Command Reference

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.

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

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.

The --embed-runtime-image-tarball flag includes a local OCI image tarball inside the function or provider package.

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:v0.42.0

Flags

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.

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

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.

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.

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.

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.

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

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:v0.42.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 render

The crossplane beta render command previews the output of a composite resource after applying any composition functions.

The crossplane beta render command connects to the locally running Docker Engine to pull and run composition functions.

Provide a composite resource, composition and composition function YAML definition with the command to render the output locally.

For example, crossplane beta 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

The crossplane beta 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.

Mock managed resources

Provide mocked, or artificial data representing a managed resource with --observed-resources. The crossplane beta 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.

beta trace

Use the crossplane beta trace command to display a visual relationship of Crossplane objects. The trace command supports claims, compositions or managed resources.

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

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                                                              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   │  ├─ VPC/platform-ref-aws-mlnwb-ckblr                         True     True    Available
 7   │  ├─ InternetGateway/platform-ref-aws-mlnwb-r7w47             True     True    Available
 8   │  ├─ Subnet/platform-ref-aws-mlnwb-lhr4h                      True     True    Available
 9   │  ├─ Subnet/platform-ref-aws-mlnwb-bss4b                      True     True    Available
10   │  ├─ Subnet/platform-ref-aws-mlnwb-fzbxx                      True     True    Available
11   │  ├─ Subnet/platform-ref-aws-mlnwb-vxbf4                      True     True    Available
12   │  ├─ RouteTable/platform-ref-aws-mlnwb-cs9nl                  True     True    Available
13   │  ├─ Route/platform-ref-aws-mlnwb-vpxdg                       True     True    Available
14   │  ├─ MainRouteTableAssociation/platform-ref-aws-mlnwb-sngx5   True     True    Available
15   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-hprsp       True     True    Available
16   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-shb8f       True     True    Available
17   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-hvb2h       True     True    Available
18   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-m58vl       True     True    Available
19   │  ├─ SecurityGroup/platform-ref-aws-mlnwb-xxbl2               True     True    Available
20   │  ├─ SecurityGroupRule/platform-ref-aws-mlnwb-7qt56           True     True    Available
21   │  └─ SecurityGroupRule/platform-ref-aws-mlnwb-szgxp           True     True    Available
22   ├─ XEKS/platform-ref-aws-mlnwb-fqjzz                           True     True    Available
23   │  ├─ Role/platform-ref-aws-mlnwb-gmpqv                        True     True    Available
24   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-t6rct        True     True    Available
25   │  ├─ Cluster/platform-ref-aws-mlnwb-crrt8                     True     True    Available
26   │  ├─ ClusterAuth/platform-ref-aws-mlnwb-dgn6f                 True     True    Available
27   │  ├─ Role/platform-ref-aws-mlnwb-tdnx4                        True     True    Available
28   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-qzljh        True     True    Available
29   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-l64q2        True     True    Available
30   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-xn2px        True     True    Available
31   │  ├─ NodeGroup/platform-ref-aws-mlnwb-4sfss                   True     True    Available
32   │  ├─ OpenIDConnectProvider/platform-ref-aws-mlnwb-h26xx       True     True    Available
33   │  └─ ProviderConfig/platform-ref-aws                          -        -
34   └─ XServices/platform-ref-aws-mlnwb-bgndx                      True     True    Available
35      ├─ Release/platform-ref-aws-mlnwb-bcj7r                     True     True    Available
36      └─ Release/platform-ref-aws-mlnwb-7hfkv                     True     True    Available

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

Print connection secrets

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

The output includes both the secret name along with the secret’s namespace.

 1NAME                                                                        SYNCED   READY   STATUS
 2Cluster/platform-ref-aws (default)                                          True     True    Available
 3└─ XCluster/platform-ref-aws-mlnwb                                          True     True    Available
 4   ├─ XNetwork/platform-ref-aws-mlnwb-6nvkx                                 True     True    Available
 5   │  ├─ SecurityGroupRule/platform-ref-aws-mlnwb-szgxp                     True     True    Available
 6   │  └─ Secret/3f11c30b-dd94-4f5b-aff7-10fe4318ab1f (upbound-system)       -        -
 7   ├─ XEKS/platform-ref-aws-mlnwb-fqjzz                                     True     True    Available
 8   │  ├─ OpenIDConnectProvider/platform-ref-aws-mlnwb-h26xx                 True     True    Available
 9   │  └─ Secret/9666eccd-929c-4452-8658-c8c881aee137-eks (upbound-system)   -        -
10   ├─ XServices/platform-ref-aws-mlnwb-bgndx                                True     True    Available
11   │  ├─ Release/platform-ref-aws-mlnwb-7hfkv                               True     True    Available
12   │  └─ Secret/d0955929-892d-40c3-b0e0-a8cabda55895 (upbound-system)       -        -
13   └─ Secret/9666eccd-929c-4452-8658-c8c881aee137 (upbound-system)          -        -

beta xpkg init

The crossplane beta 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 beta xpkg init <name> <template>

The <name> input isn’t used. Crossplane reserves the <name> for future releases.

The <template> value may be one of three well known templates:

• function-template-go - A template to build Crossplane composition functions from the crossplane/function-template-go 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.

Flags