This documentation is for the crossplane CLI v2.4.1.

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

{{< table "table table-sm table-striped" >}}

crossplane cluster

[BETA] Inspect a Crossplane cluster.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

Usage

crossplane cluster <command> [flags]

crossplane cluster top

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

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

crossplane cluster top

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

crossplane cluster top -n default

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

crossplane cluster top -s

Usage

crossplane cluster top [flags]

Flags

{{< table "table table-sm table-striped" >}}

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

{{< table "table table-sm table-striped" >}}

crossplane composition

Work with Crossplane Compositions.

Usage

crossplane composition <command> [flags]

crossplane composition convert

[BETA] Convert a Composition to a newer version.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

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

Use a different functionRef and output to stdout:

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

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

cat composition.yaml | crossplane composition convert composition-environment

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane composition generate

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

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

crossplane composition generate apis/network/definition.yaml

Generate a Composition with a custom name prefix:

crossplane 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"):

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

Write the generated Composition to a specific path:

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

Usage

crossplane composition generate <xrd> [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

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.

{{<hint "important" >}} This command runs composition functions and the Crossplane render engine using Docker by default, requiring a working Docker installation. See the function annotations and --crossplane-binary option below to understand how to render without Docker. {{< /hint >}}

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:

{{<table "table table-sm table-striped" >}}

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.

apiVersion: example.org/v1alpha1
kind: ComposedResource
metadata:
  name: test-render-b
  annotations:
    crossplane.io/composition-resource-name: resource-b
spec:
  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:

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

Simulate updating an XR that already exists:

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

Pin the Crossplane version used for rendering:

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

Use a local crossplane binary instead of Docker:

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

Pass context values to the Function pipeline:

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

Pass required resources Functions in the pipeline can request:

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

Pass OpenAPI schemas for Functions that need them:

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

Pass credentials to Functions in the pipeline that need them:

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

Override function annotations for a remote Docker daemon:

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

Force all functions to use development runtime:

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

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:

crossplane config view

Enable alpha commands:

crossplane 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

{{< table "table table-sm table-striped" >}}

crossplane config view

Print the current effective configuration as YAML.

Usage

crossplane config view

crossplane dependency

[BETA] Manage dependencies of control plane Projects.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

Usage

crossplane dependency <command> [flags]

crossplane dependency add

[BETA] Add a dependency to the current project.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

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

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

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

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

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

Usage

crossplane dependency add <package> [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane dependency clean-cache

[BETA] Clean the dependency cache.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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

{{< table "table table-sm table-striped" >}}

crossplane dependency update-cache

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

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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

{{< table "table table-sm table-striped" >}}

crossplane function

[BETA] Work with functions in control plane Projects.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

Usage

crossplane function <command> [flags]

crossplane function generate

[BETA] Generate a Function for a Composition.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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 the 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:

crossplane function generate fn1

Create a Python function in functions/fn2:

crossplane function generate fn2 --language python

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

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane operation

[ALPHA] Work with Crossplane Operations.

{{<hint "note" >}} Alpha features are experimental and may change or disappear in a future release. {{< /hint >}}

Usage

crossplane operation <command> [flags]

crossplane operation render

[ALPHA] Render an Operation.

{{<hint "note" >}} Alpha features are experimental and may change or disappear in a future release. {{< /hint >}}

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.

{{<hint "important" >}} This command runs operation functions and the Crossplane render engine using Docker by default, requiring a working Docker installation. See the function annotations and --crossplane-binary option below to understand how to render without Docker. {{< /hint >}}

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:

{{<table "table table-sm table-striped" >}}

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:

crossplane operation render operation.yaml functions.yaml

Pin the Crossplane version used for rendering:

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

Use a local crossplane binary instead of Docker:

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

Pass context values to the function pipeline:

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

Pass required resources functions can request:

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

Pass OpenAPI schemas for functions that need them:

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

Render a WatchOperation with a watched resource:

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

Pass credentials to functions that need them:

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

Include function results and context in output:

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

Include the full Operation with original spec and metadata:

crossplane operation render operation.yaml functions.yaml -o

Override function annotations for remote Docker daemon:

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

Use development runtime with custom target for all functions:

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane project

[BETA] Work with control plane Projects.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

Usage

crossplane project <command> [flags]

crossplane project build

[BETA] Build a project into Crossplane packages.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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

{{<hint "important" >}} The repository influences the function names used for embedded function references in compositions. You must specify the same repository when building and pushing a project. {{< /hint >}}

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:

crossplane project build

Build the project, overriding the repository:

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

Build the project into a custom output directory:

crossplane project build -o ./packages

Usage

crossplane project build [flags]

Flags

{{< table "table table-sm table-striped" >}}

crossplane project init

[BETA] Initialize a new project.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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/:

crossplane project init my-project

Create a new project in a specific directory:

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

Usage

crossplane project init <name> [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane project push

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

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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.

{{<hint "important" >}} The repository influences the function names used for embedded function references in compositions. You must specify the same repository when building and pushing a project. {{< /hint >}}

Examples

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

crossplane project push

Push using an explicit tag:

crossplane project push --tag=v1.2.3

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

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

Usage

crossplane project push [flags]

Flags

{{< table "table table-sm table-striped" >}}

crossplane project run

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

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

crossplane project run

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

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

Pin the Crossplane version installed in the dev control plane:

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

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

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

Usage

crossplane project run [flags]

Flags

{{< table "table table-sm table-striped" >}}

crossplane project stop

[BETA] Tear down a local dev control plane.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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 crossplane project run, pass it to crossplane project stop as well to clean up the registry data.

Examples

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

crossplane project stop

Tear down a specific local dev control plane by name:

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

Usage

crossplane project stop [flags]

Flags

{{< table "table table-sm table-striped" >}}

crossplane resource

[BETA] Work with Crossplane resources.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

Usage

crossplane resource <command> [flags]

crossplane resource trace

[BETA] Trace a Crossplane resource for troubleshooting.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

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

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

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

Trace all MyKind resources in the namespace my-ns:

crossplane resource trace mykind -n my-ns

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

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

Show connection secret names alongside the resources:

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

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

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

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

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

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

Watch a resource continuously until its deletion:

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane resource validate

[BETA] Validate Crossplane resources.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: crossplane-contrib-provider-aws-iam
spec:
  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-iam:v2.0.0

Provide a managed resource to validate:

apiVersion: iam.aws.m.upbound.io/v1beta1
kind: AccessKey
metadata:
  namespace: default
  name: sample-access-key-0
spec:
  forProvider:
    userSelector:
      matchLabels:
        example-name: test-user-0

Run validate with both files:

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

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

Validate Common Expression Language rules

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

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: myxrs.example.crossplane.io
spec:
  # ... versions[].schema.openAPIV3Schema:
  #   spec:
  #     x-kubernetes-validations:
  #       - rule: "self.minReplicas <= self.replicas && self.replicas <= self.maxReplicas"
  #         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.

schemas/
├── platform-ref-aws.yaml
├── providers/
│   └── provider-aws-iam.yaml
└── xrds/
    └── xrd.yaml

crossplane resource validate schemas/ resources.yaml

Examples

Validate resources against extensions in extensions.yaml:

crossplane resource validate extensions.yaml resources.yaml

Validate resources in a directory against extensions in another directory:

crossplane resource validate crossplane.yaml,extensionsDir/ resourceDir/

Pin the Crossplane image version used during validation:

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

Skip success log lines (only print problems):

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

Emit machine-readable results (JSON or YAML) for piping to jq, scripts, or CI systems. The structured payload includes per-resource status and field-level error details:

crossplane resource validate extensionsDir/ resourceDir/ --output json | jq .

Validate the output of render against extensions in a directory:

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

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

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane version

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

Usage

crossplane version [flags]

Flags

{{< table "table table-sm table-striped" >}}

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

{{< table "table table-sm table-striped" >}}

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.

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

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

{{<hint "note" >}} Images referenced with --embed-runtime-image must be in the local Docker cache. Use docker pull to download a missing image. {{< /hint >}}

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:

crossplane xpkg build --package-root=package/

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

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

Usage

crossplane xpkg build [flags]

Flags

{{< table "table table-sm table-striped" >}}

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

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane xpkg get-crds

Download CRDs from package dependencies.

The xpkg get-crds command downloads CRDs from Crossplane package dependencies (providers, functions, configurations) and writes them as YAML files to the specified output directory. With --json-schema, it extracts the OpenAPI v3 schemas from CRDs and writes them as JSON Schema files suitable for use with YAML language servers.

By default, the command organizes files by API group and version (for example, <group>/<version>/<kind>.{yaml|json}). Use --flat to write all files directly to the output directory without subfolders.

It accepts the same extension sources as the validate command: crossplane.yaml files, directories containing package manifests, or Provider/Function/Configuration resources.

Examples

• Download CRDs organized by group:

  shellCopy

  crossplane xpkg get-crds crossplane.yaml --output-dir ./crds
  

• Download CRDs as flat files:

  shellCopy

  crossplane xpkg get-crds crossplane.yaml --output-dir ./crds --flat
  

• Download JSON Schemas for YAML language server:

crossplane xpkg get-crds crossplane.yaml --output-dir ./schemas --json-schema

• Download CRDs from multiple sources:

  shellCopy

  crossplane xpkg get-crds crossplane.yaml,providers/ --output-dir ./crds
  

• Force re-download of cached schemas:

  shellCopy

  crossplane xpkg get-crds crossplane.yaml --output-dir ./crds --clean-cache
  

Usage

crossplane xpkg get-crds <extensions> [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

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)
• function-template-go (https://github.com/crossplane/function-template-go)
• function-template-python (https://github.com/crossplane/function-template-python)
• provider-template (https://github.com/crossplane/provider-template)
• provider-template-upjet (https://github.com/crossplane/upjet-provider-template)

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:

crossplane xpkg init function-example function-template-go

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

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

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

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:

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

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

{{<hint "important" >}} The package reference must be fully qualified, including the registry, repository, and tag (for example, registry.example.com/package:v1.0.0). {{< /hint >}}

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.

{{<hint "important" >}} The secrets must be in the same namespace as the Crossplane pod. {{< /hint >}}

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:

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

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

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

{{<hint "important" >}} The destination must be fully qualified, including the registry, repository, and tag (for example, registry.example.com/package:v1.0.0). {{< /hint >}}

Examples

Push a multi-platform package:

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

Push the single xpkg file in the current directory:

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

Push to Docker Hub:

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

Usage

crossplane xpkg push <package> [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

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:

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

{{<hint "important" >}} The package reference must be fully qualified, including the registry, repository, and tag (for example, registry.example.com/package:v1.0.0). {{< /hint >}}

Examples

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

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

Update to the latest patch version of a Provider:

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

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane xr

[ALPHA] Work with Crossplane Composite Resources (XRs).

{{<hint "note" >}} Alpha features are experimental and may change or disappear in a future release. {{< /hint >}}

Usage

crossplane xr <command> [flags]

crossplane xr generate

[ALPHA] Generate a Composite Resource (XR) from a Claim.

{{<hint "note" >}} Alpha features are experimental and may change or disappear in a future release. {{< /hint >}}

The xr generate command creates a Composite Resource (XR) from a Claim YAML.

It reads the Claim from a file (or stdin), produces an XR (same spec, derived kind, optional Claim reference), and writes the result to stdout or to a file.

Examples

Generate an XR from claim.yaml and print it to stdout (kind is X + Claim's kind):

crossplane xr generate claim.yaml

Generate an XR from claim.yaml and write it to xr.yaml:

crossplane xr generate claim.yaml -o xr.yaml

Generate an XR with an explicit name (overrides the default suffix or Claim name):

crossplane xr generate claim.yaml --name my-xr

Generate an XR with a specific kind:

crossplane xr generate claim.yaml --kind MyCompositeResource

Generate a directly linked XR (no Claim reference, no name suffix):

crossplane xr generate claim.yaml --direct

Generate an XR with a fresh random metadata.uid:

crossplane xr generate claim.yaml --gen-uid

Use in crossplane render:

crossplane render <(crossplane xr generate claim.yaml) composition.yaml functions.yaml

Read the Claim from stdin:

cat claim.yaml | crossplane xr generate -

Usage

crossplane xr generate [<input-file>] [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane xr patch

[ALPHA] Patch a Composite Resource (XR).

{{<hint "note" >}} Alpha features are experimental and may change or disappear in a future release. {{< /hint >}}

The xr patch command applies XR-level patches to a Composite Resource (XR).

It reads the XR from a file (or stdin), applies the requested patches, and writes the result to stdout or to a file. Pass at least one patching flag; today the only one is --xrd, which applies default values from an XRD's openAPIV3Schema to the XR. Future releases add more patching flags.

Examples

Apply default values from an XRD to an XR:

crossplane xr patch xr.yaml --xrd xrd.yaml

Patch an XR from stdin:

cat xr.yaml | crossplane xr patch - --xrd xrd.yaml

Write the patched XR to a file:

crossplane xr patch xr.yaml --xrd xrd.yaml -o patched.yaml

Usage

crossplane xr patch [<input-file>] [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane xrd

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

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

Usage

crossplane xrd <command> [flags]

crossplane xrd convert

[BETA] Convert an XRD to a Kubernetes CRD.

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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

crossplane xrd convert xrd.yaml

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

crossplane xrd convert xrd.yaml -o crds.yaml

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

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

Read the XRD from stdin:

cat xrd.yaml | crossplane xrd convert -

Usage

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

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}

crossplane xrd generate

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

{{<hint "note" >}} Beta features may change in a future release. {{< /hint >}}

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:

crossplane xrd generate examples/cluster/example.yaml

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

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

Generate an XRD and save it to a custom path:

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

Generate an XRD from a SimpleSchema document:

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

Usage

crossplane xrd generate <file> [flags]

Arguments

{{< table "table table-sm table-striped" >}}

Flags

{{< table "table table-sm table-striped" >}}