diff --git a/config.yaml b/config.yaml index 4292df67c..7484a7429 100644 --- a/config.yaml +++ b/config.yaml @@ -96,8 +96,8 @@ params: # The current "latest" version. Used in the version dropdown latest: "2.3" # The current "latest" version of the CLI docs. Used in the CLI version - # dropdown. Tracked separately from the core "latest" so the two can diverge. - cliLatest: "2.3" + # dropdown. + cliLatest: "2.4" docs: true anchors: # Generate heading anchors for any heading between min and max diff --git a/content/cli/v2.4/_index.md b/content/cli/v2.4/_index.md new file mode 100644 index 000000000..f9465e995 --- /dev/null +++ b/content/cli/v2.4/_index.md @@ -0,0 +1,74 @@ +--- +weight: 50 +title: CLI Overview +description: "Command-line tools for Crossplane development" +cascade: + version: "2.4" +--- + +The Crossplane CLI helps simplify some development and administration aspects of +Crossplane. + +The Crossplane CLI includes commands for: + +* building, installing, updating and pushing Crossplane Packages +* building platforms using Crossplane Projects +* testing and rendering standalone Composition Functions without the need to + access a Kubernetes cluster running Crossplane +* troubleshooting Crossplane Compositions, Composite Resources and Managed + Resources + +## Installing the CLI + +The Crossplane CLI is a single standalone binary with no external +dependencies. Some commands, such as `crossplane composition render` and +`crossplane project build`, do require a Docker compatible container runtime. + +{{}} +Install the Crossplane CLI on a user's computer. + +Most Crossplane CLI commands are independent of Kubernetes and +don't require access to a Crossplane pod. +{{< /hint >}} + +You can download the latest version using the install script: + +```shell +curl -sfL "https://cli.crossplane.io/install.sh" | sh +``` + +[The script](https://raw.githubusercontent.com/crossplane/cli/main/install.sh) +detects your operating system and CPU architecture and downloads the appropriate +binary to the current directory. Note that it doesn't attempt to place the +binary in your shell's `$PATH`, so you may want to move it. + +{{}} + +If you don't want to run shell script you can manually download a binary from +the Crossplane releases repository at +https://cli.crossplane.io/stable/current/bin + +Move the binary to a location in your `$PATH`, for example `/usr/local/bin`. +{{< /expand >}} + +### Download other CLI versions + +You can download different Crossplane CLI versions or different release branches +with the `XP_CHANNEL` and `XP_VERSION` environmental variables. + +By default the CLI installs from the `XP_CHANNEL` named `stable` and the +`XP_VERSION` of `current`, matching the most recent stable release. + +For example, to install CLI version `v2.3.0` add `XP_VERSION=v2.3.0` to the +download script curl command: + +```shell +curl -sfL "https://cli.crossplane.io/install.sh" | XP_VERSION=v2.3.0 sh +``` + +To install the latest build from the `main` branch, use the `master` channel by +adding `XP_CHANNEL=master`: + +```shell +curl -sfL "https://cli.crossplane.io/install.sh" | XP_CHANNEL=master sh +``` diff --git a/content/cli/v2.4/command-reference.md b/content/cli/v2.4/command-reference.md new file mode 100644 index 000000000..60b9a7c1a --- /dev/null +++ b/content/cli/v2.4/command-reference.md @@ -0,0 +1,2799 @@ +--- +weight: 100 +title: Command Reference +description: "Command reference for the Crossplane CLI" +--- + + + + + + + +This documentation is for the `crossplane` CLI `v2.4.0`. + + + + +# crossplane + + + + + +A command line tool for interacting with Crossplane. + +Please report issues and feature requests at https://github.com/crossplane/cli. + +## Usage + +``` +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] +``` + + + +### crossplane cluster top + + + +[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 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. | +| | `--as=STRING` | Username to impersonate for the operation. User could be a regular user or a service account in a namespace. | +| | `--as-group=AS-GROUP` | Group to impersonate for the operation. Repeat to specify multiple groups. | +| | `--as-uid=STRING` | UID to impersonate for the operation. | +{{< /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] +``` + + + +### crossplane composition convert + + + +[BETA] Convert a Composition to a newer version. + +{{}} +Beta features may change in a future release. +{{< /hint >}} + +The `composition convert` command converts a Crossplane composition to use a +different version or migrate away from features that are no longer supported. + +The supported conversions are: + +- Native Composition Environment → `function-environment-configs` + +#### Usage + +``` +crossplane composition convert +``` + + + +#### crossplane composition convert composition-environment + + + +[BETA] Convert a Pipeline Composition to use function-environment-configs. + +{{}} +Beta features may change in a future release. +{{< /hint >}} + +The `composition convert composition-environment` command converts a Crossplane +Composition to use `function-environment-configs` in place of native Composition +Environments (removed in Crossplane 1.18). + +It adds a function pipeline step using +`crossplane-contrib/function-environment-configs` if needed. By default the +function name is `function-environment-configs`, but this can be overridden with +`--function-environment-configs-ref`. + +##### Examples + +Convert an existing pipeline mode Composition using native Composition +Environment to `function-environment-configs`: + +```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 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). + +{{}} +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 +``` + +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 >}} + +#### 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. + +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`. + +{{}} +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 >}} + +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. + +#### Function context + +The `--context-files` and `--context-values` flags pass data to each Function's +`context`. The context is JSON-formatted data. + +#### Function results + +If a Function emits events with statuses, use `--include-function-results` +(`-r`) to print them alongside the rendered resources. + +#### Observed (mock) resources + +`--observed-resources` (`-o`) lets you pass mocked managed resources to the +Function pipeline. `render` treats those inputs as if they were resources +observed in a Crossplane cluster, so Functions can reference and manipulate +them. + +The argument may be a single YAML file containing multiple resources or a +directory of YAML files. The schema of the mocked resources isn't validated and +may contain any data. + +```yaml +apiVersion: example.org/v1alpha1 +kind: ComposedResource +metadata: + name: test-render-b + annotations: + crossplane.io/composition-resource-name: resource-b +spec: + coolerField: "I'm cooler!" +``` + +#### Required (extra) resources + +Required resources let a Composition request Crossplane objects on the cluster +that aren't part of the Composition. Pass them with `--required-resources` +(`-e`), a YAML file or directory of YAML files of resources to mock. Use this +with a Function like +[function-extra-resources](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. 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. | +| | `--crossplane-docker-network=STRING` | The docker network to start the crossplane container in | +| | `--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). Provide multiple files by repeating the argument. | +| `-e` | `--required-resources=PATH` | A YAML file or directory of YAML files specifying required resources to pass to the Function pipeline. Provide multiple files by repeating the argument. | +| `-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 >}} + + + + + +## crossplane config + + + +View and update the crossplane CLI configuration file. + +The `config` command manages the configuration file for the `crossplane` +CLI. The configuration file location is, in priority order: + +1. The `--config` flag. +2. The `CROSSPLANE_CONFIG` environment variable. +3. `$XDG_CONFIG_HOME/crossplane/config.yaml` (or `~/.config/crossplane/config.yaml`). + +### Examples + +Show the current effective configuration: + +```shell +crossplane config view +``` + +Enable alpha commands: + +```shell +crossplane config set features.enableAlpha true +``` + +### Usage + +``` +crossplane config [flags] +``` + + + + + +### crossplane config set + + + +Set a value and write it to the configuration file. + + + +#### Usage + +``` +crossplane config set +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Key to set (for example, features.enableAlpha). | +| `` | Value to assign. | +{{< /table >}} + + + + + + +### 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 the end of a Composition's pipeline when given a +Composition path. + +#### Supported languages + +The following are valid arguments to the `--language` / `-l` flag: + +- `go-templating` (default) +- `go` +- `kcl` +- `python` + +#### Examples + +Create a function with the default language (`go-templating`) in +`functions/fn1`: + +```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. | +| | `--crossplane-docker-network=STRING` | The docker network to start the crossplane container in | +| | `--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. Provide multiple files by repeating the argument. | +| | `--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 packages from +the output file and push them to an OCI registry. + +The `build` command constructs the repository for the built Configuration from +`spec.repository` in `crossplane-project.yaml`. Override it for a single build +with `--repository`. + +{{}} +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 | +| `-r` | `--registry="example.com/my-org"` | Override the registry in the project file. | +| | `--repository=STRING` | Override the repository name in the project file. Defaults to the 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 `crossplane project run`, pass it to `crossplane +project stop` as well to clean up the registry data. + +#### Examples + +Tear down the development control plane for the project in the current +directory: + +```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. | +| | `--as=STRING` | Username to impersonate for the operation. User could be a regular user or a service account in a namespace. | +| | `--as-group=AS-GROUP` | Group to impersonate for the operation. Repeat to specify multiple groups. | +| | `--as-uid=STRING` | UID to impersonate for the operation. | +{{< /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 +``` + +Emit machine-readable results (JSON or YAML) for piping to `jq`, scripts, or +CI systems. The structured payload includes per-resource status and +field-level error details: + +```shell +crossplane resource validate extensionsDir/ resourceDir/ --output json | jq . +``` + +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. | +| `-o` | `--output=text` | Output format for validation results (text, json, or yaml). | +| | `--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 + + + +Print the client and server version information for the current context. + + + +### Usage + +``` +crossplane version [flags] +``` +### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--client` | If true, shows client version only (no server required). | +| | `--as=STRING` | Username to impersonate for the operation. User could be a regular user or a service account in a namespace. | +| | `--as-group=AS-GROUP` | Group to impersonate for the operation. Repeat to specify multiple groups. | +| | `--as-uid=STRING` | UID to impersonate for the operation. | +{{< /table >}} + + + + +## crossplane xpkg + + + +Work with Crossplane packages. + +Crossplane packages, called *xpkgs*, allow you to add capabilities to your +Crossplane installation. Crossplane supports Configuration, Provider, and +Function packages. + +A package is an opinionated OCI image that contains everything needed to extend +a Crossplane control plane with new capabilities. For example, installing a +Provider package extends Crossplane with support for new kinds of managed +resource (MRs). + +See [the Crossplane packages documentation](https://docs.crossplane.io/latest/packages) +for more information. + +### Usage + +``` +crossplane xpkg [flags] +``` + + + +### crossplane xpkg batch + + + +Batch build and push a family of provider packages. + + + +#### Usage + +``` +crossplane xpkg batch --family-base-image=STRING --provider-name=STRING --family-package-url-format=STRING [flags] +``` +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--family-base-image=STRING` | **Required.** Family image used as the base for the smaller provider packages. | +| | `--provider-name=STRING` | **Required.** Provider name prefix, such as provider-aws, for smaller provider package repositories. | +| | `--family-package-url-format=STRING` | **Required.** Family package URL format for the smaller provider packages. Must be a valid OCI image URL containing the format specifier '%s', substituted with -. | +| | `--smaller-providers=monolith,...` | Smaller provider names to build and push, such as ec2, eks, or s3. | +| | `--concurrency=0` | Maximum number of packages to process concurrently. 0 puts no limit on the concurrency, processing all packages in parallel. | +| | `--push-retry=3` | Number of retries when pushing a provider package fails. | +| | `--platform=linux_amd64,linux_arm64,...` | Platforms to build the packages for. Each platform must use the _ syntax. An example is: linux_arm64. | +| `-p` | `--provider-bin-root=STRING` | Provider binary paths root. Smaller provider binaries must be under the platform directories in this folder. | +| `-o` | `--output-dir=STRING` | Path of the package output directory. | +| | `--store-packages=STORE-PACKAGES,...` | Smaller provider names whose provider package must be under the package output directory specified with the --output-dir option. | +| | `--package-metadata-template="./package/crossplane.yaml.tmpl"` | Smaller provider metadata template. The template variables {{ .Service }} and {{ .Name }} are always set; you may supply optional variables via --service-metadata and --template-var (the latter overrides on key conflicts). | +| | `--template-var=KEY=VALUE;...` | Smaller provider metadata template variables for the specified template. | +| | `--service-metadata=STRING` | Optional YAML file of per smaller-provider template variables. Top-level keys are smaller provider names (such as ec2, elb). Each entry is a map of variable names to scalars or lists; values get merged into the package metadata template as-is. Templates may use generic helpers toYAML and indent (YAML via gopkg.in/yaml.v3). Merged before --template-var. | +| | `--examples-group-override=KEY=VALUE;...` | Overrides for the location of the example manifests folder of a smaller provider. | +| | `--crd-group-override=KEY=VALUE;...` | Overrides for the locations of the CRD folders of the smaller providers. | +| | `--package-repo-override=KEY=VALUE;...` | Overrides for the package repository names of the smaller providers. | +| `-e` | `--examples-root="./examples"` | Path to package examples directory. | +| | `--crd-root="./package/crds"` | Path to package CRDs directory. | +| | `--ignore=IGNORE,...` | Paths to exclude from the smaller provider packages. | +| | `--build-only` | Only build the smaller provider packages and don't push them to a package repository. | +| | `--provider-name-suffix-for-push=STRING` | Suffix for provider name when pushing the packages, to add to the service name for the corresponding provider before the service-scoped name. Examples: provider-family-aws-suffix, provider-aws-suffix-s3 | +{{< /table >}} + + + + +### crossplane xpkg build + + + +Build a new package. + +The `xpkg build` command builds a package file from a local directory of +files. The CLI combines a directory of YAML files and packages them as an +[OCI container image](https://opencontainers.org/), applying the annotations and +values required by the +[Crossplane XPKG specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md). + +`crossplane xpkg build` supports building Configuration, Function, and Provider +package types. + +The command recursively looks in `--package-root` for files ending in `.yml` or +`.yaml` and attempts to combine them into a package. All YAML files must be +valid Kubernetes manifests with `apiVersion`, `kind`, `metadata`, and `spec` +fields. + +#### Ignore files + +Use `--ignore` to provide a comma-separated list of globs specifying files to +exclude from the build, relative to `--package-root`. + +```shell +crossplane xpkg build --ignore="./test/*,kind-config.yaml" +``` + +#### Set the package name + +By default, the `build` command constructs the package filename using a +combination of `metadata.name` and a hash of the package contents, and writes it +to `--package-root`. Override the location and filename with `--package-file` +(`-o`): + +```shell +crossplane xpkg build -o /home/crossplane/example.xpkg +``` + +#### Include examples + +Include YAML files demonstrating how to use the package with `--examples-root` +(`-e`). Defaults to `./examples`. + +#### Include a runtime image + +Function and Provider packages embed a controller container image. Configuration +packages don't have a runtime image. + +{{}} +Images referenced with `--embed-runtime-image` must be in the local +Docker cache. Use `docker pull` to download a missing image. +{{< /hint >}} + +Use `--embed-runtime-image-tarball` to embed a local OCI image tarball instead +of an image from the Docker cache. + +#### Examples + +Build a package from the files in the 'package' directory: + +```shell +crossplane xpkg build --package-root=package/ +``` + +Build a Provider package that embeds the controller OCI image so the package can +also run the provider. + +```shell +crossplane xpkg build --embed-runtime-image=cc873e13cdc1 +``` + +#### Usage + +``` +crossplane xpkg build [flags] +``` +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--embed-runtime-image=NAME` | An OCI image to embed in the package as its runtime. | +| | `--embed-runtime-image-tarball=PATH` | An OCI image tarball to embed in the package as its runtime. | +| `-e` | `--examples-root="./examples"` | A directory of example YAML files to include in the package. | +| | `--ignore=PATH,...` | Comma-separated file paths, specified relative to --package-root, to exclude from the package. Crossplane supports wildcards. You can't exclude directories. | +| `-o` | `--package-file=PATH` | The file to write the package to. Defaults to a generated filename in --package-root. | +| `-f` | `--package-root="."` | The directory that contains the package's crossplane.yaml file. | +{{< /table >}} + + + + +### crossplane xpkg extract + + + +Extract package contents into a Crossplane cache compatible format. Fetches from a remote registry by default. + + + +#### Usage + +``` +crossplane xpkg extract [] [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `[]` | *(optional)* Name of the package to extract. Must be a valid and fully qualified OCI image tag or a path if using --from-xpkg. | +{{< /table >}} + +#### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +|------------|-----------|-------------| +| | `--from-daemon` | Fetch the image from the Docker daemon. | +| | `--from-xpkg` | Extract a local xpkg file. If package isn't specified, implies the only one in the current directory. | +| `-o` | `--output="out.gz"` | Package output file. Extension must be .gz. | +{{< /table >}} + + + + +### crossplane xpkg get-crds + + + +Download CRDs from package dependencies. + +The `xpkg get-crds` command downloads CRDs from Crossplane package +dependencies (providers, functions, configurations) and writes them as YAML +files to the specified output directory. With `--json-schema`, it extracts the +OpenAPI v3 schemas from CRDs and writes them as JSON Schema files suitable for +use with YAML language servers. + +By default, the command organizes files by API group and version (for example, +`//.{yaml|json}`). Use `--flat` to write all files +directly to the output directory without subfolders. + +It accepts the same extension sources as the `validate` command: +`crossplane.yaml` files, directories containing package manifests, or +Provider/Function/Configuration resources. + +#### Examples + +- Download CRDs organized by group: + + ```shell + crossplane xpkg get-crds crossplane.yaml --output-dir ./crds + ``` + +- Download CRDs as flat files: + + ```shell + crossplane xpkg get-crds crossplane.yaml --output-dir ./crds --flat + ``` + +- Download JSON Schemas for YAML language server: + +```shell +crossplane xpkg get-crds crossplane.yaml --output-dir ./schemas --json-schema +``` + +- Download CRDs from multiple sources: + + ```shell + crossplane xpkg get-crds crossplane.yaml,providers/ --output-dir ./crds + ``` + +- Force re-download of cached schemas: + + ```shell + crossplane xpkg get-crds crossplane.yaml --output-dir ./crds --clean-cache + ``` + +#### Usage + +``` +crossplane xpkg get-crds [flags] +``` +#### Arguments + +{{< table "table table-sm table-striped" >}} +| Argument | Description | +|----------|-------------| +| `` | Extension 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 holding downloaded schemas. | +| | `--clean-cache` | Clean the cache directory before downloading package schemas. | +| | `--crossplane-image=STRING` | Specify the Crossplane image for fetching the built-in schemas. | +| | `--flat` | Write files to a flat directory instead of organizing by group and version. | +| | `--json-schema` | Write JSON Schema files instead of CRDs. Useful for YAML language server integration. | +| | `--no-cache` | Disable caching entirely. The command downloads schemas every time without storing them. | +| `-o` | `--output-dir="."` | Directory that receives the CRD or JSON Schema files. Defaults to current directory. | +| | `--update-cache` | Update cached schemas by downloading the latest version that satisfies a constraint. | +{{< /table >}} + + + + +### crossplane xpkg init + + + +Initialize a new package from a template. + +The `xpkg init` command initializes a directory that you can use to build a +package. It uses a template to initialize the directory, and can use any Git +repository as a template. + +Specify either a full Git URL or one of the following names as the template: + +- `configuration-template` ([https://github.com/crossplane/configuration-template](https://github.com/crossplane/configuration-template)) +- `function-template-go` ([https://github.com/crossplane/function-template-go](https://github.com/crossplane/function-template-go)) +- `function-template-python` ([https://github.com/crossplane/function-template-python](https://github.com/crossplane/function-template-python)) +- `provider-template` ([https://github.com/crossplane/provider-template](https://github.com/crossplane/provider-template)) +- `provider-template-upjet` ([https://github.com/crossplane/upjet-provider-template](https://github.com/crossplane/upjet-provider-template)) + + +#### `NOTES.txt` + +The `init` command prints the contents of any `NOTES.txt` file in the template +root after initializing the directory. Useful for instructions on how to use the +template. + +#### `init.sh` + +The `init` command executes any `init.sh` file in the template root (after user +confirmation). Useful for scripts that personalize the template. Pass `-r` +(`--run-init-script`) to run the script without prompting. + +#### Examples + +Initialize a new Go Composition Function named function-example: + +```shell +crossplane xpkg init function-example function-template-go +``` + +Initialize a new Provider named provider-example from a custom template: + +```shell +crossplane xpkg init provider-example https://github.com/crossplane/provider-template-custom +``` + +Initialize a new Go Composition Function and run its init.sh script (if any) +without prompting or displaying its contents: + +```shell +crossplane xpkg init function-example function-template-go --run-init-script +``` + +#### Usage + +``` +crossplane xpkg init