mirror of https://github.com/crossplane/docs.git
1096 lines
59 KiB
Markdown
1096 lines
59 KiB
Markdown
---
|
|
weight: 50
|
|
title: Command Reference
|
|
description: "Command reference for the Crossplane CLI"
|
|
---
|
|
|
|
|
|
<!-- vale Google.Headings = NO -->
|
|
The `crossplane` CLI provides utilities to make using Crossplane easier.
|
|
|
|
Read the [Crossplane CLI overview]({{<ref "../cli">}}) page for information on
|
|
installing `crossplane`.
|
|
|
|
## Global flags
|
|
|
|
The following flags are available for all commands.
|
|
|
|
{{< table "table table-sm table-striped">}}
|
|
|
|
| Short flag | Long flag | Description |
|
|
|------------|-------------|------------------------------|
|
|
| `-h` | `--help` | Show context sensitive help. |
|
|
| | `--verbose` | Print verbose output. |
|
|
|
|
{{< /table >}}
|
|
|
|
## version
|
|
|
|
The `crossplane version` command returns the version of Crossplane CLI
|
|
and the control plane.
|
|
|
|
```shell
|
|
crossplane version
|
|
Client Version: v1.17.0
|
|
Server Version: v1.17.0
|
|
```
|
|
|
|
## render
|
|
|
|
The `crossplane render` command previews the output of a
|
|
[composite resource]({{<ref "../concepts/composite-resources">}}) after applying
|
|
any [composition functions]({{<ref "../concepts/compositions">}}).
|
|
|
|
{{< hint "important" >}}
|
|
The `crossplane render` command requires you to use composition functions.
|
|
{{< /hint >}}
|
|
|
|
The `crossplane render` command connects to the locally running Docker
|
|
Engine to pull and run composition functions.
|
|
|
|
{{<hint "important">}}
|
|
Running `crossplane render` requires [Docker](https://www.docker.com/).
|
|
{{< /hint >}}
|
|
|
|
Provide a composite resource, composition and composition function YAML
|
|
definition with the command to render the output locally.
|
|
|
|
For example,
|
|
`crossplane render xr.yaml composition.yaml function.yaml`
|
|
|
|
The output includes the original composite resource followed by the generated
|
|
managed resources.
|
|
|
|
{{<expand "An example render output" >}}
|
|
|
|
```yaml
|
|
---
|
|
apiVersion: nopexample.org/v1
|
|
kind: XBucket
|
|
metadata:
|
|
name: test-xrender
|
|
status:
|
|
bucketRegion: us-east-2
|
|
---
|
|
apiVersion: s3.aws.upbound.io/v1beta1
|
|
kind: Bucket
|
|
metadata:
|
|
annotations:
|
|
crossplane.io/composition-resource-name: my-bucket
|
|
generateName: test-xrender-
|
|
labels:
|
|
crossplane.io/composite: test-xrender
|
|
ownerReferences:
|
|
- apiVersion: nopexample.org/v1
|
|
blockOwnerDeletion: true
|
|
controller: true
|
|
kind: XBucket
|
|
name: test-xrender
|
|
uid: ""
|
|
spec:
|
|
forProvider:
|
|
region: us-east-2
|
|
```
|
|
|
|
{{< /expand >}}
|
|
|
|
### Flags
|
|
|
|
{{< table "table table-sm table-striped">}}
|
|
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------- | ------------------------------ |
|
|
| | `--context-files=<key>=<file>,<key>=<file>` | A comma separated list of files to load for function "contexts." |
|
|
| | `--context-values=<key>=<value>,<key>=<value>` | 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=<directory or file>` | 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) |
|
|
|
|
{{< /table >}}
|
|
|
|
The `crossplane render` command relies on standard
|
|
[Docker environmental variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables)
|
|
to connect to the local Docker Engine and run composition functions.
|
|
|
|
### Provide function context
|
|
|
|
The `--context-files` and `--context-values` flags can provide data
|
|
to a function's `context`.
|
|
The context is JSON formatted data.
|
|
|
|
### Include function results
|
|
|
|
If a function produces Kubernetes events with statuses use the
|
|
`--include-function-results` to print them along with the managed resource
|
|
outputs.
|
|
|
|
### Include the composite resource
|
|
|
|
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`.
|
|
|
|
Use `--include-full-xr` to print the full composite resource,
|
|
including the `spec` and `metadata` fields.
|
|
|
|
### Mock managed resources
|
|
|
|
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.
|
|
|
|
A function can reference and manipulate the included resource as part of
|
|
running the function.
|
|
|
|
The `observed-resources` may be a single YAML file with multiple resources or a
|
|
directory of YAML files representing multiple resources.
|
|
|
|
Inside the YAML file include an
|
|
{{<hover label="apiVersion" line="1">}}apiVersion{{</hover>}},
|
|
{{<hover label="apiVersion" line="2">}}kind{{</hover>}},
|
|
{{<hover label="apiVersion" line="3">}}metadata{{</hover>}} and
|
|
{{<hover label="apiVersion" line="7">}}spec{{</hover>}}.
|
|
|
|
```yaml {label="apiVersion"}
|
|
apiVersion: example.org/v1alpha1
|
|
kind: ComposedResource
|
|
metadata:
|
|
name: test-render-b
|
|
annotations:
|
|
crossplane.io/composition-resource-name: resource-b
|
|
spec:
|
|
coolerField: "I'm cooler!"
|
|
```
|
|
|
|
The schema of the resource isn't validated and may contain any data.
|
|
|
|
### Mock Extra Resources
|
|
|
|
Extra Resources allow a Composition to request Crossplane Objects on the cluster that aren't
|
|
part of the Composition. The `--extra-resources` option points at a directory containing
|
|
YAML manifests of resources to mock. Use Extra Resources in combination with a function like
|
|
[function-extra-resources](https://github.com/crossplane-contrib/function-extra-resources) or the
|
|
built-in support in [function-go-templating](https://github.com/crossplane-contrib/function-go-templating?tab=readme-ov-file#extraresources).
|
|
|
|
## xpkg
|
|
|
|
The `crossplane xpkg` commands create, install and update Crossplane
|
|
[packages]({{<ref "../concepts/packages">}}) as well as enable authentication
|
|
and publishing of Crossplane packages to a Crossplane package registry.
|
|
|
|
### xpkg build
|
|
|
|
Using `crossplane xpkg build` provides automation and simplification to build
|
|
Crossplane packages.
|
|
|
|
The Crossplane CLI combines a directory of YAML files and packages them as
|
|
an [OCI container image](https://opencontainers.org/).
|
|
|
|
The CLI applies the required annotations and values to meet the
|
|
[Crossplane XPKG specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md).
|
|
|
|
The `crossplane` CLI supports building
|
|
[configuration]({{< ref "../concepts/packages" >}}),
|
|
[function]({{<ref "../concepts/compositions">}}) and
|
|
[provider]({{<ref "../concepts/providers" >}}) package types.
|
|
|
|
#### Flags
|
|
|
|
{{< table "table table-sm table-striped">}}
|
|
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------- | ------------------------------ |
|
|
| | `--embed-runtime-image-name=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 >}}
|
|
|
|
The `crossplane xpkg build` command recursively looks in the directory set by
|
|
`--package-root` and attempts to combine any files ending in `.yml` or `.yaml`
|
|
into a package.
|
|
|
|
All YAML files must be valid Kubernetes manifests with `apiVersion`, `kind`,
|
|
`metadata` and `spec` fields.
|
|
|
|
#### Ignore files
|
|
|
|
Use `--ignore` to provide a list of files and directories to ignore.
|
|
|
|
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`.
|
|
|
|
For example,
|
|
`crossplane xpkg build -o /home/crossplane/example.xpkg`.
|
|
|
|
|
|
#### Include examples
|
|
|
|
Include YAML files demonstrating how to use the package with `--examples-root`.
|
|
|
|
#### Include a runtime image
|
|
|
|
Functions and Providers require YAML files describing their dependencies and
|
|
settings as well as a container image for their runtime.
|
|
|
|
Using `--embed-runtime-image-name` runs a specified image and
|
|
includes the image inside the function or provider package.
|
|
|
|
{{<hint "note" >}}
|
|
Images referenced with `--embed-runtime-image-name` must be in the local Docker
|
|
cache.
|
|
|
|
Use `docker pull` to download a missing image.
|
|
{{< /hint >}}
|
|
|
|
The `--embed-runtime-image-tarball` flag includes a local OCI image tarball
|
|
inside the function or provider package.
|
|
|
|
### xpkg init
|
|
|
|
The `crossplane xpkg init` command populates the current directory with
|
|
files to build a package.
|
|
|
|
Provide a name to use for the package and the package template to start from
|
|
with the command
|
|
`crossplane xpkg init <name> <template>`
|
|
|
|
The `<name>` input isn't used. Crossplane reserves the `<name>` for future releases.
|
|
|
|
The `<template>` value may be one of four well known templates:
|
|
* `configuration-template` - A template to build a Crossplane [Configuration]({{<ref "../concepts/packages">}}) from the [crossplane/configuration-template](https://github.com/crossplane/configuration-template) repository.
|
|
* `function-template-go` - A template to build Crossplane Go [composition functions]({{<ref "../concepts/compositions">}}) from the [crossplane/function-template-go](https://github.com/crossplane/function-template-go) repository.
|
|
* `function-template-python` - A template to build Crossplane Python [composition functions]({{<ref "../concepts/compositions">}}) from the [crossplane/function-template-python](https://github.com/crossplane/function-template-go) repository.
|
|
* `provider-template` - A template to build a basic Crossplane provider from the [Crossplane/provider-template](https://github.com/crossplane/provider-template) repository.
|
|
* `provider-template-upjet` - A template for building [Upjet](https://github.com/crossplane/upjet) based Crossplane providers from existing Terraform providers. Copies from the [upbound/upjet-provider-template](https://github.com/upbound/upjet-provider-template) repository.
|
|
|
|
Instead of a well known template the `<template>` value can be a git repository
|
|
URL.
|
|
|
|
#### NOTES.txt
|
|
|
|
If the template repository contains a `NOTES.txt` file in its root directory,
|
|
the `crossplane xpkg init` command prints the contents of the file to the
|
|
terminal after populating the directory with the template files. This can be
|
|
useful for providing information about the template.
|
|
|
|
#### init.sh
|
|
|
|
If the template repository contains an `init.sh` file in its root directory, the
|
|
`crossplane xpkg init` command starts a dialog after populating the
|
|
directory with the template files. The dialog prompts the user if they want
|
|
to view or run the script. Use the initialization script to automatically
|
|
personalize the template.
|
|
|
|
#### Flags
|
|
{{< table "table table-sm table-striped">}}
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ----------------------- | ------------------------------ |
|
|
| `-b` | `--ref-name` | The branch or tag to clone from the template repository. |
|
|
| `-d` | `--directory` | The directory to create and load the template files into. Uses the current directory by default. |
|
|
| `-r` | `--run-init-script` | Run the init.sh script without prompting, if it exists. |
|
|
<!-- vale Crossplane.Spelling = YES -->
|
|
{{< /table >}}
|
|
|
|
|
|
### xpkg install
|
|
|
|
Download and install packages into Crossplane with `crossplane xpkg install`.
|
|
|
|
By default the `crossplane xpkg install` command uses the Kubernetes
|
|
configuration defined in `~/.kube/config`.
|
|
|
|
Define a custom Kubernetes configuration file location with the environmental
|
|
variable `KUBECONFIG`.
|
|
|
|
Specify the package kind, package file and optionally a name to give the package
|
|
inside Crossplane.
|
|
|
|
`crossplane xpkg install <package-kind> <registry URL package name and tag> [<optional-name>]`
|
|
|
|
The `<package-kind>` is either a `configuration`, `function` or `provider`.
|
|
|
|
For example, to install the latest version of the
|
|
[AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws):
|
|
|
|
`crossplane xpkg install provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`
|
|
|
|
#### Flags
|
|
{{< table "table table-sm table-striped">}}
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------- | ------------------------------ |
|
|
| | `--runtime-config=<runtime config name>` | Install the package with a runtime configuration. |
|
|
| `-m` | `--manual-activation` | Set the `revisionActiviationPolicy` to `Manual`. |
|
|
| | `--package-pull-secrets=<list of secrets>` | A comma-separated list of Kubernetes secrets to use for authenticating to the package registry. |
|
|
| `-r` | `--revision-history-limit=<number of revisions>` | Set the `revisionHistoryLimit`. Defaults to `1`. |
|
|
| `-w` | `--wait=<number of seconds>` | Number of seconds to wait for a package to install. |
|
|
|
|
{{< /table >}}
|
|
|
|
#### Wait for package install
|
|
|
|
When installing a package the `crossplane xpkg install` command doesn't wait for
|
|
the package to download and install. View any download or installation problems
|
|
by inspecting the `configuration` with `kubectl describe configuration`.
|
|
|
|
Use `--wait` to have the `crossplane xpkg install` command to wait for a
|
|
package to have the condition `HEALTHY` before continuing. The command
|
|
returns an error if the `wait` time expires before the package is `HEALTHY`.
|
|
|
|
#### Require manual package activation
|
|
|
|
Set the package to require
|
|
[manual activation]({{<ref "../concepts/packages#revision-activation-policy" >}}),
|
|
preventing an automatic upgrade of a package with `--manual-activation`
|
|
|
|
#### Authenticate to a private registry
|
|
|
|
To authenticate to a private package registry use `--package-pull-secrets` and
|
|
provide a list of Kubernetes Secret objects.
|
|
|
|
{{<hint "important" >}}
|
|
The secrets must be in the same namespace as the Crossplane pod.
|
|
{{< /hint >}}
|
|
|
|
#### Customize the number of stored package versions
|
|
|
|
By default Crossplane only stores a single inactive package in the local package
|
|
cache.
|
|
|
|
Store more inactive copies of a package with `--revision-history-limit`.
|
|
|
|
Read more about
|
|
[package revisions]({{< ref "../concepts/packages#configuration-revisions" >}})
|
|
in the package documentation.
|
|
|
|
### xpkg login
|
|
|
|
Use `xpkg login` to authenticate to registries that host Crossplane packages.
|
|
|
|
#### Flags
|
|
|
|
{{< table "table table-sm table-striped">}}
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------- | ------------------------------ |
|
|
| `-u` | `--username=<username>` | Username to use for authentication. |
|
|
| `-p` | `--password=<password>` | Password to use for authentication. |
|
|
| `-t` | `--token=<token string>` | User token string to use for authentication. |
|
|
| `-a` | `--account=<organization>` | Specify an Upbound organization during authentication. |
|
|
{{< /table >}}
|
|
|
|
|
|
#### Authentication options
|
|
|
|
The `crossplane xpkg login` command can use a username and password or Upbound API token.
|
|
|
|
By default, `crossplane xpkg login` without arguments, prompts for a username
|
|
and password.
|
|
|
|
Provide a username and password with the `--username` and `--password` flags or
|
|
set the environmental variable `UP_USER` for a username or `UP_PASSWORD` for the
|
|
password.
|
|
|
|
Use an Upbound user token instead of a username and password with `--token` or
|
|
the `UP_TOKEN` environmental variable.
|
|
|
|
{{< hint "important" >}}
|
|
The `--token` or `UP_TOKEN` environmental variables take precedence over a
|
|
username and password.
|
|
{{< /hint >}}
|
|
|
|
Using `-` as the input for `--password` or `--token` reads the input from stdin.
|
|
For example, `crossplane xpkg login --password -`.
|
|
|
|
After logging in the Crossplane CLI creates a `profile` in
|
|
`.crossplane/config.json` to cache unprivileged account information.
|
|
|
|
{{<hint "note" >}}
|
|
The `session` field of `config.json` file is a session cookie identifier.
|
|
|
|
The `session` value isn't used for authentication. This isn't a `token`.
|
|
{{< /hint >}}
|
|
|
|
#### Authenticate with a registered Upbound organization
|
|
|
|
Authenticate to a registered organization in the Upbound Marketplace with the
|
|
`--account` option, along with the username and password or token.
|
|
|
|
For example,
|
|
`crossplane xpkg login --account=Upbound --username=my-user --password -`.
|
|
|
|
### xpkg logout
|
|
|
|
Use `crossplane xpkg logout` to invalidate the current `crossplane xpkg login`
|
|
session.
|
|
|
|
{{< hint "note" >}}
|
|
Using `crossplane xpkg logout` removes the `session` from the
|
|
`~/.crossplane/config.json` file, but doesn't delete the configuration file.
|
|
{{< /hint >}}
|
|
|
|
### xpkg push
|
|
|
|
Push a Crossplane package file to a package registry.
|
|
|
|
{{< hint "note" >}}
|
|
Pushing a package may require authentication with
|
|
[`crossplane xpkg login`](#xpkg-login)
|
|
{{< /hint >}}
|
|
|
|
Specify the organization, package name and tag with
|
|
`crossplane xpkg push <package>`
|
|
|
|
By default the command looks in the current directory for a single `.xpkg` file
|
|
to push.
|
|
|
|
To push multiple files or to specify a specific `.xpkg` file use the `-f` flag.
|
|
|
|
For example, to push a local package named `my-package` to
|
|
`crossplane-docs/my-package:v0.14.0` use:
|
|
|
|
`crossplane xpkg push -f my-package.xpkg crossplane-docs/my-package:v0.14.0`
|
|
|
|
To push to another package registry, like [DockerHub](https://hub.docker.com/)
|
|
provide the full URL along with the package name.
|
|
|
|
For example, to push a local package named `my-package` to
|
|
DockerHub organization `crossplane-docs/my-package:v0.14.0` use:
|
|
`crossplane xpkg push -f my-package.xpkg index.docker.io/crossplane-docs/my-package:v0.14.0`.
|
|
|
|
|
|
#### Flags
|
|
|
|
{{< table "table table-sm table-striped">}}
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------- | ------------------------------ |
|
|
| `-f` | `--package-files=PATH` | A comma-separated list of xpkg files to push. |
|
|
{{< /table >}}
|
|
|
|
### xpkg update
|
|
|
|
The `crossplane xpkg update` command downloads and updates an existing package.
|
|
|
|
By default the `crossplane xpkg update` command uses the Kubernetes
|
|
configuration defined in `~/.kube/config`.
|
|
|
|
Define a custom Kubernetes configuration file location with the environmental
|
|
variable `KUBECONFIG`.
|
|
|
|
Specify the package kind, package file and optionally the name of the package
|
|
already installed in Crossplane.
|
|
|
|
`crossplane xpkg update <package-kind> <registry package name and tag> [<optional-name>]`
|
|
|
|
For example, to update to the latest version of the
|
|
[AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws):
|
|
|
|
`crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`
|
|
|
|
|
|
## beta
|
|
|
|
Crossplane `beta` commands are experimental. These commands may change the
|
|
flags, options or outputs in future releases.
|
|
|
|
Crossplane maintainers may promote or remove commands under `beta` in future
|
|
releases.
|
|
|
|
|
|
### beta convert
|
|
|
|
As Crossplane evolves, its APIs and resources may change. To help with the
|
|
migration to the new APIs and resources, the `crossplane beta convert` command
|
|
converts a Crossplane resource to a new version or kind.
|
|
|
|
Use the `crossplane beta convert` command to convert an existing
|
|
[ControllerConfig]({{<ref "../concepts/providers#controller-configuration">}})
|
|
to a [DeploymentRuntimeConfig]({{<ref "../concepts/providers#runtime-configuration">}})
|
|
or a legacy Composition using `mode: Resources` to a
|
|
[Composition pipeline function]({{< ref "../concepts/compositions" >}}).
|
|
|
|
Provide the `crossplane beta convert` command the conversion type, the input
|
|
file and optionally, an output file. By default the command writes the output to
|
|
standard out.
|
|
|
|
For example, to convert a ControllerConfig to a DeploymentRuntimeConfig use
|
|
`crossplane beta convert deployment-runtime`. For example,
|
|
|
|
`crossplane beta convert deployment-runtime controllerConfig.yaml -o deploymentConfig.yaml`
|
|
|
|
To convert a Composition using patch and transforms to a pipeline function, use
|
|
`crossplane beta convert pipeline-composition`.
|
|
|
|
Optionally, use the `-f` flag to provide the name of the function.
|
|
By default the function name is "function-patch-and-transform."
|
|
|
|
`crossplane beta convert pipeline-composition oldComposition.yaml -o newComposition.yaml -f patchFunctionName`
|
|
|
|
|
|
#### Flags
|
|
{{< table "table table-sm table-striped">}}
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | --------------- | ------------------------------ |
|
|
| `-o` | `--output-file` | The output YAML file to write. Outputs to stdout by default. |
|
|
| `-f` | `--function-name` | The name of the new function. Defaults to `function-patch-and-transform`. |
|
|
<!-- vale Crossplane.Spelling = YES -->
|
|
{{< /table >}}
|
|
|
|
|
|
### beta top
|
|
|
|
The command `crossplane beta top` shows CPU and memory usage of Crossplane
|
|
related pods.
|
|
|
|
```shell
|
|
crossplane beta top
|
|
TYPE NAMESPACE NAME CPU(cores) MEMORY
|
|
crossplane default crossplane-f98f9ddfd-tnm46 4m 32Mi
|
|
crossplane default crossplane-rbac-manager-74ff459b88-94p8p 4m 14Mi
|
|
provider default provider-aws-s3-1f1a3fb08cbc-5c49d84447-sggrq 3m 108Mi
|
|
provider default crossplane-contrib-provider-family-aws-48b3b5ccf964-76c9686b6-bgg65 2m 89Mi
|
|
```
|
|
|
|
{{<hint "important" >}}
|
|
Using `crossplane beta top` requires the Kubernetes
|
|
[metrics server](https://github.com/kubernetes-sigs/metrics-server) enabled on
|
|
the cluster running Crossplane before using `crossplane beta top`.
|
|
|
|
Follow the installation instructions on the
|
|
[metrics-server GitHub page](https://github.com/kubernetes-sigs/metrics-server#installation).
|
|
{{< /hint >}}
|
|
|
|
|
|
|
|
#### Flags
|
|
{{< table "table table-sm table-striped">}}
|
|
<!-- vale Crossplane.Spelling = NO -->
|
|
<!-- vale flags `dot` as an error but only the trailing tick. -->
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------- | ------------------------------ |
|
|
| `-n` | `--namespace` | The namespace where the Crossplane pod runs. Default is `crossplane-system`. |
|
|
| `-s` | `--summary` | Print a summary of all Crossplane pods along with the output. |
|
|
| | `--verbose` | Print verbose logging information with the output. |
|
|
<!-- vale Crossplane.Spelling = YES -->
|
|
{{< /table >}}
|
|
|
|
The Kubernetes metrics server may take some time to collect data for the
|
|
`crossplane beta top` command. Before the metrics server is ready,
|
|
running the `top` command may produce an error, for example,
|
|
|
|
`crossplane: error: error adding metrics to pod, check if metrics-server is running or wait until metrics are available for the pod: the server is currently unable to handle the request (get pods.metrics.k8s.io crossplane-contrib-provider-helm-b4cc4c2c8db3-6d787f9686-qzmz2)`
|
|
|
|
|
|
### beta trace
|
|
|
|
Use the `crossplane beta trace` command to display a visual relationship of
|
|
Crossplane objects. The `trace` command supports claims, compositions,
|
|
functions, managed resources or packages.
|
|
|
|
The command requires a resource type and a resource name.
|
|
|
|
`crossplane beta trace <resource kind> <resource name>`
|
|
|
|
For example to view a resource named `my-claim` of type `example.crossplane.io`:
|
|
`crossplane beta trace example.crossplane.io my-claim`
|
|
|
|
The command also accepts Kubernetes CLI style `<kind>/<name>` input.
|
|
For example,
|
|
`crossplane beta trace example.crossplane.io/my-claim`
|
|
|
|
By default the `crossplane beta trace` command uses the Kubernetes
|
|
configuration defined in `~/.kube/config`.
|
|
|
|
Define a custom Kubernetes configuration file location with the environmental
|
|
variable `KUBECONFIG`.
|
|
|
|
#### Flags
|
|
{{< table "table table-sm table-striped">}}
|
|
<!-- vale Crossplane.Spelling = NO -->
|
|
<!-- vale flags `dot` as an error but only the trailing tick. -->
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------- | ------------------------------ |
|
|
| `-n` | `--namespace` | The namespace of the resource. |
|
|
| `-o` | `--output=` | Change the graph output with `wide`, `json`, or `dot` for a [Graphviz dot](https://graphviz.org/docs/layouts/dot/) output. |
|
|
| | `--show-connection-secrets` | Print any connection secret names. Doesn't print the secret values. |
|
|
| | `--show-package-dependencies <filter>` | Show package dependencies. Options are `all` to show every dependency, `unique` to only print a package once or `none` to not print any dependencies. By default the `trace` command uses `--show-package-dependencies unique`. |
|
|
| | `--show-package-revisions <output>` | Print package revision versions. Options are `active`, showing only the active revisions, `all` showing all revisions or `none` to print not print any revisions. |
|
|
| | `--show-package-runtime-configs` | Print DeploymentRuntimeConfig dependencies. |
|
|
<!-- vale Crossplane.Spelling = YES -->
|
|
{{< /table >}}
|
|
|
|
#### Output options
|
|
|
|
By default `crossplane beta trace` prints directly to the terminal, limiting the
|
|
"Ready" condition and "Status" messages to 64 characters.
|
|
|
|
The following an example output a "cluster" claim from the AWS reference
|
|
platform, which includes multiple Compositions and composed resources:
|
|
|
|
```shell {copy-lines="1"}
|
|
crossplane beta trace cluster.aws.platformref.upbound.io platform-ref-aws
|
|
NAME VERSION INSTALLED HEALTHY STATE STATUS
|
|
Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
|
|
├─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-database v0.5.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-database-3112f0a765c5 v0.5.0 - True Active HealthyPackageRevision
|
|
│ └─ Provider/upbound-provider-aws-rds v0.47.0 True True - HealthyPackageRevision
|
|
│ └─ ProviderRevision/upbound-provider-aws-rds-58f96aa9fc4b v0.47.0 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-eks v0.5.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-eks-83c9d65f4a47 v0.5.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/crossplane-contrib-provider-kubernetes v0.10.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/crossplane-contrib-provider-kubernetes-63506a3443e0 v0.10.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-eks v0.47.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-aws-eks-641a096d79d8 v0.47.0 - True Active HealthyPackageRevision
|
|
│ └─ Provider/upbound-provider-aws-iam v0.47.0 True True - HealthyPackageRevision
|
|
│ └─ ProviderRevision/upbound-provider-aws-iam-438eac423037 v0.47.0 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-app v0.2.0 True True - HealthyPackageRevision
|
|
│ └─ ConfigurationRevision/upbound-configuration-app-5d95726dba8c v0.2.0 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-observability-oss v0.2.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-observability-oss-a51529457ad7 v0.2.0 - True Active HealthyPackageRevision
|
|
│ └─ Provider/grafana-provider-grafana v0.8.0 True True - HealthyPackageRevision
|
|
│ └─ ProviderRevision/grafana-provider-grafana-ac529c8ce1c6 v0.8.0 - True Active HealthyPackageRevision
|
|
└─ Configuration/upbound-configuration-gitops-flux v0.2.0 True True - HealthyPackageRevision
|
|
└─ ConfigurationRevision/upbound-configuration-gitops-flux-2e80ec62738d v0.2.0 - True Active HealthyPackageRevision
|
|
```
|
|
|
|
#### Wide outputs
|
|
Print the entire "Ready" or "Status" message if they're longer than
|
|
64 characters with `--output=wide`.
|
|
|
|
For example, the output truncates the "Status" message that's too long.
|
|
|
|
```shell {copy-lines="1"
|
|
crossplane trace cluster.aws.platformref.upbound.io platform-ref-aws
|
|
NAME SYNCED READY STATUS
|
|
Cluster/platform-ref-aws (default) True False Waiting: ...resource claim is waiting for composite resource to become Ready
|
|
```
|
|
|
|
Use `--output=wide` to see the full message.
|
|
|
|
```shell {copy-lines="1"
|
|
crossplane trace cluster.aws.platformref.upbound.io platform-ref-aws --output=wide
|
|
NAME SYNCED READY STATUS
|
|
Cluster/platform-ref-aws (default) True False Waiting: Composite resource claim is waiting for composite resource to become Ready
|
|
```
|
|
|
|
#### Graphviz dot file output
|
|
|
|
Use the `--output=dot` to print out a textual
|
|
[Graphviz dot](https://graphviz.org/docs/layouts/dot/) output.
|
|
|
|
Save the output and export it or the output directly to Graphviz `dot` to
|
|
render an image.
|
|
|
|
For example, to save the output as a `graph.png` file use
|
|
`dot -Tpng -o graph.png`.
|
|
|
|
`crossplane beta trace cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png`
|
|
|
|
#### Print connection secrets
|
|
|
|
Use `-s` to print any connection secret names along with the other resources.
|
|
|
|
{{<hint "important">}}
|
|
The `crossplane beta trace` command doesn't print secret values.
|
|
{{< /hint >}}
|
|
|
|
The output includes both the secret name along with the secret's namespace.
|
|
|
|
```shell
|
|
crossplane beta trace configuration platform-ref-aws -s
|
|
NAME SYNCED READY STATUS
|
|
Cluster/platform-ref-aws (default) True True Available
|
|
└─ XCluster/platform-ref-aws-mlnwb True True Available
|
|
├─ XNetwork/platform-ref-aws-mlnwb-6nvkx True True Available
|
|
│ ├─ SecurityGroupRule/platform-ref-aws-mlnwb-szgxp True True Available
|
|
│ └─ Secret/3f11c30b-dd94-4f5b-aff7-10fe4318ab1f (upbound-system) - -
|
|
├─ XEKS/platform-ref-aws-mlnwb-fqjzz True True Available
|
|
│ ├─ OpenIDConnectProvider/platform-ref-aws-mlnwb-h26xx True True Available
|
|
│ └─ Secret/9666eccd-929c-4452-8658-c8c881aee137-eks (upbound-system) - -
|
|
├─ XServices/platform-ref-aws-mlnwb-bgndx True True Available
|
|
│ ├─ Release/platform-ref-aws-mlnwb-7hfkv True True Available
|
|
│ └─ Secret/d0955929-892d-40c3-b0e0-a8cabda55895 (upbound-system) - -
|
|
└─ Secret/9666eccd-929c-4452-8658-c8c881aee137 (upbound-system) - -
|
|
```
|
|
|
|
#### Print package dependencies
|
|
|
|
Use the `--show-package-dependencies` flag to include more information about
|
|
package dependencies.
|
|
|
|
By default `crossplane beta trace` uses `--show-package-dependencies unique` to
|
|
include a required package only once in the output.
|
|
|
|
Use `--show-package-dependencies all` to see every package requiring the same
|
|
dependency.
|
|
|
|
```shell
|
|
crossplane beta trace configuration platform-ref-aws --show-package-dependencies all
|
|
NAME VERSION INSTALLED HEALTHY STATE STATUS
|
|
Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
|
|
├─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-database v0.5.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-database-3112f0a765c5 v0.5.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-rds v0.47.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ProviderRevision/upbound-provider-aws-rds-58f96aa9fc4b v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ └─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-eks v0.5.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-eks-83c9d65f4a47 v0.5.0 - True Active HealthyPackageRevision
|
|
│ ├─ Configuration/upbound-configuration-aws-network v0.7.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ConfigurationRevision/upbound-configuration-aws-network-97be9100cfe1 v0.7.0 - True Active HealthyPackageRevision
|
|
│ │ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
|
|
│ │ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
│ │ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/crossplane-contrib-provider-kubernetes v0.10.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/crossplane-contrib-provider-kubernetes-63506a3443e0 v0.10.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-ec2 v0.47.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ProviderRevision/upbound-provider-aws-ec2-cfeb0cd0f1d2 v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-eks v0.47.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ProviderRevision/upbound-provider-aws-eks-641a096d79d8 v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/upbound-provider-aws-iam v0.47.0 True True - HealthyPackageRevision
|
|
│ │ ├─ ProviderRevision/upbound-provider-aws-iam-438eac423037 v0.47.0 - True Active HealthyPackageRevision
|
|
│ │ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-app v0.2.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-app-5d95726dba8c v0.2.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
|
|
│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-observability-oss v0.2.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-observability-oss-a51529457ad7 v0.2.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/crossplane-contrib-provider-kubernetes v0.10.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/crossplane-contrib-provider-kubernetes-63506a3443e0 v0.10.0 - True Active HealthyPackageRevision
|
|
│ ├─ Provider/grafana-provider-grafana v0.8.0 True True - HealthyPackageRevision
|
|
│ │ └─ ProviderRevision/grafana-provider-grafana-ac529c8ce1c6 v0.8.0 - True Active HealthyPackageRevision
|
|
│ └─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
│ └─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
└─ Configuration/upbound-configuration-gitops-flux v0.2.0 True True - HealthyPackageRevision
|
|
├─ ConfigurationRevision/upbound-configuration-gitops-flux-2e80ec62738d v0.2.0 - True Active HealthyPackageRevision
|
|
├─ Provider/crossplane-contrib-provider-helm v0.16.0 True True - HealthyPackageRevision
|
|
│ └─ ProviderRevision/crossplane-contrib-provider-helm-b4cc4c2c8db3 v0.16.0 - True Active HealthyPackageRevision
|
|
└─ Function/upbound-function-patch-and-transform v0.2.1 True True - HealthyPackageRevision
|
|
└─ FunctionRevision/upbound-function-patch-and-transform-a2f88f8d8715 v0.2.1 - True Active HealthyPackageRevision
|
|
```
|
|
|
|
Use `--show-package-dependencies none` to hide all dependencies.
|
|
|
|
```shell
|
|
crossplane beta trace configuration platform-ref-aws --show-package-dependencies none
|
|
NAME VERSION INSTALLED HEALTHY STATE STATUS
|
|
Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
|
|
└─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
|
|
```
|
|
|
|
#### Print package revisions
|
|
|
|
By default the `crossplane beta trace` command only shows the package revisions
|
|
actively in use. To view both active and inactive revisions use
|
|
`--show-package-revisions all`.
|
|
|
|
```shell
|
|
crossplane beta trace configuration platform-ref-aws --show-package-revisions all
|
|
NAME VERSION INSTALLED HEALTHY STATE STATUS
|
|
Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
|
|
├─ ConfigurationRevision/platform-ref-aws-ad01153c1179 v0.8.0 - True Inactive HealthyPackageRevision
|
|
├─ ConfigurationRevision/platform-ref-aws-9ad7b5db2899 v0.9.0 - True Active HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-network v0.2.0 True True - HealthyPackageRevision
|
|
│ ├─ ConfigurationRevision/upbound-configuration-aws-network-288fcd1b88dd v0.2.0 - True Active HealthyPackageRevision
|
|
│ └─ Provider/upbound-provider-aws-ec2 v1.0.0 True True - HealthyPackageRevision
|
|
│ ├─ ProviderRevision/upbound-provider-aws-ec2-5cfd948d082f v1.0.0 - True Active HealthyPackageRevision
|
|
│ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
│ └─ ProviderRevision/upbound-provider-family-aws-48b3b5ccf964 v1.0.0 - True Active HealthyPackageRevision
|
|
# Removed for brevity
|
|
```
|
|
|
|
To hide all revisions use `--show-package-revision none`.
|
|
|
|
```shell
|
|
crossplane beta trace configuration platform-ref-aws --show-package-revisions none
|
|
NAME VERSION INSTALLED HEALTHY STATE STATUS
|
|
Configuration/platform-ref-aws v0.9.0 True True - HealthyPackageRevision
|
|
├─ Configuration/upbound-configuration-aws-network v0.2.0 True True - HealthyPackageRevision
|
|
│ └─ Provider/upbound-provider-aws-ec2 v1.0.0 True True - HealthyPackageRevision
|
|
│ └─ Provider/upbound-provider-family-aws v1.0.0 True True - HealthyPackageRevision
|
|
# Removed for brevity
|
|
```
|
|
|
|
### beta validate
|
|
|
|
The `crossplane beta validate` command validates
|
|
[compositions]({{<ref "../concepts/compositions">}}) against provider or XRD
|
|
schemas using the Kubernetes API server's validation library
|
|
with extra validation such as checking for unknown fields,
|
|
a common source of difficult to debug issues in Crossplane.
|
|
|
|
The `crossplane beta validate` command supports validating the following
|
|
scenarios:
|
|
|
|
- Validate a managed resource or composite resource
|
|
[against a Provider or XRD schema](#validate-resources-against-a-schema).
|
|
- Use the output of `crossplane render` as [validation input](#validate-render-command-output).
|
|
- Validate an [XRD against Kubernetes Common Expression Language](#validate-common-expression-language-rules)
|
|
(CEL) rules.
|
|
- Validate resources against a [directory of schemas](#validate-against-a-directory-of-schemas).
|
|
|
|
|
|
{{< hint "note" >}}
|
|
The `crossplane beta validate` command performs all validation offline.
|
|
|
|
A Kubernetes cluster running Crossplane isn't required.
|
|
{{< /hint >}}
|
|
|
|
#### Flags
|
|
|
|
{{< table "table table-sm table-striped" >}}
|
|
| Short flag | Long flag | Description |
|
|
| ------------ | ------------------------ | ----------------------------------------------------- |
|
|
| `-h` | `--help` | Show context sensitive help. |
|
|
| `-v` | `--version` | Print version and quit. |
|
|
| | `--cache-dir=".crossplane/cache"` | Specify the absolute path to the cache directory to store downloaded schemas. |
|
|
| | `--clean-cache` | Clean the cache directory before downloading package schemas. |
|
|
| | `--skip-success-results` | Skip printing success results. |
|
|
| | `--verbose` | Print verbose logging statements. |
|
|
{{< /table >}}
|
|
|
|
#### Validate resources against a schema
|
|
|
|
The `crossplane beta validate` command can validate an XR and one or more
|
|
managed resources against a provider's schema.
|
|
|
|
{{<hint "important" >}}
|
|
When validating against a provider the `crossplane beta validate` command
|
|
downloads the provider package to the `--cache-dir` directory. By default
|
|
Crossplane uses `.crossplane` as the `--cache-dir` location.
|
|
|
|
Access to a Kubernetes cluster or Crossplane pod isn't required.
|
|
Validation requires the ability to download the provider package.
|
|
{{< /hint >}}
|
|
|
|
The `crossplane beta validate` command downloads and caches the schema CRD files
|
|
in the `--cache-dir` directory. By default the Crossplane CLI uses
|
|
`.crossplane/cache` as the cache location.
|
|
|
|
To clear the cache and download the CRD files again use the `--clean-cache` flag.
|
|
|
|
To validate a managed resource against a provider,
|
|
first, create a provider manifest file. For example, to validate an IAM role
|
|
from Provider AWS, use the
|
|
[Provider AWS IAM](https://github.com/crossplane-contrib/provider-upjet-aws)
|
|
manifest.
|
|
|
|
{{<hint "tip" >}}
|
|
To validate a
|
|
"[family provider](https://blog.upbound.io/new-provider-families)" use the
|
|
provider manifests of the resources to validate.
|
|
{{< /hint >}}
|
|
|
|
```yaml
|
|
apiVersion: pkg.crossplane.io/v1
|
|
kind: Provider
|
|
metadata:
|
|
name: provider-aws-iam
|
|
spec:
|
|
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-iam:v1.21.1
|
|
```
|
|
|
|
Now include the XR or managed resource to validate.
|
|
|
|
For example, to validate an
|
|
{{<hover label="iamAK" line="2">}}AccessKey{{</hover>}} managed resource,
|
|
provide a managed resource YAML file.
|
|
|
|
```yaml {label="iamAK"}
|
|
apiVersion: iam.aws.upbound.io/v1beta1
|
|
kind: AccessKey
|
|
metadata:
|
|
name: sample-access-key-0
|
|
spec:
|
|
forProvider:
|
|
userSelector:
|
|
matchLabels:
|
|
example-name: test-user-0
|
|
```
|
|
|
|
Run the `crossplane beta validate` command providing the provider and managed
|
|
resource YAML files as input.
|
|
|
|
```shell
|
|
crossplane beta validate provider.yaml managedResource.yaml
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
|
|
Total 1 resources: 0 missing schemas, 1 success case, 0 failure cases
|
|
```
|
|
|
|
#### Validate render command output
|
|
|
|
You can pipe the output of `crossplane render` into
|
|
`crossplane beta validate` to validate complete Crossplane resource pipelines,
|
|
including XRs, compositions and composition functions.
|
|
|
|
Use the `--include-full-xr` command with `crossplane render` and the `-`
|
|
option with `crossplane beta validate` to pipe the output from
|
|
`crossplane render` to the input of `crossplane beta validate`.
|
|
|
|
```shell {copy-lines="1"}
|
|
crossplane render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml -
|
|
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
|
|
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Required value
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-1 validated successfully
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-0 validated successfully
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
|
|
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
|
|
```
|
|
|
|
#### Validate Common Expression Language rules
|
|
|
|
XRDs can define [validation rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) expressed in the Common Expression Language
|
|
([CEL](https://kubernetes.io/docs/reference/using-api/cel/)).
|
|
|
|
|
|
Apply a CEL rule with the
|
|
{{<hover label="celXRD" line="12" >}}x-kubernetes-validations{{</hover>}} key
|
|
inside the schema {{<hover label="celXRD" line="10" >}}spec{{</hover>}} object of an XRD.
|
|
|
|
```yaml {label="celXRD"}
|
|
apiVersion: apiextensions.crossplane.io/v1
|
|
kind: CompositeResourceDefinition
|
|
metadata:
|
|
name: myXR.crossplane.io
|
|
spec:
|
|
# Removed for brevity
|
|
openAPIV3Schema:
|
|
type: object
|
|
properties:
|
|
spec:
|
|
type: object
|
|
x-kubernetes-validations:
|
|
- rule: "self.minReplicas <= self.replicas && self.replicas <= self.maxReplicas"
|
|
message: "replicas should be in between minReplicas and maxReplicas."
|
|
properties:
|
|
minReplicas:
|
|
type: integer
|
|
maxReplicas:
|
|
type: integer
|
|
replicas:
|
|
type: integer
|
|
# Removed for brevity
|
|
```
|
|
|
|
The rule in this example checks that the vale of the
|
|
{{<hover label="celXR" line="6">}}replicas{{</hover>}} field of an XR is between
|
|
the {{<hover label="celXR" line="7">}}minReplicas{{</hover>}} and
|
|
{{<hover label="celXR" line="8">}}maxReplicas{{</hover>}} values.
|
|
|
|
```yaml {label="celXR"}
|
|
apiVersion: example.crossplane.io/v1beta1
|
|
kind: XR
|
|
metadata:
|
|
name: example
|
|
spec:
|
|
replicas: 49
|
|
minReplicas: 1
|
|
maxReplicas: 30
|
|
```
|
|
|
|
Running `crossplane beta validate` with the example XRD and XR produces an
|
|
error.
|
|
|
|
```shell
|
|
`crossplane beta validate xrd.yaml xr.yaml
|
|
[x] CEL validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Invalid value: "object": replicas should be in between minReplicas and maxReplicas.
|
|
Total 1 resources: 0 missing schemas, 0 success cases, 1 failure cases
|
|
```
|
|
|
|
#### Validate against a directory of schemas
|
|
|
|
The `crossplane render` command can validate a directory of YAML files.
|
|
|
|
The command only processes `.yaml` and `.yml` files, while ignoring all other
|
|
file types.
|
|
|
|
With a directory of files, provide the directory and resource to validate.
|
|
|
|
For example, using a directory named
|
|
{{<hover label="validateDir" line="2">}}schemas{{</hover>}} containing the XRD
|
|
and Provider schemas.
|
|
|
|
```shell {label="validateDir"}
|
|
tree
|
|
schemas
|
|
|-- platform-ref-aws.yaml
|
|
|-- providers
|
|
| |-- a.txt
|
|
| `-- provider-aws-iam.yaml
|
|
`-- xrds
|
|
`-- xrd.yaml
|
|
```
|
|
|
|
Provide the directory name and a resource YAML file to the
|
|
`crossplane beta validate` command.
|
|
|
|
```shell
|
|
crossplane beta validate schema resources.yaml
|
|
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
|
|
[x] CEL validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Invalid value: "object": no such key: minReplicas evaluating rule: replicas should be greater than or equal to minReplicas.
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-1 validated successfully
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-0 validated successfully
|
|
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
|
|
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
|
|
```
|
|
|
|
|