diff --git a/content/master/cli/command-reference.md b/content/master/cli/command-reference.md index 64fac8b01..8b8396e53 100644 --- a/content/master/cli/command-reference.md +++ b/content/master/cli/command-reference.md @@ -4,164 +4,394 @@ 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 + + + -Read the [Crossplane CLI overview]({{}}) page for information on -installing `crossplane`. -## Global flags +A command line tool for interacting with Crossplane. -The following flags are available for all commands. +Please report issues and feature requests at https://github.com/crossplane/cli. -{{< 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 configuration file. | +| | `--verbose` | Print verbose logging statements. | {{< /table >}} + + + +## crossplane cluster + + + +[BETA] Inspect a Crossplane cluster. + +{{}} +Beta features may change in a future release. +{{< /hint >}} + +### Usage + +``` +crossplane cluster [flags] +``` + -## version +### crossplane cluster top -The `crossplane version` command returns the version of Crossplane CLI -and the control plane. +[BETA] Display resource (CPU/memory) usage by Crossplane related pods. + +{{}} +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](https://kubernetes-sigs.github.io/metrics-server/). + +#### Examples + +Show resource usage for all Crossplane pods in the `crossplane-system` +namespace: + +```shell +crossplane cluster top +``` + +Show resource usage for all Crossplane pods in the `default` namespace: + +```shell +crossplane cluster top -n default +``` + +Add a summary of resource usage for all Crossplane pods on top of the results: ```shell -crossplane version -Client Version: v1.17.0 -Server Version: v1.17.0 +crossplane cluster top -s +``` + +#### Usage + +``` +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)' + + + +### Usage + +``` +crossplane completions [flags] +``` +### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--uninstall` | | +{{< /table >}} + + + + +## crossplane composition + + + +Work with Crossplane Compositions. + + + +### Usage + +``` +crossplane composition [flags] ``` -## render + +### crossplane composition convert + -The `crossplane render` command previews the output of a -[composite resource]({{}}) after applying -any [composition functions]({{}}). +[BETA] Convert a Composition to a newer version. -{{< hint "important" >}} -The `crossplane render` command requires you to use composition functions. +{{}} +Beta features may change in a future release. {{< /hint >}} -The `crossplane render` command connects to the locally running Docker -Engine to pull and run composition functions. +The `composition convert` command converts a Crossplane composition to use a +different version or migrate away from features that are no longer supported. -{{}} -Running `crossplane render` requires [Docker](https://www.docker.com/). +The 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. + +{{}} +Beta features may change in a future release. {{< /hint >}} -Provide a composite resource, composition and composition function YAML -definition with the command to render the output locally. +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). -For example, -`crossplane render xr.yaml composition.yaml function.yaml` +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`. -The output includes the original composite resource followed by the generated -managed resources. +##### Examples -{{}} +Convert an existing pipeline mode Composition using native Composition +Environment to `function-environment-configs`: -```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 +```shell +crossplane composition convert composition-environment composition.yaml \ + -o composition-environment.yaml ``` -{{< /expand >}} +Use a different functionRef and output to stdout: -### Flags +```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 convert or '-' for stdin. | +{{< /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; omit for stdout. | +| | `--function-environment-configs-ref="function-environment-configs"` | Name of the installed function-environment-configs Function. | +{{< /table >}} + + + + +### crossplane composition generate + + + +[BETA] Generate a Composition for a CompositeResourceDefinition (XRD). -{{< table "table table-sm table-striped">}} +{{}} +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: + +```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 (for example, "postgres"): + +```shell +crossplane composition generate examples/database/database.yaml --plural postgreses +``` -| 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) | +Write the generated Composition to a specific path: +```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 >}} -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. +#### 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 referenced kind. | +| | `--path=STRING` | Output file. | +| `-f` | `--project-file="crossplane-project.yaml"` | Path to project definition file. | +| | `--cache-dir=STRING` | Directory for cached xpkg package contents. | +{{< /table >}} + + + + +### 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. -### Provide function context +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`. -The `--context-files` and `--context-values` flags can provide data -to a function's `context`. -The context is JSON formatted data. +{{}} +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: + +{{}} +| Annotation | Purpose | +| ---------- | ------- | +| `render.crossplane.io/runtime: "Development"` | Connect to a Function running locally, instead of using Docker, for example when developing or debugging a new Function. 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 (for example, `dns:///example.org:7443` or `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 or reuse a container with the given name. Restart the container if needed. | +| `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), you may omit the functions +file argument in favor of using function dependencies defined in the project +metadata and embedded functions from the project. -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 +402,2090 @@ spec: coolerField: "I'm cooler!" ``` -The schema of the resource isn't validated and may contain any data. +#### Required (extra) resources -### Mock 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). -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). +#### Examples - -## xpkg - +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. Optional 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. 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. Provide multiple annotations by repeating the argument. | +| | `--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 >}} -The `crossplane xpkg` commands create, install and update Crossplane -[packages]({{}}) and enable authentication -and publishing of Crossplane packages to a Crossplane package registry. -### xpkg build + +## crossplane config + -Using `crossplane xpkg build` provides automation and simplification to build -Crossplane packages. +View and update the crossplane CLI configuration file. -The Crossplane CLI combines a directory of YAML files and packages them as -an [OCI container image](https://opencontainers.org/). +The `config` command manages the configuration file for the `crossplane` +CLI. The configuration file location is, in priority order: -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). +1. The `--config` flag. +2. The `CROSSPLANE_CONFIG` environment variable. +3. `$XDG_CONFIG_HOME/crossplane/config.yaml` (or `~/.config/crossplane/config.yaml`). -The `crossplane` CLI supports building -[configuration]({{< ref "../packages/configurations" >}}), -[function]({{}}) and -[provider]({{}}) package types. +### Examples -#### Flags +Show the current effective configuration: -{{< table "table table-sm table-striped">}} +```shell +crossplane config view +``` -| 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 >}} +Enable alpha commands: -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. +```shell +crossplane config set features.enableAlpha true +``` -All YAML files must be valid Kubernetes manifests with `apiVersion`, `kind`, -`metadata` and `spec` fields. +### Usage -#### Ignore files +``` +crossplane config [flags] +``` + + + +### crossplane config set + + -Use `--ignore` to provide a list of files and directories to ignore. +Set a value and write it to the configuration file. -For example, -`crossplane xpkg build --ignore="./test/*,kind-config.yaml"` -#### Set the package name -`crossplane` automatically names the new package a combination of the -`metadata.name` and a hash of the package contents and saves the contents -in the same location as `--package-root`. Define a specific location and -filename with `--package-file` or `-o`. +#### Usage -For example, -`crossplane xpkg build -o /home/crossplane/example.xpkg`. +``` +crossplane config set +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Key to set (for example, features.enableAlpha). | +| `` | Value to assign. | +{{< /table >}} -#### Include examples + + +### crossplane config view + + + +Print the current effective configuration as YAML. + + + +#### Usage + +``` +crossplane config view +``` + + + +## crossplane dependency + + + +[BETA] Manage dependencies of control plane Projects. + +{{}} +Beta features may change in a future release. +{{< /hint >}} + +### Usage + +``` +crossplane dependency [flags] +``` + + + +### crossplane dependency add + + + +[BETA] Add a dependency to the current project. + +{{}} +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: + +```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 add (xpkg OCI reference, k8s:, git repository URL, or HTTP(S) 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 to CRDs in the git repository. | +{{< /table >}} + + + + +### crossplane dependency clean-cache + + + +[BETA] Clean the dependency cache. + +{{}} +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" >}} +| 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. + +{{}} +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" >}} +| 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. + +{{}} +Beta features may change in a future release. +{{< /hint >}} + +### Usage + +``` +crossplane function [flags] +``` + + + +### crossplane function generate + + + +[BETA] Generate a Function for a Composition. + +{{}} +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 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`: + +```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. + +{{}} +Alpha features are experimental and may change or disappear in a future release. +{{< /hint >}} + +### Usage + +``` +crossplane operation [flags] +``` + + + +### crossplane operation render + + + +[ALPHA] Render an Operation. + +{{}} +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. + +{{}} +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: + +{{
}} +| Annotation | Purpose | +| ---------- | ------- | +| `render.crossplane.io/runtime: "Development"` | Connect to a Function running locally, instead of using Docker, for example when developing or debugging a new Function. 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 (for example, `dns:///example.org:7443` or `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 or reuse a container with the given name. Restart the container if needed. | +| `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), 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: + +```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 Composition Functions to use to render the XR. Optional 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. 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. Provide multiple annotations by repeating the argument. | +| `-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. + +{{}} +Beta features may change in a future release. +{{< /hint >}} + +### Usage + +``` +crossplane project [flags] +``` + + + +### crossplane project build + + + +[BETA] Build a project into Crossplane packages. + +{{}} +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 packges from the +output file and push them to an OCI registry. + +The `build `command constructs the repository for the built Configuration from +`spec.repository` in `crossplane-project.yaml`. Override it for a single build +with `--repository`. + +{{}} +The 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: + +```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. + +{{}} +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/`: + +```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. + +{{}} +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`. + +{{}} +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: + +```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. Defaults to a time-based semver-like tag. | +| | `--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. + +{{}} +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: + +```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` | Grant Crossplane the cluster-admin role. | +| | `--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. + +{{}} +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 `up project run`, pass it to `up project stop` as +well to clean up the registry data. + +#### Examples + +Tear down the development control plane for the project in the current +directory: + +```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. + +{{}} +Beta features may change in a future release. +{{< /hint >}} + +### Usage + +``` +crossplane resource [flags] +``` + + + +### crossplane resource trace + + + +[BETA] Trace a Crossplane resource for troubleshooting. + +{{}} +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: + +```shell +crossplane resource trace +``` + +Kubernetes-style `/` 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](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 other kind-specific printer columns. + +##### 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 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`: + +```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 its deletion: + +```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, if not passed as part of the resource. | +{{< /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 resource deletion. | +{{< /table >}} + + + + +### crossplane resource validate + + + +[BETA] Validate Crossplane resources. + +{{}} +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](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 isn't +required as `validate` downloads the Provider extracts it locally. + +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 validate +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 Common Expression Language 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 to use for +validation. It ignores any files with extensions other than `.yml` or `.yaml`. + +```plaintext +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: + +```shell +crossplane resource validate extensionsDir/ resourceDir/ --cache-dir .cache --clean-cache +``` + +#### Usage + +``` +crossplane resource validate [flags] +``` +#### Arguments + +{{< 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 >}} + +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--cache-dir="~/.crossplane/cache"` | Absolute path to the cache directory for downloaded schemas. | +| | `--clean-cache` | Clean the cache directory before downloading package schemas. | +| | `--crossplane-image=STRING` | Specify the Crossplane image for validating built-in schemas. | +| | `--error-on-missing-schemas` | Return non zero exit code if missing schemas. | +| | `--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 slows down the cache lookup due to the required network calls. | +{{< /table >}} + + + + +## 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 + -The `crossplane xpkg init` command populates the current directory with -files to build a package. +Work with Crossplane packages. -Provide a name to use for the package and the package template to start from -with the command -`crossplane xpkg init