This documentation is for the crossplane CLI v2.3.0.

crossplane

A command line tool for interacting with Crossplane.

Please report issues and feature requests at https://github.com/crossplane/cli.

Usage

crossplane  <command> [flags]

Flags

crossplane cluster

[BETA] Inspect a Crossplane cluster.

Usage

crossplane cluster <command> [flags]

crossplane cluster top

[BETA] Display resource (CPU/memory) usage by Crossplane related pods.

The cluster top command returns current resource usage (CPU and memory) by Crossplane pods. Like kubectl top pods, it requires the Metrics Server.

Examples

Show resource usage for all Crossplane pods in the crossplane-system namespace:

1crossplane cluster top

Show resource usage for all Crossplane pods in the default namespace:

1crossplane cluster top -n default

Add a summary of resource usage for all Crossplane pods on top of the results:

1crossplane cluster top -s

Usage

crossplane cluster top [flags]

Flags

crossplane completions

Get shell (bash/zsh/fish) completions. You can source this command to get completions for the login shell. Example: ‘source <(crossplane completions)’

Usage

crossplane completions [flags]

Flags

crossplane composition

Work with Crossplane Compositions.

Usage

crossplane composition <command> [flags]

crossplane composition convert

[BETA] Convert a Composition to a newer version.

The composition convert command converts a Crossplane composition to use a different version or migrate away from features that are no longer supported.

The supported conversions are:

• Native Composition Environment → function-environment-configs

Usage

crossplane composition convert <command>

crossplane composition convert composition-environment

[BETA] Convert a Pipeline Composition to use function-environment-configs.

The composition convert composition-environment command converts a Crossplane Composition to use function-environment-configs in place of native Composition Environments (removed in Crossplane 1.18).

It adds a function pipeline step using crossplane-contrib/function-environment-configs if needed. By default the function name is function-environment-configs, but this can be overridden with --function-environment-configs-ref.

Examples

Convert an existing pipeline mode Composition using native Composition Environment to function-environment-configs:

1crossplane composition convert composition-environment composition.yaml \
2  -o composition-environment.yaml

Use a different functionRef and output to stdout:

1crossplane composition convert composition-environment composition.yaml \
2  --function-environment-configs-ref=local-function-environment-configs

Read a composition from stdin and output the updated composition on stdout:

1cat composition.yaml | crossplane composition convert composition-environment

Usage

crossplane composition convert composition-environment [<input-file>] [flags]

Arguments

Flags

crossplane composition generate

[BETA] Generate a Composition for a CompositeResourceDefinition (XRD).

The composition generate command creates a Composition for a CompositeResourceDefinition (XRD). The generated Composition contains a single pipeline step that runs function-auto-ready, which is automatically added to the project’s dependencies if it isn’t already present.

Examples

Generate a Composition from a CompositeResourceDefinition (XRD) and save it next to the XRD under the project’s APIs directory:

1crossplane composition generate apis/network/definition.yaml

Generate a Composition with a custom name prefix:

1crossplane composition generate examples/network/network-aws.yaml --name aws

Generate a Composition with a custom plural form, useful when automatic pluralization is wrong (for example, “postgres”):

1crossplane composition generate examples/database/database.yaml --plural postgreses

Write the generated Composition to a specific path:

1crossplane composition generate apis/network/definition.yaml --path apis/network/composition.yaml

Usage

crossplane composition generate <xrd> [flags]

Arguments

Flags

crossplane composition render

Render a composite resource (XR).

The composition render command shows you what resources a Composition would create or mutate by running the composition locally and printing its results. It also prints any changes to the status of the XR. It runs the Crossplane render engine (either in a Docker container or via a local binary) to produce high-fidelity output that matches what the real reconciler would produce.

By default, render prints only the status and metadata.name of the XR. Use --include-full-xr (-x) to include the full XR spec and metadata.

Function runtime configuration

By default, the render command pulls and runs Composition Functions using Docker. You can add the following annotations to each Function to change how they’re run:

Use the standard DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, and DOCKER_TLS_VERIFY environment variables to configure how this command connects to the Docker daemon. See the Docker environment variables reference.

Project support

When running render in a Crossplane Project (any directory containing a crossplane-project.yaml project metadata file), you may omit the functions file argument in favor of using function dependencies defined in the project metadata and embedded functions from the project.

Function context

The --context-files and --context-values flags pass data to each Function’s context. The context is JSON-formatted data.

Function results

If a Function emits events with statuses, use --include-function-results (-r) to print them alongside the rendered resources.

Observed (mock) resources

--observed-resources (-o) lets you pass mocked managed resources to the Function pipeline. render treats those inputs as if they were resources observed in a Crossplane cluster, so Functions can reference and manipulate them.

The argument may be a single YAML file containing multiple resources or a directory of YAML files. The schema of the mocked resources isn’t validated and may contain any data.

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!"

Required (extra) resources

Required resources let a Composition request Crossplane objects on the cluster that aren’t part of the Composition. Pass them with --required-resources (-e), a YAML file or directory of YAML files of resources to mock. Use this with a Function like function-extra-resources or the built-in support in function-go-templating.

Examples

Simulate creating a new XR:

1crossplane composition render xr.yaml composition.yaml functions.yaml

Simulate updating an XR that already exists:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  --observed-resources=existing-observed-resources.yaml

Pin the Crossplane version used for rendering:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  --crossplane-version=v2.3.0

Use a local crossplane binary instead of Docker:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  --crossplane-binary=/usr/local/bin/crossplane

Pass context values to the Function pipeline:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  --context-values=apiextensions.crossplane.io/environment='{"key": "value"}'

Pass required resources Functions in the pipeline can request:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  --required-resources=required-resources.yaml

Pass OpenAPI schemas for Functions that need them:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  --required-schemas=schemas/

Pass credentials to Functions in the pipeline that need them:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  --function-credentials=credentials.yaml

Override function annotations for a remote Docker daemon:

1DOCKER_HOST=tcp://192.168.1.100:2376 crossplane composition render xr.yaml composition.yaml functions.yaml \
2  -a render.crossplane.io/runtime-docker-publish-address=0.0.0.0 \
3  -a render.crossplane.io/runtime-docker-target=192.168.1.100

Force all functions to use development runtime:

1crossplane composition render xr.yaml composition.yaml functions.yaml \
2  -a render.crossplane.io/runtime=Development \
3  -a render.crossplane.io/runtime-development-target=localhost:9444

Usage

crossplane composition render <composite-resource> <composition> [<functions>] [flags]

Arguments

Flags

crossplane config

View and update the crossplane CLI configuration file.

The config command manages the configuration file for the crossplane CLI. The configuration file location is, in priority order:

1. The --config flag.
2. The CROSSPLANE_CONFIG environment variable.
3. $XDG_CONFIG_HOME/crossplane/config.yaml (or ~/.config/crossplane/config.yaml).

Examples

Show the current effective configuration:

1crossplane config view

Enable alpha commands:

1crossplane config set features.enableAlpha true

Usage

crossplane config <command> [flags]

crossplane config set

Set a value and write it to the configuration file.

Usage

crossplane config set <key> <value>

Arguments

crossplane config view

Print the current effective configuration as YAML.

Usage

crossplane config view

crossplane dependency

[BETA] Manage dependencies of control plane Projects.

Usage

crossplane dependency <command> [flags]

crossplane dependency add

[BETA] Add a dependency to the current project.

The dependency add command adds a dependency to a Crossplane Project metadata file and generates language bindings (schemas) for the dependency package’s CRDs.

Dependency types

Projects support three kinds of dependencies:

• Crossplane packages from an OCI registry (xpkgs).
• Arbitrary CRDs fetched from either an HTTP(S) URL or a Git repository.
• Kubernetes core APIs.

An xpkg dependency may be either a runtime dependency (the default) or a build-time dependency. Runtime dependencies become dependencies of the Configuration produced by crossplane project build or crossplane project run and are thus installed into a cluster with the Configuration. Build-time dependencies have schemas generated but don’t become Configuration dependencies. Use the --api-only flag to add a build-time xpkg dependency.

Non-xpkg dependencies are always build-time dependencies.

Examples

Retrieve the latest available semantic version of provider-aws-eks, generate schemas for its CRDs, and add it to the project as a runtime dependency:

1crossplane dependency add xpkg.crossplane.io/crossplane-contrib/provider-aws-eks

Retrieve the latest available version greater than v1.1.0 of provider-gcp-storage, generate schemas for its CRDs, and add it to the project as a build-time only dependency:

1crossplane dependency add --api-only 'xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:>v1.1.0'

Generate schemas for the core resources from Kubernetes v1.33.0 and add it to the project as a build-time dependency:

1crossplane dependency add k8s:v1.33.0

Generate schemas for a specific CRD from an HTTP URL and add it to the project as a build-time dependency:

1crossplane dependency add https://raw.githubusercontent.com/cert-manager/cert-manager/refs/heads/master/deploy/crds/cert-manager.io_certificaterequests.yaml

Generate schemas for CRDs from a specific subdirectory of a git repository and add it to the project as a build-time dependency:

1crossplane dependency add https://github.com/kubernetes-sigs/cluster-api \
2    --git-ref=release-1.11 --git-path=config/crd/bases

Usage

crossplane dependency add <package> [flags]

Arguments

Flags

crossplane dependency clean-cache

[BETA] Clean the dependency cache.

The clean-cache command removes all cached package images from the local cache directory and removes generated schemas. This can help free up disk space, force re-generation of schemas, or resolve issues with corrupted cache entries.

Usage

crossplane dependency clean-cache [flags]

Flags

crossplane dependency update-cache

[BETA] Update the dependency cache for the current project.

The dependency update-cache command updates the local dependency cache for the current project. It re-resolves semantic version constraints to specific versions (fetching newer versions if available), caches all dependencies, and re-generates language bindings (schemas) for them if needed.

Usage

crossplane dependency update-cache [flags]

Flags

crossplane function

[BETA] Work with functions in control plane Projects.

Usage

crossplane function <command> [flags]

crossplane function generate

[BETA] Generate a Function for a Composition.

The function generate command creates an embedded function in the specified language under the project’s functions/ directory. It optionally idempotently adds the new function to end of a Composition’s pipeline when given a Composition path.

Supported languages

The following are valid arguments to the --language / -l flag:

• go-templating (default)
• go
• kcl
• python

Examples

Create a function with the default language (go-templating) in functions/fn1:

1crossplane function generate fn1

Create a Python function in functions/fn2:

1crossplane function generate fn2 --language python

Create a Go function in functions/compose-cluster and add it as a pipeline step in the given Composition:

1crossplane function generate compose-cluster apis/cluster/composition.yaml --language go

Usage

crossplane function generate <name> [<pipeline-path>] [flags]

Arguments

Flags

crossplane operation

[ALPHA] Work with Crossplane Operations.

Usage

crossplane operation <command> [flags]

crossplane operation render

[ALPHA] Render an Operation.

The operation render command shows you what resources an Operation would create or mutate by running the operation locally and printing its results. It runs the Crossplane render engine (either in a Docker container or via a local binary) to produce high-fidelity output that matches what the real reconciler would produce.

Function runtime configuration

By default, the render command pulls and runs Operation Functions using Docker. You can add the following annotations to each Function to change how they’re run:

Use the standard DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, and DOCKER_TLS_VERIFY environment variables to configure how this command connects to the Docker daemon. See the Docker environment variables reference.

Project support

When running render in a Crossplane Project (any directory containing a crossplane-project.yaml project metadata file), you may omit the functions file argument in favor of using function dependencies defined in the project metadata and embedded functions from the project.

Examples

Render an Operation:

1crossplane operation render operation.yaml functions.yaml

Pin the Crossplane version used for rendering:

1crossplane operation render operation.yaml functions.yaml \
2  --crossplane-version=v2.2.1

Use a local crossplane binary instead of Docker:

1crossplane operation render operation.yaml functions.yaml \
2  --crossplane-binary=/usr/local/bin/crossplane

Pass context values to the function pipeline:

1crossplane operation render operation.yaml functions.yaml \
2  --context-values=apiextensions.crossplane.io/environment='{"key": "value"}'

Pass required resources functions can request:

1crossplane operation render operation.yaml functions.yaml \
2  --required-resources=required-resources.yaml

Pass OpenAPI schemas for functions that need them:

1crossplane operation render operation.yaml functions.yaml \
2  --required-schemas=schemas/

Render a WatchOperation with a watched resource:

1crossplane operation render watchoperation.yaml functions.yaml \
2  --watched-resource=watched-configmap.yaml

Pass credentials to functions that need them:

1crossplane operation render operation.yaml functions.yaml \
2  --function-credentials=credentials.yaml

Include function results and context in output:

1crossplane operation render operation.yaml functions.yaml -r -c

Include the full Operation with original spec and metadata:

1crossplane operation render operation.yaml functions.yaml -o

Override function annotations for remote Docker daemon:

1crossplane operation render operation.yaml functions.yaml \
2  -a render.crossplane.io/runtime-docker-publish-address=0.0.0.0 \
3  -a render.crossplane.io/runtime-docker-target=192.168.1.100

Use development runtime with custom target for all functions:

1crossplane operation render operation.yaml functions.yaml \
2  -a render.crossplane.io/runtime=Development \
3  -a render.crossplane.io/runtime-development-target=localhost:9444

Usage

crossplane operation render <operation> [<functions>] [flags]

Arguments

Flags

crossplane project

[BETA] Work with control plane Projects.

Usage

crossplane project <command> [flags]

crossplane project build

[BETA] Build a project into Crossplane packages.

The project build command builds a Crossplane Project into a set of xpkgs. It builds each embedded function in the project and a Configuration package that ties everything together. The output of the build is a special .xpkg file containing all the built packages, placed in the project’s output directory (_output/ by default). The project push command can consume packges from the output file and push them to an OCI registry.

The build command constructs the repository for the built Configuration from spec.repository in crossplane-project.yaml. Override it for a single build with --repository.

The build reuses the dependency cache populated by crossplane dependency add and crossplane dependency update-cache. Override the cache location with --cache-dir or the CROSSPLANE_XPKG_CACHE environment variable.

Examples

Build the project in the current directory:

1crossplane project build

Build the project, overriding the repository:

1crossplane project build --repository=xpkg.crossplane.io/my-org/my-project

Build the project into a custom output directory:

1crossplane project build -o ./packages

Usage

crossplane project build [flags]

Flags

crossplane project init

[BETA] Initialize a new project.

The project init command scaffolds a new, empty Crossplane Project. It creates a target directory containing a minimal crossplane-project.yaml along with the standard sub-directories used by the DevEx tooling: apis, functions, examples, tests, and operations.

The project name must be a valid DNS-1035 label. By default, the init command creates a new directory named after the project; use --directory (-d) to choose a different target directory.

Examples

Create a new project named my-project in ./my-project/:

1crossplane project init my-project

Create a new project in a specific directory:

1crossplane project init my-project --directory ./projects/new-project

Usage

crossplane project init <name> [flags]

Arguments

Flags

crossplane project push

[BETA] Push a built project to an OCI registry.

The project push command pushes the xpkgs produced by crossplane project build to an OCI registry. It pushes both the Configuration package and any embedded function packages built from the project. The push command uses registry credentials from the local docker configuration; pushing to a private registry may require a prior docker login.

By default the command pushes to the repository specified in crossplane-project.yaml and uses a tag generated from the package contents. Override either with --repository and --tag (-t). To push a specific package file instead of the project’s default output, use --package-file.

Examples

Push the project’s packages using the repository and a generated tag:

1crossplane project push

Push using an explicit tag:

1crossplane project push --tag=v1.2.3

Push to a different repository than the one in the project file:

1crossplane project push --repository=xpkg.crossplane.io/my-org/my-project --tag=v1.2.3

Usage

crossplane project push [flags]

Flags

crossplane project run

[BETA] Build and run a project in a local dev control plane.

The project run command builds a Crossplane Project and runs it on a local development control plane for testing.

This command:

• Builds all embedded functions defined in the project.
• Creates (or reuses) a local development control plane running in a KIND cluster, with a local OCI registry for packages.
• Loads the project’s packages into the local OCI registry.
• Installs the project’s Configuration on the control plane.
• Updates kubeconfig so kubectl points at the development control plane.

By default, run names the control plane after the project. Use --control-plane-name to choose a different name, which is useful when running multiple projects side-by-side.

You can use a Crossplane version other than the latest stable version by specifying the --crossplane-version flag.

You can provide resources to apply around the project install:

• --init-resources applies one or more files before installing the Configuration (useful for things like ImageConfig).
• --extra-resources applies one or more files after installing the Configuration and its dependencies (useful for things like ProviderConfig).

Examples

Build and run the project on the default local development control plane:

1crossplane project run

Run on a control plane with a specific name (created if it doesn’t exist):

1crossplane project run --control-plane-name=my-dev-ctp

Pin the Crossplane version installed in the dev control plane:

1crossplane project run --crossplane-version=v2.2.1

Apply imageconfig.yaml before installing the Configuration, and providerconfig.yaml after:

1crossplane project run --init-resources=imageconfig.yaml --extra-resources=providerconfig.yaml

Usage

crossplane project run [flags]

Flags

crossplane project stop

[BETA] Tear down a local dev control plane.

The project stop command tears down the local development control plane created by crossplane project run. It removes both the KIND cluster and the local OCI registry.

When run from a project directory, the stop command tears down the control plane whose name matches the project name. When run outside a project directory, pass --control-plane-name to identify the control plane to tear down. If you passed --registry-dir to up project run, pass it to up project stop as well to clean up the registry data.

Examples

Tear down the development control plane for the project in the current directory:

1crossplane project stop

Tear down a specific local dev control plane by name:

1crossplane project stop --control-plane-name=my-dev-cp

Usage

crossplane project stop [flags]

Flags

crossplane resource

[BETA] Work with Crossplane resources.

Usage

crossplane resource <command> [flags]

crossplane resource trace

[BETA] Trace a Crossplane resource for troubleshooting.

The resource trace command traces a Crossplane resource (Claim, Composite, or Managed Resource) to give a detailed view of its relationships and help troubleshoot compositions.

The command requires a resource type and a resource name:

1crossplane resource trace <resource kind> <resource name>

Kubernetes-style <kind>/<name> input works too: for example, crossplane resource trace example.crossplane.io/my-xr.

You can further specify the kind as TYPE[.VERSION][.GROUP] if needed; for example, mykind.example.org or mykind.v1alpha1.example.org.

By default, crossplane resource trace uses the Kubernetes configuration at ~/.kube/config. Override with the KUBECONFIG environment variable.

Output options

By default, trace prints to the terminal as a tree, truncating the Ready and Status messages to 64 characters.

Change the format with -o (--output): wide, json, yaml, or dot (for a Graphviz graph).

Wide output

Use --output=wide to print the full Ready and Status messages even when they exceed 64 characters, and other kind-specific printer columns.

Graphviz dot output

Use --output=dot to print a textual Graphviz dot graph.Pipe to dot to render an image:

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

Print connection secrets

Use --show-connection-secrets to include connection-secret names alongside the other resources. Secret values are never printed. Output includes the secret name and namespace.

Print package dependencies

The --show-package-dependencies flag controls how the display of package dependencies:

• unique (default): include each required package only once.
• all: show every package that requires the same dependency.
• none: hide all package dependencies.

Print package revisions

The --show-package-revisions flag controls the display of package revisions:

• active (default): show only the active revisions.
• all: show all revisions, including inactive ones.
• none: hide all revisions.

Examples

Trace a MyKind resource named my-res in the namespace my-ns:

1crossplane resource trace mykind my-res -n my-ns

Trace all MyKind resources in the namespace my-ns:

1crossplane resource trace mykind -n my-ns

Wide format with full errors, condition messages, and kind-specific columns:

1crossplane resource trace mykind my-res -n my-ns -o wide

Show connection secret names alongside the resources:

1crossplane resource trace mykind my-res -n my-ns --show-connection-secrets

Output a Graphviz dot graph and pipe to dot to generate a PNG:

1crossplane resource trace mykind my-res -n my-ns -o dot | dot -Tpng -o output.png

Output all retrieved resources as JSON and pipe to jq for color:

1crossplane resource trace mykind my-res -n my-ns -o json | jq

Output debug logs to stderr while piping a dot graph to dot:

1crossplane resource trace mykind my-res -n my-ns -o dot --verbose | dot -Tpng -o output.png

Watch a resource continuously until its deletion:

1crossplane resource trace mykind my-res -n my-ns --watch

Usage

crossplane resource trace <resource> [<name>] [flags]

Arguments

Flags

crossplane resource validate

[BETA] Validate Crossplane resources.

The resource validate command validates the provided Crossplane resources against the schemas of the provided extensions (XRDs, CRDs, Providers, Functions, and Configurations). It uses the Kubernetes API server’s validation library plus other checks such as unknown-field detection, a common source of difficult-to-debug Crossplane issues.

The validate command downloads any Providers or Configurations provided as extensions, and loads their CRDs before validation. If --cache-dir isn’t set, it defaults to ~/.crossplane/cache. Clean the cache before downloading schemas with --clean-cache.

All validation happens offline using the Kubernetes API server’s validation library, without requiring a Crossplane instance or control plane.

crossplane resource validate supports validating:

• A managed or composite resource against a Provider or XRD schema.
• The output of crossplane composition render.
• An XRD’s Common Expression Language (CEL) rules.
• Resources against a directory of schemas.

Validate resources against a schema

When validating against a Provider, the command downloads the Provider package to --cache-dir. Access to a Kubernetes cluster or Crossplane pod isn’t required as validate downloads the Provider extracts it locally.

Create a Provider manifest:

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: crossplane-contrib-provider-aws-iam
5spec:
6  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-iam:v2.0.0

Provide a managed resource to validate:

 1apiVersion: iam.aws.m.upbound.io/v1beta1
 2kind: AccessKey
 3metadata:
 4  namespace: default
 5  name: sample-access-key-0
 6spec:
 7  forProvider:
 8    userSelector:
 9      matchLabels:
10        example-name: test-user-0

Run validate with both files:

1crossplane resource validate provider.yaml managedResource.yaml

Validate render output

Pipe the output of crossplane composition render to validate to validate complete Crossplane resource pipelines, including XRs, Compositions, and Functions. Use --include-full-xr on render, and - (read stdin) on validate:

1crossplane composition render xr.yaml composition.yaml func.yaml --include-full-xr | \
2    crossplane resource validate schemas.yaml -

Validate Common Expression Language rules

XRDs can define validation rules in CEL via x-kubernetes-validations. validate evaluates them:

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: myxrs.example.crossplane.io
 5spec:
 6  # ... versions[].schema.openAPIV3Schema:
 7  #   spec:
 8  #     x-kubernetes-validations:
 9  #       - rule: "self.minReplicas <= self.replicas && self.replicas <= self.maxReplicas"
10  #         message: "replicas should be in between minReplicas and maxReplicas."

Validate against a directory of schemas

validate can also take a directory of schema YAML files to use for validation. It ignores any files with extensions other than .yml or .yaml.

1schemas/
2├── platform-ref-aws.yaml
3├── providers/
4│   └── provider-aws-iam.yaml
5└── xrds/
6    └── xrd.yaml

1crossplane resource validate schemas/ resources.yaml

Examples

Validate resources against extensions in extensions.yaml:

1crossplane resource validate extensions.yaml resources.yaml

Validate resources in a directory against extensions in another directory:

1crossplane resource validate crossplane.yaml,extensionsDir/ resourceDir/

Pin the Crossplane image version used during validation:

1crossplane resource validate extensions.yaml resources.yaml \
2  --crossplane-image=xpkg.crossplane.io/crossplane/crossplane:v1.20.0

Skip success log lines (only print problems):

1crossplane resource validate extensionsDir/ resourceDir/ --skip-success-results

Validate the output of render against extensions in a directory:

1crossplane composition render xr.yaml composition.yaml func.yaml --include-full-xr | \
2    crossplane resource validate extensionsDir/ -

Use a custom cache directory and clean it before downloading schemas:

1crossplane resource validate extensionsDir/ resourceDir/ --cache-dir .cache --clean-cache

Usage

crossplane resource validate <extensions> <resources> [flags]

Arguments

Flags

crossplane version

Print the client and server version information for the current context.

Usage

crossplane version [flags]

Flags

crossplane xpkg

Work with Crossplane packages.

Crossplane packages, called xpkgs, allow you to add capabilities to your Crossplane installation. Crossplane supports Configuration, Provider, and Function packages.

A package is an opinionated OCI image that contains everything needed to extend a Crossplane control plane with new capabilities. For example, installing a Provider package extends Crossplane with support for new kinds of managed resource (MRs).

See the Crossplane packages documentation for more information.

Usage

crossplane xpkg <command> [flags]

crossplane xpkg batch

Batch build and push a family of provider packages.

Usage

crossplane xpkg batch --family-base-image=STRING --provider-name=STRING --family-package-url-format=STRING [flags]

Flags

crossplane xpkg build

Build a new package.

The xpkg build command builds a package file from a local directory of files. The CLI combines a directory of YAML files and packages them as an OCI container image, applying the annotations and values required by the Crossplane XPKG specification.

crossplane xpkg build supports building Configuration, Function, and Provider package types.

The command recursively looks in --package-root for files ending in .yml or .yaml and attempts to combine them 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 comma-separated list of globs specifying files to exclude from the build, relative to --package-root.

1crossplane xpkg build --ignore="./test/*,kind-config.yaml"

Set the package name

By default, the build command constructs the package filename using a combination of metadata.name and a hash of the package contents, and writes it to --package-root. Override the location and filename with --package-file (-o):

1crossplane xpkg build -o /home/crossplane/example.xpkg

Include examples

Include YAML files demonstrating how to use the package with --examples-root (-e). Defaults to ./examples.

Include a runtime image

Function and Provider packages embed a controller container image. Configuration packages don’t have a runtime image.

Use --embed-runtime-image-tarball to embed a local OCI image tarball instead of an image from the Docker cache.

Examples

Build a package from the files in the ‘package’ directory:

1crossplane xpkg build --package-root=package/

Build a Provider package that embeds the controller OCI image so the package can also run the provider.

1crossplane xpkg build --embed-runtime-image=cc873e13cdc1

Usage

crossplane xpkg build [flags]

Flags

crossplane xpkg extract

Extract package contents into a Crossplane cache compatible format. Fetches from a remote registry by default.

Usage

crossplane xpkg extract [<package>] [flags]

Arguments

Flags

crossplane xpkg init

Initialize a new package from a template.

The xpkg init command initializes a directory that you can use to build a package. It uses a template to initialize the directory, and can use any Git repository as a template.

Specify either a full Git URL or one of the following names as the template:

• configuration-template (https://github.com/crossplane/configuration-template)
• provider-template (https://github.com/crossplane/provider-template)
• provider-template-upjet (https://github.com/crossplane/upjet-provider-template)
• function-template-go (https://github.com/crossplane/function-template-go)
• function-template-python (https://github.com/crossplane/function-template-python)

NOTES.txt

The init command prints the contents of any NOTES.txt file in the template root after initializing the directory. Useful for instructions on how to use the template.

init.sh

The init command executes any init.sh file in the template root (after user confirmation). Useful for scripts that personalize the template. Pass -r (--run-init-script) to run the script without prompting.

Examples

Initialize a new Go Composition Function named function-example:

1crossplane xpkg init function-example function-template-go

Initialize a new Provider named provider-example from a custom template:

1crossplane xpkg init provider-example https://github.com/crossplane/provider-template-custom

Initialize a new Go Composition Function and run its init.sh script (if any) without prompting or displaying its contents:

1crossplane xpkg init function-example function-template-go --run-init-script

Usage

crossplane xpkg init <name> <template> [flags]

Arguments

Flags

crossplane xpkg install

Install a package in a control plane.

The xpkg install command installs a package in a Crossplane control plane. It uses ~/.kube/config to connect to the control plane; override the path with the KUBECONFIG environment variable.

Specify the package kind, fully qualified package OCI reference, and optionally a name for the package inside Crossplane:

1crossplane xpkg install <package-kind> <oci-ref> [<optional-name>]

The <package-kind> is one of configuration, function, or provider.

Wait for package install

By default the command returns as soon as Crossplane accepts the package. It doesn’t wait for the download or install to complete. To inspect download or installation problems, run kubectl describe <kind>.

Use --wait (-w) to make the command wait for the package to become HEALTHY before returning. The command returns an error if the wait time expires before the package is healthy.

Require manual package activation

Pass -m (--manual-activation) to set the package’s revisionActivationPolicy to Manual, which prevents automatic upgrades of the package.

Authenticate to a private registry

To authenticate to a private package registry use --package-pull-secrets with a comma-separated list of Kubernetes Secret names.

Customize the number of stored package revisions

By default Crossplane keeps only the active revision and one inactive revision in the local package cache. Increase the number of stored revisions with -r (--revision-history-limit).

Examples

Wait 1 minute for the package to finish installing before returning:

1crossplane xpkg install provider xpkg.crossplane.io/crossplane-contrib/provider-aws-eks:v0.41.0 --wait=1m

Install a Function named function-eg using a custom DeploymentRuntimeConfig:

1crossplane xpkg install function xpkg.crossplane.io/crossplane/function-example:v0.1.4 function-eg \
2  --runtime-config=customconfig

Usage

crossplane xpkg install <kind> <package> [<name>] [flags]

Arguments

Flags

crossplane xpkg push

Push a package to a registry.

The xpkg push command pushes a Crossplane package file to any OCI registry. A package’s OCI tag must be a semantic version. The push command uses registry credentials from the local docker configuration; pushing to a private registry may require a prior docker login.

By default the command looks in the current directory for a single .xpkg file to push. To push multiple files (for example, a multi-platform package) or a specific .xpkg file, use -f (--package-files).

Examples

Push a multi-platform package:

1crossplane xpkg push -f function-amd64.xpkg,function-arm64.xpkg \
2  xpkg.crossplane.io/crossplane/function-example:v1.0.0

Push the single xpkg file in the current directory:

1crossplane xpkg push xpkg.crossplane.io/crossplane/function-example:v1.0.0

Push to Docker Hub:

1crossplane xpkg push docker.io/crossplane/function-example:v1.0.0

Usage

crossplane xpkg push <package> [flags]

Arguments

Flags

crossplane xpkg update

Update a package in a control plane.

The xpkg update command updates a package in a Crossplane control plane. It uses ~/.kube/config to connect to the control plane; override the path with the KUBECONFIG environment variable.

Specify the package kind, a new fully qualified package OCI reference, and optionally the name of the package already installed in Crossplane:

1crossplane xpkg update <package-kind> <oci-ref> [<optional-name>]

Examples

Update the Function named function-eg to a new version:

1crossplane xpkg update function xpkg.crossplane.io/crossplane/function-example:v0.1.5 function-eg

Update to the latest patch version of a Provider:

1crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v2.0.0

Usage

crossplane xpkg update <kind> <package> [<name>]

Arguments

crossplane xrd

[BETA] Work with Crossplane Composite Resource Definitions (XRDs).

Usage

crossplane xrd <command> [flags]

crossplane xrd convert

[BETA] Convert an XRD to a Kubernetes CRD.

The xrd convert command converts a CompositeResourceDefinition (XRD) into one or more CustomResourceDefinitions that Crossplane derives from it internally.

Useful for inspecting the generated CRD shape, feeding it into kubectl-based tooling that doesn’t understand XRDs, or debugging composition behavior.

Output depends on the XRD type, detected automatically:

• Namespaced or Cluster-scoped XRD: 1 CRD for the XR
• Legacy XRD without claimNames: 1 CRD for the XR
• Legacy XRD with claimNames: 2 CRDs: one for the XR and one for the Claim

Examples

Convert an XRD file and print the CRDs to stdout (multi-doc YAML for legacy XRDs):

1crossplane xrd convert xrd.yaml

Convert and write to a single file (multi-doc YAML for legacy XRDs):

1crossplane xrd convert xrd.yaml -o crds.yaml

Split per-CRD files into a directory (each named <crd.Name>.yaml):

1crossplane xrd convert xrd.yaml --output-dir ./crds/

Read the XRD from stdin:

1cat xrd.yaml | crossplane xrd convert -

Usage

crossplane xrd convert [<input-file>] [flags]

Arguments

Flags

crossplane xrd generate

[BETA] Generate an XRD from a Composite Resource (XR) or SimpleSchema definition.

The xrd generate command creates a CompositeResourceDefinition (XRD) from either an example Composite Resource (XR) or a SimpleSchema document, and writes it into the project’s APIs directory.

XR is the default input format; pass --from simpleschema to generate an XRD from a SimpleSchema definition instead.

Examples

Generate an XRD from an example Composite Resource (XR) and save it under the project’s APIs directory:

1crossplane xrd generate examples/cluster/example.yaml

Generate an XRD with a specific plural form, useful when automatic pluralization is wrong (for example, “postgres”):

1crossplane xrd generate examples/postgres/example.yaml --plural postgreses

Generate an XRD and save it to a custom path:

1crossplane xrd generate examples/postgres/example.yaml --path database/definition.yaml

Generate an XRD from a SimpleSchema document:

1crossplane xrd generate apis/network/schema.yaml --from simpleschema

Usage

crossplane xrd generate <file> [flags]

Arguments

Flags