Crossplane logo
Crossplane logo
master v1.18
Latest
v1.17 v1.16

Command Reference

On this page

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 flagLong flagDescription
-h--helpShow context sensitive help.
--verbosePrint 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 a composite resource after applying any composition functions.

Important
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.

Important
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 flagLong flagDescription
--context-files=<key>=<file>,<key>=<file>A comma separated list of files to load for function “contexts.”
--context-values=<key>=<value>,<key>=<value>A comma separated list of key-value pairs to load for function “contexts.”
-r--include-function-resultsInclude the “results” or events from the function.
-o--observed-resources=<directory or file>Provide artificial managed resource data to the function.
-e--extra-resources=PATHA YAML file or directory of YAML files specifying extra resources to pass to the Function pipeline.
-c--include-contextInclude the context in the rendered output as a resource of kind: Context.
-x--include-full-xrInclude 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 standard Docker environmental variables to 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 the status 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 an apiVersion, kind, metadata and spec.

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.

Mock Extra Resources

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 like function-extra-resources or the built-in support in function-go-templating.

xpkg

The crossplane xpkg commands create, install and update Crossplane packages 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 the Crossplane XPKG specification.

The crossplane CLI supports building configuration, function and provider package types.

Flags

Short flagLong flagDescription
--embed-runtime-image-name=NAMEThe image name and tag of an image to include in the package. Only for provider and function packages.
--embed-runtime-image-tarball=PATHThe 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=PATHDirectory 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 .yaml into 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 the metadata.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.

Upbound Marketplace uses files included with --examples-root as documentation for published packages.

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.

Note

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 command
crossplane 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:

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, the crossplane 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 flagLong flagDescription
-b--ref-nameThe branch or tag to clone from the template repository.
-d--directoryThe directory to create and load the template files into. Uses the current directory by default.
-r--run-init-scriptRun 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 version 0.42.0 of the AWS S3 provider:

crossplane xpkg install provider xpkg.upbound.io/upbound/provider-aws-s3:v1.17.0

Flags

Short flagLong flagDescription
--runtime-config=<runtime config name>Install the package with a runtime configuration.
-m--manual-activationSet the revisionActiviationPolicy to Manual.
--package-pull-secrets=<list of secrets>A comma-separated list of Kubernetes secrets to use for authenticating to the package registry.
-r--revision-history-limit=<number of revisions>Set the revisionHistoryLimit. Defaults to 1.
-w--wait=<number of seconds>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 require manual 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.

Important
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 about package revisions in the package documentation.

xpkg login

Use xpkg login to authenticate to xpkg.upbound.io, the Upbound Marketplace container registry.

Register with the Upbound Marketplace to push packages and create private repositories.

Flags

Short flagLong flagDescription
-u--username=<username>Username to use for authentication.
-p--password=<password>Password to use for authentication.
-t--token=<token string>User token string to use for authentication.
-a--account=<organization>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.

Important
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.

Note

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 login session.

Note
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.

The Crossplane CLI pushes images to the Upbound Marketplace at xpkg.upbound.io by default.

Note
Pushing a package may require authentication with crossplane xpkg login

Specify the organization, package name and tag with
crossplane 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 to crossplane-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 DockerHub provide 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 flagLong flagDescription
-f--package-files=PATHA 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>]

The package file must be an organization, image and tag on the xpkg.upbound.io registry on Upbound Marketplace.

For example, to update to version 0.42.0 of the AWS S3 provider:

crossplane xpkg update provider xpkg.upbound.io/upbound/provider-aws-s3:v1.17.0

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 existing ControllerConfig to a DeploymentRuntimeConfig or a legacy Composition using mode: Resources to a Composition 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 use crossplane 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, use crossplane 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 flagLong flagDescription
-o--output-fileThe output YAML file to write. Outputs to stdout by default.
-f--function-nameThe 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     upbound-provider-family-aws-48b3b5ccf964-76c9686b6-bgg65   2m           89Mi
Important

Using crossplane beta top requires the Kubernetes metrics server enabled on the cluster running Crossplane before using crossplane beta top.

Follow the installation instructions on the metrics-server GitHub page.

Flags

Short flagLong flagDescription
-n--namespaceThe namespace where the Crossplane pod runs. Default is crossplane-system.
-s--summaryPrint a summary of all Crossplane pods along with the output.
--verbosePrint verbose logging information with the output.

The Kubernetes metrics server may take some time to collect data for the crossplane 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 flagLong flagDescription
-n--namespaceThe namespace of the resource.
-o--output=Change the graph output with wide, json, or dot for a Graphviz dot output.
--show-connection-secretsPrint any connection secret names. Doesn’t print the secret values.
--show-package-dependencies <filter>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 <output>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-configsPrint 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 textual Graphviz 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 use dot -Tpng -o graph.png.

crossplane beta trace cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png

Use -s to print any connection secret names along with the other resources.

Important
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)          -        -

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

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 validate

The crossplane beta validate command validates compositions 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:

Note

The crossplane beta validate command performs all validation offline.

A Kubernetes cluster running Crossplane isn’t required.

Flags

Short flagLong flagDescription
-h--helpShow context sensitive help.
-v--versionPrint version and quit.
--cache-dir=".crossplane/cache"Specify the absolute path to the cache directory to store downloaded schemas.
--clean-cacheClean the cache directory before downloading package schemas.
--skip-success-resultsSkip printing success results.
--verbosePrint 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.

Important

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 the Provider AWS IAM manifest.

Tip
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.upbound.io/upbound/provider-aws-iam:v1.17.0

Now include the XR or managed resource to validate.

For example, to validate an AccessKey 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 into crossplane 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 from crossplane 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 the x-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 the replicas field of an XR is between the minReplicas and maxReplicas 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 named schemas 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 the crossplane 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