From 114878872ff00c0e3d164365995a4f3105f7ea20 Mon Sep 17 00:00:00 2001 From: Adam Wolfe Gordon Date: Thu, 21 May 2026 15:30:38 -0600 Subject: [PATCH 1/3] Update CLI reference docs for v2.3.0 Use the new `crossplane generate-docs` command to generate CLI reference docs from the built-in CLI help. Update both `master` and `v2.3`, since they're the same for now. Signed-off-by: Adam Wolfe Gordon --- content/master/cli/command-reference.md | 2917 +++++++++++++++++------ content/v2.3/cli/command-reference.md | 2917 +++++++++++++++++------ 2 files changed, 4244 insertions(+), 1590 deletions(-) diff --git a/content/master/cli/command-reference.md b/content/master/cli/command-reference.md index 64fac8b01..6796a4c94 100644 --- a/content/master/cli/command-reference.md +++ b/content/master/cli/command-reference.md @@ -4,164 +4,386 @@ title: Command Reference description: "Command reference for the Crossplane CLI" --- + + +This documentation is for the `crossplane` CLI v2.3.0. + -The `crossplane` CLI provides utilities to make using Crossplane easier. + +# crossplane + + + + + +A command line tool for interacting with Crossplane. -Read the [Crossplane CLI overview]({{}}) page for information on -installing `crossplane`. +Please report issues and feature requests at https://github.com/crossplane/cli. -## Global flags -The following flags are available for all commands. +Alpha and beta features are enabled. Manage enabled features with "crossplane config set". -{{< table "table table-sm table-striped">}} +## Usage -| Short flag | Long flag | Description | -|------------|-------------|------------------------------| -| `-h` | `--help` | Show context sensitive help. | -| | `--verbose` | Print verbose output. | +``` +crossplane [flags] +``` +## Flags +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-h` | `--help` | Show context-sensitive help. | +| | `--config=PATH` | Path to the crossplane CLI config file. | +| | `--verbose` | Print verbose logging statements. | {{< /table >}} + -## version +## crossplane cluster -The `crossplane version` command returns the version of Crossplane CLI -and the control plane. +[BETA] Inspect a Crossplane cluster. -```shell -crossplane version -Client Version: v1.17.0 -Server Version: v1.17.0 +NOTE: Beta features may be changed in a future release. + +### Usage + +``` +crossplane cluster [flags] ``` -## render + +### crossplane cluster top + -The `crossplane render` command previews the output of a -[composite resource]({{}}) after applying -any [composition functions]({{}}). +[BETA] Display resource (CPU/memory) usage by Crossplane related pods. -{{< hint "important" >}} -The `crossplane render` command requires you to use composition functions. -{{< /hint >}} +NOTE: Beta features may be changed in a future release. -The `crossplane render` command connects to the locally running Docker -Engine to pull and run composition functions. +The `cluster top` command returns current resource utilization (CPU and memory) +by Crossplane pods. Similar to `kubectl top pods`, it requires the [Metrics +Server](https://kubernetes-sigs.github.io/metrics-server/) to be correctly +configured and working on the server. -{{}} -Running `crossplane render` requires [Docker](https://www.docker.com/). -{{< /hint >}} +#### Examples -Provide a composite resource, composition and composition function YAML -definition with the command to render the output locally. +Show resource utilization for all Crossplane pods in the `crossplane-system` +namespace: -For example, -`crossplane render xr.yaml composition.yaml function.yaml` +```shell +crossplane cluster top +``` -The output includes the original composite resource followed by the generated -managed resources. +Show resource utilization for all Crossplane pods in the `default` namespace: -{{}} +```shell +crossplane cluster top -n default +``` + +Add a summary of resource utilization for all Crossplane pods on top of the +results: + +```shell +crossplane cluster top -s +``` + +#### Usage -```yaml ---- -apiVersion: nopexample.org/v1 -kind: XBucket -metadata: - name: test-xrender -status: - bucketRegion: us-east-2 ---- -apiVersion: s3.aws.m.upbound.io/v1beta1 -kind: Bucket -metadata: - annotations: - crossplane.io/composition-resource-name: my-bucket - generateName: test-xrender- - labels: - crossplane.io/composite: test-xrender - namespace: default - ownerReferences: - - apiVersion: nopexample.org/v1 - blockOwnerDeletion: true - controller: true - kind: XBucket - name: test-xrender - uid: "" -spec: - forProvider: - region: us-east-2 ``` +crossplane cluster top [flags] +``` +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-s` | `--summary` | Adds summary header for all Crossplane pods. | +| `-n` | `--namespace="crossplane-system"` | Show pods from a specific namespace, defaults to crossplane-system. | +{{< /table >}} + + + + +## crossplane completions + + + +Get shell (bash/zsh/fish) completions. You can source this command to get completions for the login shell. Example: 'source <(crossplane completions)' + + -{{< /expand >}} +### Usage +``` +crossplane completions [flags] +``` ### Flags -{{< table "table table-sm table-striped">}} +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--uninstall` | | +{{< /table >}} + + + + +## crossplane composition + + + +Work with Crossplane Compositions. + + + +### Usage + +``` +crossplane composition [flags] +``` + + + +### crossplane composition convert + + + +[BETA] Convert a Composition to a newer version. + +NOTE: Beta features may be changed in a future release. + +The `composition convert` command converts a Crossplane composition to use a +different version or migrate away from features that are no longer supported. + +The currently supported conversions are: + +- Native Composition Environment → `function-environment-configs` + +#### Usage + +``` +crossplane composition convert +``` + + + +#### crossplane composition convert composition-environment + + + +[BETA] Convert a Pipeline Composition to use function-environment-configs. + +NOTE: Beta features may be changed in a future release. + +The `composition convert composition-environment` command converts a Crossplane +Composition to use `function-environment-configs` in place of native Composition +Environments, which were removed in Crossplane v1.18. + +It adds a function pipeline step using +`crossplane-contrib/function-environment-configs` if needed. By default the +function is referenced as `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`: + +```shell +crossplane composition convert composition-environment composition.yaml \ + -o composition-environment.yaml +``` + +Use a different functionRef and output to stdout: + +```shell +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: + +```shell +cat composition.yaml | crossplane composition convert composition-environment +``` + +##### Usage + +``` +crossplane composition convert composition-environment [] [flags] +``` +##### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `[]` | *(optional)* The Composition file to be converted. If not specified or '-', stdin will be used. | +{{< /table >}} + +##### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-o` | `--output-file=PATH` | The file to write the generated Composition to. If not specified, stdout will be used. | +| | `--function-environment-configs-ref="function-environment-configs"` | Name of the existing function-environment-configs Function, to be used to reference it. | +{{< /table >}} + + + + +### crossplane composition generate + + + +[BETA] Generate a Composition for a CompositeResourceDefinition (XRD). + +NOTE: Beta features may be changed in a future release. + +The `composition generate` command creates a Composition for a +CompositeResourceDefinition (XRD). The Composition is scaffolded with 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: + +```shell +crossplane composition generate apis/network/definition.yaml +``` + +Generate a Composition with a custom name prefix: + +```shell +crossplane composition generate examples/network/network-aws.yaml --name aws +``` + +Generate a Composition with a custom plural form, useful when automatic +pluralization is wrong (e.g., "postgres"): + +```shell +crossplane composition generate examples/database/database.yaml --plural postgreses +``` + +Write the generated Composition to a specific path within the project: + +```shell +crossplane composition generate apis/network/definition.yaml --path apis/network/composition.yaml +``` + +#### Usage + +``` +crossplane composition generate [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Path to the CompositeResourceDefinition (XRD) file. | +{{< /table >}} -| Short flag | Long flag | Description | -| ------------ | ------------- | ------------------------------ | -| | `--context-files==,=` | A comma separated list of files to load for function "contexts." | -| | `--context-values==,=` | A comma separated list of key-value pairs to load for function "contexts." | -| `-r` | `--include-function-results` | Include the "results" or events from the function. | -| `-o` | `--observed-resources=` | Provide artificial managed resource data to the function. | -| `-e` | `--extra-resources=PATH` | A YAML file or directory of YAML files specifying extra resources to pass to the Function pipeline. | -| `-c` | `--include-context` | Include the context in the rendered output as a resource of kind: Context. | -| `-x` | `--include-full-xr` | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. | -| | `--timeout=` | Amount of time to wait for a function to finish. (Default 1 minute) | +#### Flags +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--name=STRING` | Name prefix for the composition. | +| | `--plural=STRING` | Custom plural for the CompositeTypeRef.Kind. | +| | `--path=STRING` | Output file path override. | +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition file. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | {{< /table >}} -The `crossplane render` command relies on standard -[Docker environmental variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) -to connect to the local Docker Engine and run composition functions. -### Provide function context + + +### 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 that would be made 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, only the `status` field and `metadata.name` of the XR are +printed. Use `--include-full-xr` (`-x`) to include the full XR `spec` and +`metadata`. + +{{}} +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 >}} -The `--context-files` and `--context-values` flags can provide data -to a function's `context`. -The context is JSON formatted data. +#### Function runtime configuration + +Composition Functions are pulled and run using Docker by default. You can add +the following annotations to each Function to change how they're run: + +{{}} +| Annotation | Purpose | +| ---------- | ------- | +| `render.crossplane.io/runtime: "Development"` | Connect to a Function that is already running, instead of using Docker. This is useful to develop and debug new Functions. The Function must be listening at `localhost:9443` and running with the `--insecure` flag. | +| `render.crossplane.io/runtime-development-target: "dns:///example.org:7443"` | Connect to a Function running somewhere other than `localhost:9443`. The target uses gRPC target syntax (e.g., `dns:///example.org:7443` or simply `example.org:7443`). | +| `render.crossplane.io/runtime-docker-cleanup: "Orphan"` | Don't stop the Function's Docker container after rendering. | +| `render.crossplane.io/runtime-docker-name: ""` | Create a container with that name and reuse it as long as it is running or can be restarted. | +| `render.crossplane.io/runtime-docker-pull-policy: "Always"` | Always pull the Function's package, even if it already exists locally. Other supported values are `Never` or `IfNotPresent`. | +| `render.crossplane.io/runtime-docker-publish-address: "0.0.0.0"` | Host address that Docker should publish the Function's container port to. Defaults to `127.0.0.1` (localhost only). Use `0.0.0.0` to publish to all host network interfaces, enabling access from remote machines. | +| `render.crossplane.io/runtime-docker-target: "docker-host"` | Address that the render CLI should use to connect to the Function's Docker container. If not specified, uses the publish address. | +{{< /table >}} -### Include function results +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](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) +reference. -If a function produces Kubernetes events with statuses use the -`--include-function-results` to print them along with the managed resource -outputs. +#### Project support -### Include the composite resource +When running `render` in a Crossplane Project (any directory containing a +`crossplane-project.yaml` project metadata file), it is optional to provide the +functions file as an argument. If the functions file is omitted, function +dependencies defined in the project metadata will be used. Embedded functions +from the project will also be built and run by render. -Composition functions can only change the `status` field of a composite -resource. By default, the `crossplane render` command only prints the -`status` field with `metadata.name`. +#### Function context -Use `--include-full-xr` to print the full composite resource, -including the `spec` and `metadata` fields. +The `--context-files` and `--context-values` flags pass data to each Function's +`context`. The context is JSON-formatted data. -### Mock managed resources +#### Function results -Provide mocked, or artificial data representing a managed resource with -`--observed-resources`. The `crossplane render` command treats the -provided inputs as if they were resources in a Crossplane cluster. +If a Function emits events with statuses, use `--include-function-results` +(`-r`) to print them alongside the rendered resources. -A function can reference and manipulate the included resource as part of -running the function. +#### Observed (mock) resources -The `observed-resources` may be a single YAML file with multiple resources or a -directory of YAML files representing multiple 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. -Inside the YAML file include an -{{}}apiVersion{{}}, -{{}}kind{{}}, -{{}}metadata{{}} and -{{}}spec{{}}. +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. -```yaml {label="apiVersion"} +```yaml apiVersion: example.org/v1alpha1 kind: ComposedResource metadata: @@ -172,930 +394,2035 @@ spec: coolerField: "I'm cooler!" ``` -The schema of the resource isn't validated and may contain any data. +#### 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](https://github.com/crossplane-contrib/function-extra-resources) +or the built-in support in +[function-go-templating](https://github.com/crossplane-contrib/function-go-templating?tab=readme-ov-file#extraresources). + +#### Examples + +Simulate creating a new XR: + +```shell +crossplane composition render xr.yaml composition.yaml functions.yaml +``` + +Simulate updating an XR that already exists: + +```shell +crossplane composition render xr.yaml composition.yaml functions.yaml \ + --observed-resources=existing-observed-resources.yaml +``` + +Pin the Crossplane version used for rendering: + +```shell +crossplane composition render xr.yaml composition.yaml functions.yaml \ + --crossplane-version=v2.3.0 +``` + +Use a local crossplane binary instead of Docker: + +```shell +crossplane composition render xr.yaml composition.yaml functions.yaml \ + --crossplane-binary=/usr/local/bin/crossplane +``` + +Pass context values to the Function pipeline: + +```shell +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: + +```shell +crossplane composition render xr.yaml composition.yaml functions.yaml \ + --required-resources=required-resources.yaml +``` + +Pass OpenAPI schemas for Functions that need them: + +```shell +crossplane composition render xr.yaml composition.yaml functions.yaml \ + --required-schemas=schemas/ +``` + +Pass credentials to Functions in the pipeline that need them: + +```shell +crossplane composition render xr.yaml composition.yaml functions.yaml \ + --function-credentials=credentials.yaml +``` + +Override function annotations for a remote Docker daemon: + +```shell +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: + +```shell +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 [] [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | A YAML file specifying the composite resource (XR) to render. | +| `` | A YAML file specifying the Composition to use to render the XR. Must be mode: Pipeline. | +| `[]` | *(optional)* A YAML file or directory of YAML files specifying the Composition Functions to use to render the XR. May be omitted when running in a project. | +{{< /table >}} + +#### Flags -### Mock extra resources +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--crossplane-version=VERSION` | Version of the Crossplane image to use for rendering (e.g. v2.3.0). Defaults to the latest stable version. | +| | `--crossplane-image=IMAGE` | Override the full Crossplane Docker image reference for rendering. | +| | `--crossplane-binary=PATH` | Path to a local crossplane binary to use instead of Docker. | +| | `--context-files=KEY=VALUE;...` | Comma-separated context key-value pairs to pass to the Function pipeline. Values must be files containing JSON/YAML. | +| | `--context-values=KEY=VALUE;...` | Comma-separated context key-value pairs to pass to the Function pipeline. Values must be JSON/YAML. Keys take precedence over --context-files. | +| `-r` | `--include-function-results` | Include informational and warning messages from Functions in the rendered output as resources of kind: Result. | +| `-x` | `--include-full-xr` | Include a direct copy of the input XR's spec and metadata fields in the rendered output. | +| `-o` | `--observed-resources=PATH` | A YAML file or directory of YAML files specifying the observed state of composed resources. | +| | `--extra-resources=PATH` | A YAML file or directory of YAML files specifying required resources (deprecated, use --required-resources). | +| `-e` | `--required-resources=PATH` | A YAML file or directory of YAML files specifying required resources to pass to the Function pipeline. | +| `-s` | `--required-schemas=DIR` | A directory of JSON files specifying OpenAPI v3 schemas (from kubectl get --raw /openapi/v3/). | +| `-c` | `--include-context` | Include the context in the rendered output as a resource of kind: Context. | +| | `--function-credentials=PATH` | A YAML file or directory of YAML files specifying credentials to use for Functions to render the XR. | +| `-a` | `--function-annotations=KEY=VALUE,...` | Override function annotations for all functions. Can be repeated. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +| | `--max-concurrency=8` | Maximum concurrency for building embedded functions. | +| `-f` | `--project-file="crossplane-project.yaml"` | Path to the project file. Optional. | +| | `--timeout=1m` | How long to run before timing out. | +| | `--xrd=PATH` | A YAML file specifying the CompositeResourceDefinition (XRD) that defines the XR's schema and properties. | +{{< /table >}} -Extra Resources allow a Composition to request Crossplane Objects on the cluster that aren't -part of the Composition. The `--extra-resources` option points at a directory containing -YAML manifests of resources to mock. Use Extra Resources in combination with a function like -[function-extra-resources](https://github.com/crossplane-contrib/function-extra-resources) or the -built-in support in [function-go-templating](https://github.com/crossplane-contrib/function-go-templating?tab=readme-ov-file#extraresources). -## xpkg + +## crossplane config + + +View and modify the crossplane CLI config file. + +The `config` command manages the configuration file for the `crossplane` +CLI. The config 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 config: + +```shell +crossplane config view +``` + +Enable alpha commands: + +```shell +crossplane config set features.enableAlpha true +``` -The `crossplane xpkg` commands create, install and update Crossplane -[packages]({{}}) and enable authentication -and publishing of Crossplane packages to a Crossplane package registry. +### Usage + +``` +crossplane config [flags] +``` -### xpkg build + +### crossplane config set + -Using `crossplane xpkg build` provides automation and simplification to build -Crossplane packages. - -The Crossplane CLI combines a directory of YAML files and packages them as -an [OCI container image](https://opencontainers.org/). +Set a config value and write it to the config file. -The CLI applies the required annotations and values to meet the -[Crossplane XPKG specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md). -The `crossplane` CLI supports building -[configuration]({{< ref "../packages/configurations" >}}), -[function]({{}}) and -[provider]({{}}) package types. -#### Flags +#### Usage -{{< table "table table-sm table-striped">}} +``` +crossplane config set +``` +#### Arguments -| Short flag | Long flag | Description | -| ------------ | ------------- | ------------------------------ | -| | `--embed-runtime-image=NAME` | The image name and tag of an image to include in the package. Only for provider and function packages. | -| | `--embed-runtime-image-tarball=PATH` | The filename of an image to include in the package. Only for provider and function packages. | -| `-e` | `--examples-root="./examples"` | The path to a directory of examples related to the package. | -| | `--ignore=PATH,...` | List of files and directories to ignore. | -| `-o` | `--package-file=PATH` | Directory and filename of the created package. | -| `-f` | `--package-root="."` | Directory to search for YAML files. | +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Config key to set (e.g. features.enableAlpha). | +| `` | Value to assign. | {{< /table >}} -The `crossplane xpkg build` command recursively looks in the directory set by -`--package-root` and attempts to combine any files ending in `.yml` or `.yaml` -into a package. -All YAML files must be valid Kubernetes manifests with `apiVersion`, `kind`, -`metadata` and `spec` fields. + + +### crossplane config view + + + +Print the current effective config as YAML. + + + +#### Usage + +``` +crossplane config view +``` + + + +## crossplane dependency + + + +[BETA] Manage dependencies of control plane Projects. + +NOTE: Beta features may be changed in a future release. + +### Usage + +``` +crossplane dependency [flags] +``` + + + +### crossplane dependency add + + + +[BETA] Add a dependency to the current project. + +NOTE: Beta features may be changed in a future release. + +The `dependency add` command adds a dependency to a Crossplane Project. The +dependency is added to the project's metadata file and language bindings +(schemas) are generated its CRDs when applicable. + +#### 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 thus get installed into a cluster when the Configuration is +installed. Build-time dependencies, on the other hand, are used only for schema +generation and do not become Configuration dependencies. Use the `--api-only` +flag to indicate that an xpkg dependency should be build-time only. + +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: + +```shell +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: + +```shell +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: + +```shell +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: + +```shell +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: + +```shell +crossplane dependency add https://github.com/kubernetes-sigs/cluster-api \ + --git-ref=release-1.11 --git-path=config/crd/bases +``` + +#### Usage + +``` +crossplane dependency add [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Package to be added (e.g. xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.5.0, k8s:v1.33.0, a git repo URL, or an HTTP URL). | +{{< /table >}} + +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition file. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +| | `--api-only` | Mark an xpkg dependency as API-only (not a runtime dependency). | +| | `--git-ref=STRING` | Git ref for CRD dependencies (branch, tag, or commit SHA). | +| | `--git-path=STRING` | Path within the git repository for CRD dependencies. | +{{< /table >}} + + + + +### crossplane dependency clean-cache + + + +[BETA] Clean the dependency cache. + +NOTE: Beta features may be changed in a future release. + +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" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition file. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +| | `--keep-packages` | Keep cached xpkg package contents; remove only generated schemas. | +{{< /table >}} + + + + +### crossplane dependency update-cache + + + +[BETA] Update the dependency cache for the current project. + +NOTE: Beta features may be changed in a future release. + +The `dependency update-cache` command updates the local dependency cache for the +current project. It caches all dependencies listed in the +`crossplane-project.yaml` file and re-generates language bindings (schemas) for +them if needed. Any dependency whose version is expressed as a semantic version +constraint will have the constraint re-resolved to a specific version (i.e., +schemas will be updated if a newer version is available). + +#### Usage + +``` +crossplane dependency update-cache [flags] +``` +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition file. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +| | `--git-token=STRING` | Token for git HTTPS authentication. | +| | `--git-username="x-access-token"` | Username for git HTTPS authentication. | +{{< /table >}} + + + + +## crossplane function + + + +[BETA] Work with functions in control plane Projects. + +NOTE: Beta features may be changed in a future release. + +### Usage + +``` +crossplane function [flags] +``` + + + +### crossplane function generate + + + +[BETA] Generate a Function for a Composition. + +NOTE: Beta features may be changed in a future release. + +The `function generate` command creates an embedded function in the specified +language under the project's `functions/` directory. If a path to a Composition +file is supplied, the new function is also idempotently added as a step to the +end of the Composition's pipeline. + +#### 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`: + +```shell +crossplane function generate fn1 +``` + +Create a Python function in `functions/fn2`: + +```shell +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: + +```shell +crossplane function generate compose-cluster apis/cluster/composition.yaml --language go +``` + +#### Usage + +``` +crossplane function generate [] [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Name of the function to generate. Must be a valid DNS-1035 label. | +| `[]` | *(optional)* Path to a Composition YAML file to add a pipeline step to. | +{{< /table >}} + +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-l` | `--language="go-templating"` | Language to use for the function. | +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition file. | +{{< /table >}} + + + + +## crossplane operation + + + +[ALPHA] Work with Crossplane Operations. + +NOTE: Alpha features are experimental and may be changed or removed in a future release. + +### Usage + +``` +crossplane operation [flags] +``` + + + +### crossplane operation render + + + +[ALPHA] Render an Operation. + +NOTE: Alpha features are experimental and may be changed or removed in a future release. + +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. + +{{}} +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 + +Operation Functions are pulled and run using Docker by default. You can add the +following annotations to each Function to change how they're run: + +{{
}} +| Annotation | Purpose | +| ---------- | ------- | +| `render.crossplane.io/runtime: "Development"` | Connect to a Function that is already running, instead of using Docker. This is useful to develop and debug new Functions. The Function must be listening at `localhost:9443` and running with the `--insecure` flag. | +| `render.crossplane.io/runtime-development-target: "dns:///example.org:7443"` | Connect to a Function running somewhere other than `localhost:9443`. The target uses gRPC target syntax (e.g., `dns:///example.org:7443` or simply `example.org:7443`). | +| `render.crossplane.io/runtime-docker-cleanup: "Orphan"` | Don't stop the Function's Docker container after rendering. | +| `render.crossplane.io/runtime-docker-name: ""` | Create a container with that name and reuse it as long as it is running or can be restarted. | +| `render.crossplane.io/runtime-docker-pull-policy: "Always"` | Always pull the Function's package, even if it already exists locally. Other supported values are `Never` or `IfNotPresent`. | +| `render.crossplane.io/runtime-docker-publish-address: "0.0.0.0"` | Host address that Docker should publish the Function's container port to. Defaults to `127.0.0.1` (localhost only). Use `0.0.0.0` to publish to all host network interfaces, enabling access from remote machines. | +| `render.crossplane.io/runtime-docker-target: "docker-host"` | Address that the render CLI should use to connect to the Function's Docker container. If not specified, uses the publish address. | +{{< /table >}} + +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](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) +reference. + +#### Project support + +When running `render` in a Crossplane Project (any directory containing a +`crossplane-project.yaml` project metadata file), it is optional to provide the +functions file as an argument. If the functions file is omitted, function +dependencies defined in the project metadata will be used. Embedded functions +from the project will also be built and run by render. + +#### Examples + +Render an Operation: + +```shell +crossplane operation render operation.yaml functions.yaml +``` + +Pin the Crossplane version used for rendering: + +```shell +crossplane operation render operation.yaml functions.yaml \ + --crossplane-version=v2.2.1 +``` + +Use a local crossplane binary instead of Docker: + +```shell +crossplane operation render operation.yaml functions.yaml \ + --crossplane-binary=/usr/local/bin/crossplane +``` + +Pass context values to the function pipeline: + +```shell +crossplane operation render operation.yaml functions.yaml \ + --context-values=apiextensions.crossplane.io/environment='{"key": "value"}' +``` + +Pass required resources functions can request: + +```shell +crossplane operation render operation.yaml functions.yaml \ + --required-resources=required-resources.yaml +``` + +Pass OpenAPI schemas for functions that need them: + +```shell +crossplane operation render operation.yaml functions.yaml \ + --required-schemas=schemas/ +``` + +Render a WatchOperation with a watched resource: + +```shell +crossplane operation render watchoperation.yaml functions.yaml \ + --watched-resource=watched-configmap.yaml +``` + +Pass credentials to functions that need them: + +```shell +crossplane operation render operation.yaml functions.yaml \ + --function-credentials=credentials.yaml +``` + +Include function results and context in output: + +```shell +crossplane operation render operation.yaml functions.yaml -r -c +``` + +Include the full Operation with original spec and metadata: + +```shell +crossplane operation render operation.yaml functions.yaml -o +``` + +Override function annotations for remote Docker daemon: + +```shell +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: + +```shell +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 [] [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | A YAML file specifying the Operation to render. | +| `[]` | *(optional)* A YAML file or directory of YAML files specifying the operation functions to use to render the Operation. May be omitted when running in a project. | +{{< /table >}} + +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--crossplane-version=VERSION` | Version of the Crossplane image to use for rendering (e.g. v2.3.0). Defaults to the latest stable version. | +| | `--crossplane-image=IMAGE` | Override the full Crossplane Docker image reference for rendering. | +| | `--crossplane-binary=PATH` | Path to a local crossplane binary to use instead of Docker. | +| | `--context-files=KEY=VALUE;...` | Comma-separated context key-value pairs to pass to the function pipeline. Values must be files containing JSON. | +| | `--context-values=KEY=VALUE;...` | Comma-separated context key-value pairs to pass to the function pipeline. Values must be JSON. Keys take precedence over --context-files. | +| | `--function-credentials=PATH` | A YAML file or directory of YAML files specifying credentials to use for functions. | +| `-a` | `--function-annotations=KEY=VALUE,...` | Override function annotations for all functions. Can be repeated. | +| `-c` | `--include-context` | Include the context in the rendered output as a resource of kind: Context. | +| `-o` | `--include-full-operation` | Include a direct copy of the input Operation's spec and metadata fields in the rendered output. | +| `-r` | `--include-function-results` | Include informational and warning messages from functions in the rendered output as resources of kind: Result. | +| `-e` | `--required-resources=PATH` | A YAML file or directory of YAML files specifying required resources to pass to the function pipeline. | +| | `--required-schemas=DIR` | A directory of JSON files specifying OpenAPI schemas to pass to the function pipeline. | +| `-w` | `--watched-resource=PATH` | A YAML file specifying the watched resource for WatchOperation rendering. The resource is also added to required resources. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +| | `--max-concurrency=8` | Maximum concurrency for building embedded functions. | +| `-f` | `--project-file="crossplane-project.yaml"` | Path to the project file. Optional. | +| | `--timeout=1m` | How long to run before timing out. | +{{< /table >}} + + + + +## crossplane project + + + +[BETA] Work with control plane Projects. + +NOTE: Beta features may be changed in a future release. + +### Usage + +``` +crossplane project [flags] +``` + + + +### crossplane project build + + + +[BETA] Build a project into Crossplane packages. + +NOTE: Beta features may be changed in a future release. + +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. A special `.xpkg` file containing all the built +packages is written to the project's output directory (`_output/` by +default). This file can be consumed by the `project push` command to push the +packages to an OCI registry. + +The repository for the built Configuration is taken from `spec.repository` in +`crossplane-project.yaml`. Override it for a single build with `--repository`. + +{{}} +The repository is used to construct the function names used for +embedded function references in compositions. The same repository must be +specified 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: + +```shell +crossplane project build +``` + +Build the project, overriding the repository: + +```shell +crossplane project build --repository=xpkg.crossplane.io/my-org/my-project +``` + +Build the project into a custom output directory: + +```shell +crossplane project build -o ./packages +``` + +#### Usage + +``` +crossplane project build [flags] +``` +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition. | +| | `--repository=STRING` | Override the repository in the project file. | +| `-o` | `--output-dir="_output"` | Output directory for packages. | +| | `--max-concurrency=8` | Max concurrent function builds. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +{{< /table >}} + + + + +### crossplane project init + + + +[BETA] Initialize a new project. + +NOTE: Beta features may be changed in a future release. + +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 project is +created in 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/`: + +```shell +crossplane project init my-project +``` + +Create a new project in a specific directory: + +```shell +crossplane project init my-project --directory ./projects/new-project +``` + +#### Usage + +``` +crossplane project init [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | The name of the new project. | +{{< /table >}} + +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-d` | `--directory=STRING` | Directory to initialize. Defaults to project name. | +{{< /table >}} + + + + +### crossplane project push + + + +[BETA] Push a built project to an OCI registry. + +NOTE: Beta features may be changed in a future release. + +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. Credentials for the registry +are taken 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`. + +{{}} +The repository is used to construct the function names used for +embedded function references in compositions. The same repository must be +specified when building and pushing a project. +{{< /hint >}} + +#### Examples + +Push the project's packages using the repository and a generated tag: + +```shell +crossplane project push +``` + +Push using an explicit tag: + +```shell +crossplane project push --tag=v1.2.3 +``` + +Push to a different repository than the one in the project file: + +```shell +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" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition. | +| | `--repository=STRING` | Override the repository in the project file. | +| `-t` | `--tag=""` | Tag for the pushed package. If not provided, a semver tag will be generated. | +| | `--package-file=STRING` | Package file to push. Defaults to /.xpkg. | +| `-o` | `--output-dir="_output"` | Directory containing built packages. | +| | `--max-concurrency=8` | Max concurrent function pushes. | +| | `--insecure-skip-tls-verify` | [INSECURE] Skip verifying TLS certificates. | +{{< /table >}} + + + + +### crossplane project run + + + +[BETA] Build and run a project in a local dev control plane. + +NOTE: Beta features may be changed in a future release. + +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 the control plane is named after the project. Use +`--control-plane-name` to choose a different name, which is useful when running +multiple projects side-by-side. + +The Crossplane version installed in the dev control plane can be pinned with +`--crossplane-version`; otherwise the latest stable version is used. + +Resources can be applied 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: + +```shell +crossplane project run +``` + +Run on a control plane with a specific name (created if it doesn't exist): + +```shell +crossplane project run --control-plane-name=my-dev-ctp +``` + +Pin the Crossplane version installed in the dev control plane: + +```shell +crossplane project run --crossplane-version=v2.2.1 +``` + +Apply `imageconfig.yaml` before installing the Configuration, and +`providerconfig.yaml` after: + +```shell +crossplane project run --init-resources=imageconfig.yaml --extra-resources=providerconfig.yaml +``` + +#### Usage + +``` +crossplane project run [flags] +``` +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition. | +| | `--repository=STRING` | Override the repository. | +| | `--max-concurrency=8` | Max concurrent builds. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +| | `--control-plane-name=STRING` | Name of the dev control plane. Defaults to project name. | +| | `--crossplane-version=STRING` | Version of Crossplane to install. | +| | `--registry-dir=STRING` | Directory for local registry images. | +| | `--cluster-admin` | Allow Crossplane cluster admin. | +| | `--timeout=5m` | Max wait for project readiness. | +| | `--init-resources=INIT-RESOURCES` | Resources to apply before installing. | +| | `--extra-resources=EXTRA-RESOURCES` | Resources to apply after installing. | +{{< /table >}} + + + + +### crossplane project stop + + + +[BETA] Tear down a local dev control plane. + +NOTE: Beta features may be changed in a future release. + +The `project stop` command tears down the local development control plane +previously created by `crossplane project run`. The KIND cluster and the local +OCI registry are both removed. + +When run from a project directory the control plane name is derived from the +project name. When run outside a project directory, pass `--control-plane-name` +to identify the control plane to tear down. Pass `--registry-dir` to point at +the local registry directory used by `project run` if it was overridden there. + +#### Examples + +Tear down the development control plane for the project in the current +directory: + +```shell +crossplane project stop +``` + +Tear down a specific local dev control plane by name: + +```shell +crossplane project stop --control-plane-name=my-dev-cp +``` + +#### Usage + +``` +crossplane project stop [flags] +``` +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition. | +| | `--control-plane-name=STRING` | Name of the dev control plane. Defaults to project name. | +| | `--registry-dir=STRING` | Directory for local registry images. | +{{< /table >}} + + + + +## crossplane resource + + + +[BETA] Work with Crossplane resources. + +NOTE: Beta features may be changed in a future release. + +### Usage + +``` +crossplane resource [flags] +``` + + + +### crossplane resource trace + + + +[BETA] Trace a Crossplane resource for troubleshooting. + +NOTE: Beta features may be changed in a future release. + +The `resource trace` command traces a Crossplane resource (Claim, Composite, or +Managed Resource) to give a detailed view of its relationships — helpful for +troubleshooting. + +The command requires a resource type and a resource name: + +```shell +crossplane resource trace +``` + +Kubernetes-style `/` input works too — for example, `crossplane +resource trace example.crossplane.io/my-xr`. + +If needed the resource kind can be specified further as +`TYPE[.VERSION][.GROUP]`, 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](https://graphviz.org/docs/layouts/dot/) graph). + +##### Wide output + +Use `--output=wide` to print the full `Ready` and `Status` messages even when +they exceed 64 characters, and additional per-kind columns (for example, +composed resource names for composite resources, or image used for packages). + +##### Graphviz dot output + +Use `--output=dot` to print a textual [Graphviz +dot](https://graphviz.org/docs/layouts/dot/) graph. Pipe to `dot` to render an +image: + +```shell +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 package dependencies are +displayed: + +- `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 which package revisions are shown: + +- `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`: + +```shell +crossplane resource trace mykind my-res -n my-ns +``` + +Trace all `MyKind` resources in the namespace `my-ns`: + +```shell +crossplane resource trace mykind -n my-ns +``` + +Wide format with full errors, condition messages, and kind-specific columns: + +```shell +crossplane resource trace mykind my-res -n my-ns -o wide +``` + +Show connection secret names alongside the resources: + +```shell +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: + +```shell +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: + +```shell +crossplane resource trace mykind my-res -n my-ns -o json | jq +``` + +Output debug logs to stderr while piping a dot graph to dot: + +```shell +crossplane resource trace mykind my-res -n my-ns -o dot --verbose | dot -Tpng -o output.png +``` + +Watch a resource continuously until it is deleted: + +```shell +crossplane resource trace mykind my-res -n my-ns --watch +``` + +#### Usage + +``` +crossplane resource trace [] [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Kind of the Crossplane resource, accepts the 'TYPE[.VERSION][.GROUP][/NAME]' format. | +| `[]` | *(optional)* Name of the Crossplane resource, can be passed as part of the resource too. | +{{< /table >}} + +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| `-c` | `--context=""` | Kubernetes context. | +| `-n` | `--namespace=""` | Namespace of the resource. | +| `-o` | `--output="default"` | Output format. One of: default, wide, json, dot, yaml. | +| `-s` | `--show-connection-secrets` | Show connection secrets in the output. | +| | `--show-package-dependencies="unique"` | Show package dependencies in the output. One of: unique, all, none. | +| | `--show-package-revisions="active"` | Show package revisions in the output. One of: active, all, none. | +| | `--show-package-runtime-configs` | Show package runtime configs in the output. | +| | `--concurrency=5` | load concurrency | +| `-w` | `--watch` | Watch for changes until the resource is deleted | +{{< /table >}} + + + + +### crossplane resource validate + + + +[BETA] Validate Crossplane resources. + +NOTE: Beta features may be changed in a future release. + +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 additional checks (such as unknown-field detection, a common source +of difficult-to-debug Crossplane issues). + +If Providers or Configurations are provided as extensions, they are downloaded +and loaded as CRDs before validation. If `--cache-dir` is not set, it defaults +to `~/.crossplane/cache`. Clean the cache before downloading schemas with +`--clean-cache`. + +All validation is performed offline using the Kubernetes API server's validation +library — no Crossplane instance or control plane is required. + +`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](https://kubernetes.io/docs/reference/using-api/cel/) (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 is not +required — only the ability to download the Provider package. + +Create a Provider manifest: + +```yaml +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: + +```yaml +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: + +```shell +crossplane resource validate provider.yaml managedResource.yaml +``` + +#### Validate render output + +Pipe the output of `crossplane composition render` to `validate` to check +complete Crossplane resource pipelines, including XRs, Compositions, and +Functions. Use `--include-full-xr` on `render`, and `-` (read stdin) on +`validate`: + +```shell +crossplane composition render xr.yaml composition.yaml func.yaml --include-full-xr | \ + crossplane resource validate schemas.yaml - +``` + +#### Validate CEL rules + +XRDs can define [validation +rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) +in CEL via `x-kubernetes-validations`. `validate` evaluates them: + +```yaml +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. Only `.yaml` and +`.yml` files are processed; other files are ignored. + +```text +schemas/ +├── platform-ref-aws.yaml +├── providers/ +│ └── provider-aws-iam.yaml +└── xrds/ + └── xrd.yaml +``` + +```shell +crossplane resource validate schemas/ resources.yaml +``` + +#### Examples + +Validate resources against extensions in extensions.yaml: + +```shell +crossplane resource validate extensions.yaml resources.yaml +``` + +Validate resources in a directory against extensions in another directory: + +```shell +crossplane resource validate crossplane.yaml,extensionsDir/ resourceDir/ +``` + +Pin the Crossplane image version used during validation: + +```shell +crossplane resource validate extensions.yaml resources.yaml \ + --crossplane-image=xpkg.crossplane.io/crossplane/crossplane:v1.20.0 +``` + +Skip success log lines (only print problems): + +```shell +crossplane resource validate extensionsDir/ resourceDir/ --skip-success-results +``` + +Validate the output of render against extensions in a directory: + +```shell +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: -#### Ignore files +```shell +crossplane resource validate extensionsDir/ resourceDir/ --cache-dir .cache --clean-cache +``` -Use `--ignore` to provide a list of files and directories to ignore. +#### Usage -For example, -`crossplane xpkg build --ignore="./test/*,kind-config.yaml"` +``` +crossplane resource validate [flags] +``` +#### Arguments -#### Set the package name +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Extension sources as a comma-separated list of files, directories, or '-' for standard input. | +| `` | Resource sources as a comma-separated list of files, directories, or '-' for standard input. | +{{< /table >}} -`crossplane` automatically names the new package a combination of the -`metadata.name` and a hash of the package contents and saves the contents -in the same location as `--package-root`. Define a specific location and -filename with `--package-file` or `-o`. +#### Flags -For example, -`crossplane xpkg build -o /home/crossplane/example.xpkg`. +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--cache-dir="~/.crossplane/cache"` | Absolute path to the cache directory where downloaded schemas are stored. | +| | `--clean-cache` | Clean the cache directory before downloading package schemas. | +| | `--crossplane-image=STRING` | Specify the Crossplane image to be used for validating the built-in schemas. | +| | `--error-on-missing-schemas` | Return non zero exit code if not all schemas are provided. | +| | `--skip-success-results` | Skip printing success results. | +| | `--update-cache` | Update cached schemas by downloading the latest version that satisfies a constraint. May be useful if you are using semantic version constraints and want to get the latest version, but this will slow down the cache lookup due to the required network calls. | +{{< /table >}} -#### Include examples + + +## crossplane version + + -Include YAML files demonstrating how to use the package with `--examples-root`. +Print the client and server version information for the current context. -#### Include a runtime image -Functions and Providers require YAML files describing their dependencies and -settings and a container image for their runtime. -Using `--embed-runtime-image` runs a specified image and -includes the image inside the function or provider package. +### Usage -{{}} -Images referenced with `--embed-runtime-image` must be in the local Docker -cache. +``` +crossplane version [flags] +``` +### Flags -Use `docker pull` to download a missing image. -{{< /hint >}} +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--client` | If true, shows client version only (no server required). | +{{< /table >}} -The `--embed-runtime-image-tarball` flag includes a local OCI image tarball -inside the function or provider package. -### xpkg init + +## crossplane xpkg + + +Work with Crossplane packages. -The `crossplane xpkg init` command populates the current directory with -files to build a package. +Crossplane can be extended using packages. Crossplane packages are called +*xpkgs*. Crossplane supports Configuration, Provider, and Function packages. -Provide a name to use for the package and the package template to start from -with the command -`crossplane xpkg init