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

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

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.

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.

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.

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.

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.

NOTES.txt

init.sh

Flags

xpkg install

Flags

Wait for package install

Require manual package activation

Authenticate to a private registry

Customize the number of stored package versions

Flags

Authentication options

Authenticate with a registered Upbound organization

xpkg logout

xpkg push

Flags

xpkg update

beta

beta convert

Flags

beta top

Flags

beta trace

Flags

Output options

Wide outputs

Graphviz dot file output

Print connection secrets

Print package dependencies

Print package revisions

beta validate

Flags

Validate resources against a schema

Validate render command output

Validate Common Expression Language rules

Validate against a directory of schemas

NOTES.txt

init.sh

Flags

xpkg install

Flags

Wait for package install

Require manual package activation

Authenticate to a private registry

Customize the number of stored package versions

xpkg login

Flags

Authentication options

Authenticate with a registered Upbound organization

xpkg logout

xpkg push

Flags

xpkg update

beta

beta convert

Flags

beta top

Flags

beta trace

Flags

Output options

Wide outputs

Graphviz dot file output

Print connection secrets

Print package dependencies

Print package revisions

beta validate

Flags

Validate resources against a schema

Validate render command output

Validate Common Expression Language rules

Validate against a directory of schemas