Crossplane Docs · v1.20 · Command Reference (original) (raw)
This document is for an older version of Crossplane CLI.
This document applies to Crossplane CLI v1.20 and not to the latest release v2.3.
The crossplane CLI provides utilities to make using Crossplane easier.
Read the Crossplane CLI overview page for information on installing crossplane.
Global flags
The following flags are available for all commands.
| Short flag | Long flag | Description |
|---|---|---|
| -h | --help | Show context sensitive help. |
| --verbose | Print verbose output. |
version
The crossplane version command returns the version of Crossplane CLI and the control plane.
1crossplane version
2Client Version: v1.17.0
3Server Version: v1.17.0
render
The crossplane render command previews the output of acomposite resource after applying any composition functions.
The crossplane render command requires you to use composition functions.
The crossplane render command connects to the locally running Docker Engine to pull and run composition functions.
Running crossplane render requires Docker.
Provide a composite resource, composition and composition function YAML definition with the command to render the output locally.
For example,crossplane render xr.yaml composition.yaml function.yaml
The output includes the original composite resource followed by the generated managed resources.
1---
2apiVersion: nopexample.org/v1
3kind: XBucket
4metadata:
5 name: test-xrender
6status:
7 bucketRegion: us-east-2
8---
9apiVersion: s3.aws.upbound.io/v1beta1
10kind: Bucket
11metadata:
12 annotations:
13 crossplane.io/composition-resource-name: my-bucket
14 generateName: test-xrender-
15 labels:
16 crossplane.io/composite: test-xrender
17 ownerReferences:
18 - apiVersion: nopexample.org/v1
19 blockOwnerDeletion: true
20 controller: true
21 kind: XBucket
22 name: test-xrender
23 uid: ""
24spec:
25 forProvider:
26 region: us-east-2
Flags
| Short flag | Long flag | Description |
|---|---|---|
| --context-files==,= | A comma separated list of files to load for function “contexts.” | |
| --context-values==,= | A comma separated list of key-value pairs to load for function “contexts.” | |
| -r | --include-function-results | Include the “results” or events from the function. |
| -o | --observed-resources= | Provide artificial managed resource data to the function. |
| -e | --extra-resources=PATH | A YAML file or directory of YAML files specifying extra resources to pass to the Function pipeline. |
| -c | --include-context | Include the context in the rendered output as a resource of kind: Context. |
| -x | --include-full-xr | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. |
| --timeout= | Amount of time to wait for a function to finish. (Default 1 minute) |
The crossplane render command relies on standardDocker environmental variablesto connect to the local Docker Engine and run composition functions.
Provide function context
The --context-files and --context-values flags can provide data to a function’s context. The context is JSON formatted data.
Include function results
If a function produces Kubernetes events with statuses use the--include-function-results to print them along with the managed resource outputs.
Include the composite resource
Composition functions can only change the status field of a composite resource. By default, the crossplane render command only prints thestatus field with metadata.name.
Use --include-full-xr to print the full composite resource, including the spec and metadata fields.
Mock managed resources
Provide mocked, or artificial data representing a managed resource with--observed-resources. The crossplane render command treats the provided inputs as if they were resources in a Crossplane cluster.
A function can reference and manipulate the included resource as part of running the function.
The observed-resources may be a single YAML file with multiple resources or a directory of YAML files representing multiple resources.
Inside the YAML file include anapiVersion,kind,metadata andspec.
1apiVersion: example.org/v1alpha1
2kind: ComposedResource
3metadata:
4 name: test-render-b
5 annotations:
6 crossplane.io/composition-resource-name: resource-b
7spec:
8 coolerField: "I'm cooler!"
The schema of the resource isn’t validated and may contain any data.
Extra Resources allow a Composition to request Crossplane Objects on the cluster that aren’t part of the Composition. The --extra-resources option points at a directory containing YAML manifests of resources to mock. Use Extra Resources in combination with a function likefunction-extra-resources or the built-in support in function-go-templating.
xpkg
The crossplane xpkg commands create, install and update Crossplanepackages as well as enable authentication and publishing of Crossplane packages to a Crossplane package registry.
xpkg build
Using crossplane xpkg build provides automation and simplification to build Crossplane packages.
The Crossplane CLI combines a directory of YAML files and packages them as an OCI container image.
The CLI applies the required annotations and values to meet theCrossplane XPKG specification.
The crossplane CLI supports buildingconfiguration,function andprovider package types.
Flags
| Short flag | Long flag | Description |
|---|---|---|
| --embed-runtime-image-name=NAME | The image name and tag of an image to include in the package. Only for provider and function packages. | |
| --embed-runtime-image-tarball=PATH | The filename of an image to include in the package. Only for provider and function packages. | |
| -e | --examples-root="./examples" | The path to a directory of examples related to the package. |
| --ignore=PATH,... | List of files and directories to ignore. | |
| -o | --package-file=PATH | Directory and filename of the created package. |
| -f | --package-root="." | Directory to search for YAML files. |
The crossplane xpkg build command recursively looks in the directory set by--package-root and attempts to combine any files ending in .yml or .yamlinto a package.
All YAML files must be valid Kubernetes manifests with apiVersion, kind,metadata and spec fields.
Ignore files
Use --ignore to provide a list of files and directories to ignore.
For example,crossplane xpkg build --ignore="./test/*,kind-config.yaml"
Set the package name
crossplane automatically names the new package a combination of themetadata.name and a hash of the package contents and saves the contents in the same location as --package-root. Define a specific location and filename with --package-file or -o.
For example,crossplane xpkg build -o /home/crossplane/example.xpkg.
Include examples
Include YAML files demonstrating how to use the package with --examples-root.
Include a runtime image
Functions and Providers require YAML files describing their dependencies and settings as well as a container image for their runtime.
Using --embed-runtime-image-name runs a specified image and includes the image inside the function or provider package.
Images referenced with --embed-runtime-image-name must be in the local Docker cache.
Use docker pull to download a missing image.
The --embed-runtime-image-tarball flag includes a local OCI image tarball inside the function or provider package.
xpkg init
The crossplane xpkg init command populates the current directory with files to build a package.
Provide a name to use for the package and the package template to start from with the commandcrossplane xpkg init <name> <template>
The <name> input isn’t used. Crossplane reserves the <name> for future releases.
The <template> value may be one of four well known templates:
configuration-template- A template to build a Crossplane Configuration from the crossplane/configuration-template repository.function-template-go- A template to build Crossplane Go composition functions from the crossplane/function-template-go repository.function-template-python- A template to build Crossplane Python composition functions from the crossplane/function-template-python repository.provider-template- A template to build a basic Crossplane provider from the Crossplane/provider-template repository.provider-template-upjet- A template for building Upjet based Crossplane providers from existing Terraform providers. Copies from the upbound/upjet-provider-template repository.
Instead of a well known template the <template> value can be a git repository URL.
NOTES.txt
If the template repository contains a NOTES.txt file in its root directory, the crossplane xpkg init command prints the contents of the file to the terminal after populating the directory with the template files. This can be useful for providing information about the template.
init.sh
If the template repository contains an init.sh file in its root directory, thecrossplane xpkg init command starts a dialog after populating the directory with the template files. The dialog prompts the user if they want to view or run the script. Use the initialization script to automatically personalize the template.
Flags
| Short flag | Long flag | Description |
|---|---|---|
| -b | --ref-name | The branch or tag to clone from the template repository. |
| -d | --directory | The directory to create and load the template files into. Uses the current directory by default. |
| -r | --run-init-script | Run the init.sh script without prompting, if it exists. |
xpkg install
Download and install packages into Crossplane with crossplane xpkg install.
By default the crossplane xpkg install command uses the Kubernetes configuration defined in ~/.kube/config.
Define a custom Kubernetes configuration file location with the environmental variable KUBECONFIG.
Specify the package kind, package file and optionally a name to give the package inside Crossplane.
crossplane xpkg install <package-kind> <registry URL package name and tag> [<optional-name>]
The <package-kind> is either a configuration, function or provider.
For example, to install the latest version of theAWS S3 provider:
crossplane xpkg install provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
Flags
| Short flag | Long flag | Description |
|---|---|---|
| --runtime-config= | Install the package with a runtime configuration. | |
| -m | --manual-activation | Set the revisionActiviationPolicy to Manual. |
| --package-pull-secrets= | A comma-separated list of Kubernetes secrets to use for authenticating to the package registry. | |
| -r | --revision-history-limit= | Set the revisionHistoryLimit. Defaults to 1. |
| -w | --wait= | Number of seconds to wait for a package to install. |
Wait for package install
When installing a package the crossplane xpkg install command doesn’t wait for the package to download and install. View any download or installation problems by inspecting the configuration with kubectl describe configuration.
Use --wait to have the crossplane xpkg install command to wait for a package to have the condition HEALTHY before continuing. The command returns an error if the wait time expires before the package is HEALTHY.
Require manual package activation
Set the package to requiremanual activation, preventing an automatic upgrade of a package with --manual-activation
Authenticate to a private registry
To authenticate to a private package registry use --package-pull-secrets and provide a list of Kubernetes Secret objects.
The secrets must be in the same namespace as the Crossplane pod.
Customize the number of stored package versions
By default Crossplane only stores a single inactive package in the local package cache.
Store more inactive copies of a package with --revision-history-limit.
Read more aboutpackage revisionsin the package documentation.
xpkg login
Use xpkg login to authenticate to registries that host Crossplane packages.
Flags
| Short flag | Long flag | Description |
|---|---|---|
| -u | --username= | Username to use for authentication. |
| -p | --password= | Password to use for authentication. |
| -t | --token= | User token string to use for authentication. |
| -a | --account= | Specify an Upbound organization during authentication. |
Authentication options
The crossplane xpkg login command can use a username and password or Upbound API token.
By default, crossplane xpkg login without arguments, prompts for a username and password.
Provide a username and password with the --username and --password flags or set the environmental variable UP_USER for a username or UP_PASSWORD for the password.
Use an Upbound user token instead of a username and password with --token or the UP_TOKEN environmental variable.
The --token or UP_TOKEN environmental variables take precedence over a username and password.
Using - as the input for --password or --token reads the input from stdin. For example, crossplane xpkg login --password -.
After logging in the Crossplane CLI creates a profile in.crossplane/config.json to cache unprivileged account information.
The session field of config.json file is a session cookie identifier.
The session value isn’t used for authentication. This isn’t a token.
Authenticate with a registered Upbound organization
Authenticate to a registered organization in the Upbound Marketplace with the--account option, along with the username and password or token.
For example,crossplane xpkg login --account=Upbound --username=my-user --password -.
xpkg logout
Use crossplane xpkg logout to invalidate the current crossplane xpkg loginsession.
Using crossplane xpkg logout removes the session from the~/.crossplane/config.json file, but doesn’t delete the configuration file.
xpkg push
Push a Crossplane package file to a package registry.
Pushing a package may require authentication withcrossplane xpkg login
Specify the organization, package name and tag withcrossplane xpkg push <package>
By default the command looks in the current directory for a single .xpkg file to push.
To push multiple files or to specify a specific .xpkg file use the -f flag.
For example, to push a local package named my-package tocrossplane-docs/my-package:v0.14.0 use:
crossplane xpkg push -f my-package.xpkg crossplane-docs/my-package:v0.14.0
To push to another package registry, like DockerHubprovide the full URL along with the package name.
For example, to push a local package named my-package to DockerHub organization crossplane-docs/my-package:v0.14.0 use:crossplane xpkg push -f my-package.xpkg index.docker.io/crossplane-docs/my-package:v0.14.0.
Flags
| Short flag | Long flag | Description |
|---|---|---|
| -f | --package-files=PATH | A comma-separated list of xpkg files to push. |
xpkg update
The crossplane xpkg update command downloads and updates an existing package.
By default the crossplane xpkg update command uses the Kubernetes configuration defined in ~/.kube/config.
Define a custom Kubernetes configuration file location with the environmental variable KUBECONFIG.
Specify the package kind, package file and optionally the name of the package already installed in Crossplane.
crossplane xpkg update <package-kind> <registry package name and tag> [<optional-name>]
For example, to update to the latest version of theAWS S3 provider:
crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
beta
Crossplane beta commands are experimental. These commands may change the flags, options or outputs in future releases.
Crossplane maintainers may promote or remove commands under beta in future releases.
beta convert
As Crossplane evolves, its APIs and resources may change. To help with the migration to the new APIs and resources, the crossplane beta convert command converts a Crossplane resource to a new version or kind.
Use the crossplane beta convert command to convert an existingControllerConfigto a DeploymentRuntimeConfigor a legacy Composition using mode: Resources to aComposition pipeline function.
Provide the crossplane beta convert command the conversion type, the input file and optionally, an output file. By default the command writes the output to standard out.
For example, to convert a ControllerConfig to a DeploymentRuntimeConfig usecrossplane beta convert deployment-runtime. For example,
crossplane beta convert deployment-runtime controllerConfig.yaml -o deploymentConfig.yaml
To convert a Composition using patch and transforms to a pipeline function, usecrossplane beta convert pipeline-composition.
Optionally, use the -f flag to provide the name of the function. By default the function name is “function-patch-and-transform.”
crossplane beta convert pipeline-composition oldComposition.yaml -o newComposition.yaml -f patchFunctionName
Flags
| Short flag | Long flag | Description |
|---|---|---|
| -o | --output-file | The output YAML file to write. Outputs to stdout by default. |
| -f | --function-name | The name of the new function. Defaults to function-patch-and-transform. |
beta top
The command crossplane beta top shows CPU and memory usage of Crossplane related pods.
1crossplane beta top
2TYPE NAMESPACE NAME CPU(cores) MEMORY
3crossplane default crossplane-f98f9ddfd-tnm46 4m 32Mi
4crossplane default crossplane-rbac-manager-74ff459b88-94p8p 4m 14Mi
5provider default provider-aws-s3-1f1a3fb08cbc-5c49d84447-sggrq 3m 108Mi
6provider default crossplane-contrib-provider-family-aws-48b3b5ccf964-76c9686b6-bgg65 2m 89Mi
Using crossplane beta top requires the Kubernetesmetrics server enabled on the cluster running Crossplane before using crossplane beta top.
Follow the installation instructions on themetrics-server GitHub page.
Flags
| Short flag | Long flag | Description |
|---|---|---|
| -n | --namespace | The namespace where the Crossplane pod runs. Default is crossplane-system. |
| -s | --summary | Print a summary of all Crossplane pods along with the output. |
| --verbose | Print verbose logging information with the output. |
The Kubernetes metrics server may take some time to collect data for thecrossplane beta top command. Before the metrics server is ready, running the top command may produce an error, for example,
crossplane: error: error adding metrics to pod, check if metrics-server is running or wait until metrics are available for the pod: the server is currently unable to handle the request (get pods.metrics.k8s.io crossplane-contrib-provider-helm-b4cc4c2c8db3-6d787f9686-qzmz2)
beta trace
Use the crossplane beta trace command to display a visual relationship of Crossplane objects. The trace command supports claims, compositions, functions, managed resources or packages.
The command requires a resource type and a resource name.
crossplane beta trace <resource kind> <resource name>
For example to view a resource named my-claim of type example.crossplane.io:crossplane beta trace example.crossplane.io my-claim
The command also accepts Kubernetes CLI style <kind>/<name> input. For example,crossplane beta trace example.crossplane.io/my-claim
By default the crossplane beta trace command uses the Kubernetes configuration defined in ~/.kube/config.
Define a custom Kubernetes configuration file location with the environmental variable KUBECONFIG.
Flags
| Short flag | Long flag | Description |
|---|---|---|
| -n | --namespace | The namespace of the resource. |
| -o | --output= | Change the graph output with wide, json, or dot for a Graphviz dot output. |
| --show-connection-secrets | Print any connection secret names. Doesn’t print the secret values. | |
| --show-package-dependencies | Show package dependencies. Options are all to show every dependency, unique to only print a package once or none to not print any dependencies. By default the trace command uses --show-package-dependencies unique. | |
| --show-package-revisions | Print package revision versions. Options are active, showing only the active revisions, all showing all revisions or none to print not print any revisions. | |
| --show-package-runtime-configs | Print DeploymentRuntimeConfig dependencies. |
Output options
By default crossplane beta trace prints directly to the terminal, limiting the “Ready” condition and “Status” messages to 64 characters.
The following an example output a “cluster” claim from the AWS reference platform, which includes multiple Compositions and composed resources:
1crossplane beta trace cluster.aws.platformref.upbound.io platform-ref-aws
2NAME VERSION INSTALLED HEALTHY STATE STATUS
3Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
4├─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
5├─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
6│ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
7│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
8│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
9│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
10│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
11│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
12│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
13├─ Configuration/upbound-configuration-aws-database v0.5.0 True True - HealthyPackageRevision
14│ ├─ ConfigurationRevision/upbound-configuration-aws-database-3112f0a765c5 v0.5.0 - True Active HealthyPackageRevision
15│ └─ Provider/upbound-provider-aws-rds v0.47.0 True True - HealthyPackageRevision
16│ └─ ProviderRevision/upbound-provider-aws-rds-58f96aa9fc4b v0.47.0 - True Active HealthyPackageRevision
17├─ Configuration/upbound-configuration-aws-eks v0.5.0 True True - HealthyPackageRevision
18│ ├─ ConfigurationRevision/upbound-configuration-aws-eks-83c9d65f4a47 v0.5.0 - True Active HealthyPackageRevision
19│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
20│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
21│ ├─ Provider/crossplane-contrib-provider-kubernetes v0.10.0 True True - HealthyPackageRevision
22│ │ └─ ProviderRevision/crossplane-contrib-provider-kubernetes-63506a3443e0 v0.10.0 - True Active HealthyPackageRevision
23│ ├─ Provider/upbound-provider-aws-eks v0.47.0 True True - HealthyPackageRevision
24│ │ └─ ProviderRevision/upbound-provider-aws-eks-641a096d79d8 v0.47.0 - True Active HealthyPackageRevision
25│ └─ Provider/upbound-provider-aws-iam v0.47.0 True True - HealthyPackageRevision
26│ └─ ProviderRevision/upbound-provider-aws-iam-438eac423037 v0.47.0 - True Active HealthyPackageRevision
27├─ Configuration/upbound-configuration-app v0.2.0 True True - HealthyPackageRevision
28│ └─ ConfigurationRevision/upbound-configuration-app-5d95726dba8c v0.2.0 - True Active HealthyPackageRevision
29├─ Configuration/upbound-configuration-observability-oss v0.2.0 True True - HealthyPackageRevision
30│ ├─ ConfigurationRevision/upbound-configuration-observability-oss-a51529457ad7 v0.2.0 - True Active HealthyPackageRevision
31│ └─ Provider/grafana-provider-grafana v0.8.0 True True - HealthyPackageRevision
32│ └─ ProviderRevision/grafana-provider-grafana-ac529c8ce1c6 v0.8.0 - True Active HealthyPackageRevision
33└─ Configuration/upbound-configuration-gitops-flux v0.2.0 True True - HealthyPackageRevision
34 └─ ConfigurationRevision/upbound-configuration-gitops-flux-2e80ec62738d v0.2.0 - True Active HealthyPackageRevision
Wide outputs
Print the entire “Ready” or “Status” message if they’re longer than 64 characters with --output=wide.
For example, the output truncates the “Status” message that’s too long.
1crossplane trace cluster.aws.platformref.upbound.io platform-ref-aws
2NAME SYNCED READY STATUS
3Cluster/platform-ref-aws (default) True False Waiting: ...resource claim is waiting for composite resource to become Ready
Use --output=wide to see the full message.
1crossplane trace cluster.aws.platformref.upbound.io platform-ref-aws --output=wide
2NAME SYNCED READY STATUS
3Cluster/platform-ref-aws (default) True False Waiting: Composite resource claim is waiting for composite resource to become Ready
Graphviz dot file output
Use the --output=dot to print out a textualGraphviz dot output.
Save the output and export it or the output directly to Graphviz dot to render an image.
For example, to save the output as a graph.png file usedot -Tpng -o graph.png.
crossplane beta trace cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png
Print connection secrets
Use -s to print any connection secret names along with the other resources.
The crossplane beta trace command doesn’t print secret values.
The output includes both the secret name along with the secret’s namespace.
1crossplane beta trace configuration platform-ref-aws -s
2NAME SYNCED READY STATUS
3Cluster/platform-ref-aws (default) True True Available
4└─ XCluster/platform-ref-aws-mlnwb True True Available
5 ├─ XNetwork/platform-ref-aws-mlnwb-6nvkx True True Available
6 │ ├─ SecurityGroupRule/platform-ref-aws-mlnwb-szgxp True True Available
7 │ └─ Secret/3f11c30b-dd94-4f5b-aff7-10fe4318ab1f (upbound-system) - -
8 ├─ XEKS/platform-ref-aws-mlnwb-fqjzz True True Available
9 │ ├─ OpenIDConnectProvider/platform-ref-aws-mlnwb-h26xx True True Available
10 │ └─ Secret/9666eccd-929c-4452-8658-c8c881aee137-eks (upbound-system) - -
11 ├─ XServices/platform-ref-aws-mlnwb-bgndx True True Available
12 │ ├─ Release/platform-ref-aws-mlnwb-7hfkv True True Available
13 │ └─ Secret/d0955929-892d-40c3-b0e0-a8cabda55895 (upbound-system) - -
14 └─ Secret/9666eccd-929c-4452-8658-c8c881aee137 (upbound-system) - -
Print package dependencies
Use the --show-package-dependencies flag to include more information about package dependencies.
By default crossplane beta trace uses --show-package-dependencies unique to include a required package only once in the output.
Use --show-package-dependencies all to see every package requiring the same dependency.
1crossplane beta trace configuration platform-ref-aws --show-package-dependencies all
2NAME VERSION INSTALLED HEALTHY STATE STATUS
3Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
4├─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
5├─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
6│ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
7│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
8│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
9│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
10│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
11│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
12│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
13├─ Configuration/upbound-configuration-aws-database v0.5.0 True True - HealthyPackageRevision
14│ ├─ ConfigurationRevision/upbound-configuration-aws-database-3112f0a765c5 v0.5.0 - True Active HealthyPackageRevision
15│ ├─ Provider/upbound-provider-aws-rds v0.47.0 True True - HealthyPackageRevision
16│ │ ├─ ProviderRevision/upbound-provider-aws-rds-58f96aa9fc4b v0.47.0 - True Active HealthyPackageRevision
17│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
18│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
19│ └─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
20│ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
21│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
22│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
23│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
24│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
25│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
26│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
27├─ Configuration/upbound-configuration-aws-eks v0.5.0 True True - HealthyPackageRevision
28│ ├─ ConfigurationRevision/upbound-configuration-aws-eks-83c9d65f4a47 v0.5.0 - True Active HealthyPackageRevision
29│ ├─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
30│ │ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
31│ │ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
32│ │ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
33│ │ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
34│ │ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
35│ │ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
36│ │ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
37│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
38│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
39│ ├─ Provider/crossplane-contrib-provider-kubernetes v0.10.0 True True - HealthyPackageRevision
40│ │ └─ ProviderRevision/crossplane-contrib-provider-kubernetes-63506a3443e0 v0.10.0 - True Active HealthyPackageRevision
41│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
42│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
43│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
44│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
45│ ├─ Provider/upbound-provider-aws-eks v0.47.0 True True - HealthyPackageRevision
46│ │ ├─ ProviderRevision/upbound-provider-aws-eks-641a096d79d8 v0.47.0 - True Active HealthyPackageRevision
47│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
48│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
49│ ├─ Provider/upbound-provider-aws-iam v0.47.0 True True - HealthyPackageRevision
50│ │ ├─ ProviderRevision/upbound-provider-aws-iam-438eac423037 v0.47.0 - True Active HealthyPackageRevision
51│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
52│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
53│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
54│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
55├─ Configuration/upbound-configuration-app v0.2.0 True True - HealthyPackageRevision
56│ ├─ ConfigurationRevision/upbound-configuration-app-5d95726dba8c v0.2.0 - True Active HealthyPackageRevision
57│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
58│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
59│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
60│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
61├─ Configuration/upbound-configuration-observability-oss v0.2.0 True True - HealthyPackageRevision
62│ ├─ ConfigurationRevision/upbound-configuration-observability-oss-a51529457ad7 v0.2.0 - True Active HealthyPackageRevision
63│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
64│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
65│ ├─ Provider/crossplane-contrib-provider-kubernetes v0.10.0 True True - HealthyPackageRevision
66│ │ └─ ProviderRevision/crossplane-contrib-provider-kubernetes-63506a3443e0 v0.10.0 - True Active HealthyPackageRevision
67│ ├─ Provider/grafana-provider-grafana v0.8.0 True True - HealthyPackageRevision
68│ │ └─ ProviderRevision/grafana-provider-grafana-ac529c8ce1c6 v0.8.0 - True Active HealthyPackageRevision
69│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
70│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
71└─ Configuration/upbound-configuration-gitops-flux v0.2.0 True True - HealthyPackageRevision
72 ├─ ConfigurationRevision/upbound-configuration-gitops-flux-2e80ec62738d v0.2.0 - True Active HealthyPackageRevision
73 ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
74 │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
75 └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
76 └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
Use --show-package-dependencies none to hide all dependencies.
1crossplane beta trace configuration platform-ref-aws --show-package-dependencies none
2NAME VERSION INSTALLED HEALTHY STATE STATUS
3Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
4└─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
Print package revisions
By default the crossplane beta trace command only shows the package revisions actively in use. To view both active and inactive revisions use--show-package-revisions all.
1crossplane beta trace configuration platform-ref-aws --show-package-revisions all
2NAME VERSION INSTALLED HEALTHY STATE STATUS
3Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
4├─ ConfigurationRevision/platform-ref-aws-ad01153c1179 v0.8.0 - True Inactive HealthyPackageRevision
5├─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
6├─ Configuration/upbound-configuration-aws-network v0.2.0 True True - HealthyPackageRevision
7│ ├─ ConfigurationRevision/upbound-configuration-aws-network-288fcd1b88dd v0.2.0 - True Active HealthyPackageRevision
8│ └─ Provider/upbound-provider-aws-ec2 v1.0.0 True True - HealthyPackageRevision
9│ ├─ ProviderRevision/upbound-provider-aws-ec2-5cfd948d082f v1.0.0 - True Active HealthyPackageRevision
10│ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
11│ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
12# Removed for brevity
To hide all revisions use --show-package-revision none.
1crossplane beta trace configuration platform-ref-aws --show-package-revisions none
2NAME VERSION INSTALLED HEALTHY STATE STATUS
3Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
4├─ Configuration/upbound-configuration-aws-network v0.2.0 True True - HealthyPackageRevision
5│ └─ Provider/upbound-provider-aws-ec2 v1.0.0 True True - HealthyPackageRevision
6│ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
7# Removed for brevity
beta upgrade check
The crossplane beta upgrade check command inspects a live Crossplane v1.xcontrol plane and reports any usage of features that v2 removes or changes the behavior of. Run it against a cluster before upgrading to see what would break.
crossplane beta upgrade check only reads from a cluster. It never creates, modifies, or deletes resources.
Run it against a Crossplane v1.x control plane. The command looks for the v2breaking changes, so there’s nothing to scan on a cluster already running v2.
The command looks for:
- Native patch and transform Compositions, which v2 removes in favor ofcomposition functions.
ControllerConfigusage, including Providers and Functions that still reference one. v2 removes the type in favor ofDeploymentRuntimeConfig.- External secret stores, an alpha feature that v2 removes.
- Composite resource connection details. v2 keeps these working for legacy XRs, so the command reports them as informational rather than as a blocker.
- Unqualified package sources, which break because v2 removes the default registry and requires fully qualified package references.
By default the command uses the Kubernetes configuration in ~/.kube/config and sweeps the entire control plane: cluster-scoped resources and all namespaces. Use--kubeconfig and --context to target a specific cluster. For example,crossplane beta upgrade check --kubeconfig ~/.kube/prod.yaml --context prod.
Use --namespace to restrict namespaced checks, like Claims, to a single namespace. For example,crossplane beta upgrade check --namespace team-a. Cluster scoped checks still run, regardless of the --namespace flag value.
The command groups its findings and marks each with a severity. Issue findings ([✗]), along with any checks that fail to complete, cause the command to return a nonzero exit code so you can use it in CI. Informational findings ([i]) don’t change the exit code. Use -o json for JSON output suited to automation. For example, crossplane beta upgrade check -o json.
1crossplane beta upgrade check
2[✗] 4 issues, 0 informational, 0 incomplete checks.
3
4[✗] Native patch-and-transform Compositions - 3 issues
5 │
6 │ Crossplane v2 removes native patch-and-transform (P&T) Composition. Compositions must use mode: Pipeline with Composition Functions.
7 │ Fix: Migrate to Composition Functions (spec.mode: Pipeline with spec.pipeline steps). Run "crossplane beta convert pipeline-composition" to convert existing Compositions.
8 │ Docs: https://docs.crossplane.io/latest/guides/upgrade-to-crossplane-v2/#native-patch-and-transform-composition
9 │ https://docs.crossplane.io/v1.20/cli/command-reference/#beta-convert
10 │
11 │ NAME FIELD
12 │ composition.apiextensions.crossplane.io/nativepnt-composition .spec.mode
13 │ composition.apiextensions.crossplane.io/nativepnt-composition .spec.patchSets
14 │ composition.apiextensions.crossplane.io/nativepnt-composition .spec.resources
15 └──
16[✓] ControllerConfig usage
17[✗] External secret stores - 1 issue
18 │
19 │ Crossplane v2 removes support for external secret stores. Publish connection details as Kubernetes Secrets composed by your Compositions, or adopt External Secrets Operator if
20 │ you need an external store.
21 │ Fix: Disable --enable-external-secret-stores on the Crossplane Deployment, replace StoreConfig-based publishing with composed Kubernetes Secrets (or adopt External Secrets
22 │ Operator), then delete StoreConfig resources. No automated converter exists.
23 │ Docs: https://docs.crossplane.io/latest/guides/upgrade-to-crossplane-v2/#external-secret-stores
24 │ https://docs.crossplane.io/latest/guides/connection-details-composition
25 │ https://github.com/external-secrets/external-secrets
26 │
27 │ NAMESPACE NAME FIELD
28 │ crossplane-system deployment.apps/crossplane .spec.template.spec.containers[0].args
29 └──
30[✓] Composite resource connection details
31[✓] Unqualified package sources
32
33crossplane: error: blockers found
Flags
| Short flag | Long flag | Description |
|---|---|---|
| --kubeconfig | Path to the kubeconfig file. Defaults to $KUBECONFIG or ~/.kube/config. | |
| -c | --context | Kubernetes context to use from the kubeconfig. |
| -n | --namespace | Restrict namespaced checks to a single namespace. Defaults to all namespaces. |
| --crossplane-namespace | Namespace where the Crossplane Deployment runs. Default is crossplane-system. | |
| --crossplane-selector | Label selector for the Crossplane Deployment. Default is app=crossplane. | |
| -o | --output | Output format. One of text or json. Default is text. |
| --skip-managed-resources | Skip scanning managed resources for external secret stores usage. Speeds up the command on clusters with large numbers of provider CRDs. | |
| --concurrency | Maximum number of resources to process in parallel. Default is 10. | |
| --verbose | Print verbose logging information with the output. |
Tune performance and control plane load
Scanning every managed resource for external secret stores usage is the most expensive part of the run on clusters with large numbers of provider CRDs. Two flags let you trade run time against the load the command puts on your API server.
Use --skip-managed-resources to skip the managed resource scan entirely. The command still inspects StoreConfig resources, the Crossplane Deployment, and composite resources for external secret stores usage, but doesn’t scan managed resources. Skipping it gives the biggest reduction in run time, at the cost of not catching external secret stores usage on managed resources.
Use --concurrency (default 10) to limit the number of resources the command processes in parallel:
- Lower it, for example
--concurrency 2, to put less load on the API server and slow the run down. This helps when you run against a busy production control plane that you don’t want to overload. - Raise it to finish faster, at the cost of more load on the API server.
beta validate
The crossplane beta validate command validatescompositions against provider or XRD schemas using the Kubernetes API server’s validation library with extra validation such as checking for unknown fields, a common source of difficult to debug issues in Crossplane.
The crossplane beta validate command supports validating the following scenarios:
- Validate a managed resource or composite resourceagainst a Provider or XRD schema.
- Use the output of
crossplane renderas validation input. - Validate an XRD against Kubernetes Common Expression Language(CEL) rules.
- Validate resources against a directory of schemas.
The crossplane beta validate command performs all validation offline.
A Kubernetes cluster running Crossplane isn’t required.
Flags
| Short flag | Long flag | Description |
|---|---|---|
| -h | --help | Show context sensitive help. |
| -v | --version | Print version and quit. |
| --cache-dir=".crossplane/cache" | Specify the absolute path to the cache directory to store downloaded schemas. | |
| --clean-cache | Clean the cache directory before downloading package schemas. | |
| --skip-success-results | Skip printing success results. | |
| --error-on-missing-schemas | Return a non zero exit code if any schemas are missing. | |
| --verbose | Print verbose logging statements. |
Validate resources against a schema
The crossplane beta validate command can validate an XR and one or more managed resources against a provider’s schema.
When validating against a provider the crossplane beta validate command downloads the provider package to the --cache-dir directory. By default Crossplane uses .crossplane as the --cache-dir location.
Access to a Kubernetes cluster or Crossplane pod isn’t required. Validation requires the ability to download the provider package.
The crossplane beta validate command downloads and caches the schema CRD files in the --cache-dir directory. By default the Crossplane CLI uses.crossplane/cache as the cache location.
To clear the cache and download the CRD files again use the --clean-cache flag.
To validate a managed resource against a provider, first, create a provider manifest file. For example, to validate an IAM role from Provider AWS, use theProvider AWS IAMmanifest.
To validate a “family provider” use the provider manifests of the resources to validate.
1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4 name: provider-aws-iam
5spec:
6 package: xpkg.crossplane.io/crossplane-contrib/provider-aws-iam:v1.21.1
Now include the XR or managed resource to validate.
For example, to validate anAccessKey managed resource, provide a managed resource YAML file.
1apiVersion: iam.aws.upbound.io/v1beta1
2kind: AccessKey
3metadata:
4 name: sample-access-key-0
5spec:
6 forProvider:
7 userSelector:
8 matchLabels:
9 example-name: test-user-0
Run the crossplane beta validate command providing the provider and managed resource YAML files as input.
1crossplane beta validate provider.yaml managedResource.yaml
2[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
3Total 1 resources: 0 missing schemas, 1 success case, 0 failure cases
Validate render command output
You can pipe the output of crossplane render intocrossplane beta validate to validate complete Crossplane resource pipelines, including XRs, compositions and composition functions.
Use the --include-full-xr command with crossplane render and the -option with crossplane beta validate to pipe the output fromcrossplane render to the input of crossplane beta validate.
1crossplane render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml -
2[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
3[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Required value
4[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
5[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-1 validated successfully
6[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-0 validated successfully
7[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
8Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
Validate Common Expression Language rules
XRDs can define validation rules expressed in the Common Expression Language (CEL).
Apply a CEL rule with thex-kubernetes-validations key inside the schema spec object of an XRD.
1apiVersion: apiextensions.crossplane.io/v1
2kind: CompositeResourceDefinition
3metadata:
4 name: myXR.crossplane.io
5spec:
6# Removed for brevity
7 openAPIV3Schema:
8 type: object
9 properties:
10 spec:
11 type: object
12 x-kubernetes-validations:
13 - rule: "self.minReplicas <= self.replicas && self.replicas <= self.maxReplicas"
14 message: "replicas should be in between minReplicas and maxReplicas."
15 properties:
16 minReplicas:
17 type: integer
18 maxReplicas:
19 type: integer
20 replicas:
21 type: integer
22# Removed for brevity
The rule in this example checks that the vale of thereplicas field of an XR is between the minReplicas andmaxReplicas values.
1apiVersion: example.crossplane.io/v1beta1
2kind: XR
3metadata:
4 name: example
5spec:
6 replicas: 49
7 minReplicas: 1
8 maxReplicas: 30
Running crossplane beta validate with the example XRD and XR produces an error.
1`crossplane beta validate xrd.yaml xr.yaml
2[x] CEL validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Invalid value: "object": replicas should be in between minReplicas and maxReplicas.
3Total 1 resources: 0 missing schemas, 0 success cases, 1 failure cases
Validate against a directory of schemas
The crossplane render command can validate a directory of YAML files.
The command only processes .yaml and .yml files, while ignoring all other file types.
With a directory of files, provide the directory and resource to validate.
For example, using a directory namedschemas containing the XRD and Provider schemas.
1tree
2schemas
3|-- platform-ref-aws.yaml
4|-- providers
5| |-- a.txt
6| `-- provider-aws-iam.yaml
7`-- xrds
8 `-- xrd.yaml
Provide the directory name and a resource YAML file to thecrossplane beta validate command.
1crossplane beta validate schema resources.yaml
2[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
3[x] CEL validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Invalid value: "object": no such key: minReplicas evaluating rule: replicas should be greater than or equal to minReplicas.
4[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
5[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-1 validated successfully
6[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-0 validated successfully
7[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
8Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases