diff --git a/content/master/cli/command-reference.md b/content/master/cli/command-reference.md index 7979651f..f2c18462 100644 --- a/content/master/cli/command-reference.md +++ b/content/master/cli/command-reference.md @@ -18,10 +18,14 @@ The following flags are available for all commands. | Short flag | Long flag | Description | |------------|-------------|------------------------------| | `-h` | `--help` | Show context sensitive help. | -| `-v` | `--version` | Print version and exit. | | | `--verbose` | Print verbose output. | {{< /table >}} +## version + +The `crossplane version` command returns the version of the Crossplane CLI you +are running. + ## xpkg The `crossplane xpkg` commands create, install and update Crossplane diff --git a/content/v1.16/cli/command-reference.md b/content/v1.16/cli/command-reference.md index 7979651f..19dc3ffc 100644 --- a/content/v1.16/cli/command-reference.md +++ b/content/v1.16/cli/command-reference.md @@ -6,9 +6,9 @@ description: "Command reference for the Crossplane CLI" -The `crossplane` CLI provides utilities to make using Crossplane easier. +The `crossplane` CLI provides utilities to make using Crossplane easier. -Read the [Crossplane CLI overview]({{}}) page for information on +Read the [Crossplane CLI overview]({{}}) page for information on installing `crossplane`. ## Global flags @@ -16,33 +16,37 @@ 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. | -| `-v` | `--version` | Print version and exit. | -| | `--verbose` | Print verbose output. | +| | `--verbose` | Print verbose output. | {{< /table >}} +## version + +The `crossplane version` command returns the version of the Crossplane CLI you +are running. + ## xpkg The `crossplane xpkg` commands create, install and update Crossplane [packages]({{}}) as well as enable authentication -and publishing of Crossplane packages to a Crossplane package registry. +and publishing of Crossplane packages to a Crossplane package registry. ### xpkg build -Using `crossplane xpkg build` provides automation and simplification to build -Crossplane packages. +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 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 +The CLI applies the required annotations and values to meet the [Crossplane XPKG specification](https://github.com/crossplane/crossplane/blob/master/contributing/specifications/xpkg.md). -The `crossplane` CLI supports building +The `crossplane` CLI supports building [configuration]({{< ref "../concepts/packages" >}}), -[function]({{}}) and -[provider]({{}}) package types. +[function]({{}}) and +[provider]({{}}) package types. #### Flags @@ -57,54 +61,54 @@ The `crossplane` CLI supports building | `-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` +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. +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. +Use `--ignore` to provide a list of files and directories to ignore. -For example, +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`. +`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, +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 YAML files demonstrating how to use the package with `--examples-root`. -[Upbound Marketplace](https://marketplace.upbound.io/) uses files included with +[Upbound Marketplace](https://marketplace.upbound.io/) uses files included with `--examples-root` as documentation for published packages. #### Include a runtime image -Functions and Providers require YAML files describing their dependencies and +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 +Using `--embed-runtime-image-name` runs a specified image and includes the image inside the function or provider package. {{}} -Images referenced with `--embed-runtime-image-name` must be in the local Docker -cache. +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 +The `--embed-runtime-image-tarball` flag includes a local OCI image tarball inside the function or provider package. @@ -112,20 +116,20 @@ inside the function or provider package. 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`. +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 +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 +Specify the package kind, package file and optionally a name to give the package inside Crossplane. `crossplane xpkg install []` The `` is either a `configuration`, `function` or `provider`. -For example, to install version 0.42.0 of the +For example, to install version 0.42.0 of the [AWS S3 provider](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/v0.42.0): `crossplane xpkg install provider xpkg.upbound.io/upbound/provider-aws-s3:v0.42.0` @@ -145,55 +149,55 @@ For example, to install version 0.42.0 of the #### 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 +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 +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]({{}}), +Set the package to require +[manual activation]({{}}), 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. +To authenticate to a private package registry use `--package-pull-secrets` and +provide a list of Kubernetes Secret objects. {{}} -The secrets must be in the same namespace as the Crossplane pod. +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. +cache. -Store more inactive copies of a package with `--revision-history-limit`. +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. +Read more about +[package revisions]({{< ref "../concepts/packages#configuration-revisions" >}}) +in the package documentation. ### xpkg login -Use `xpkg login` to authenticate to `xpkg.upbound.io`, the +Use `xpkg login` to authenticate to `xpkg.upbound.io`, the [Upbound Marketplace](https://marketplace.upbound.io/) container registry. -[Register with the Upbound Marketplace](https://accounts.upbound.io/register) -to push packages and create private repositories. +[Register with the Upbound Marketplace](https://accounts.upbound.io/register) +to push packages and create private repositories. #### Flags {{< table "table table-sm table-striped">}} | Short flag | Long flag | Description | | ------------ | ------------- | ------------------------------ | -| `-u` | `--username=` | Username to use for authentication. | -| `-p` | `--password=` | Password to use for authentication. | -| `-t` | `--token=` | User token string to use for authentication. | +| `-u` | `--username=` | Username to use for authentication. | +| `-p` | `--password=` | Password to use for authentication. | +| `-t` | `--token=` | User token string to use for authentication. | | `-a` | `--account=` | Specify an Upbound organization during authentication. | {{< /table >}} @@ -203,80 +207,80 @@ to push packages and create private repositories. 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. +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. +password. -Use an Upbound user token instead of a username and password with `--token` or -the `UP_TOKEN` environmental variable. +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 +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. +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. +After logging in the Crossplane CLI creates a `profile` in +`.crossplane/config.json` to cache unprivileged account information. {{}} -The `session` field of `config.json` file is a session cookie identifier. +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. +Authenticate to a registered organization in the Upbound Marketplace with the +`--account` option, along with the username and password or token. -For example, +For example, `crossplane xpkg login --account=Upbound --username=my-user --password -`. ### xpkg logout -Use `crossplane xpkg logout` to invalidate the current `crossplane xpkg login` +Use `crossplane xpkg logout` to invalidate the current `crossplane xpkg login` session. {{< hint "note" >}} -Using `crossplane xpkg logout` removes the `session` from the +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. +Push a Crossplane package file to a package registry. -The Crossplane CLI pushes images to the -[Upbound Marketplace](https://marketplace.upbound.io/) at `xpkg.upbound.io` by +The Crossplane CLI pushes images to the +[Upbound Marketplace](https://marketplace.upbound.io/) at `xpkg.upbound.io` by default. {{< hint "note" >}} -Pushing a package may require authentication with +Pushing a package may require authentication with [`crossplane xpkg login`](#xpkg-login) {{< /hint >}} -Specify the organization, package name and tag with +Specify the organization, package name and tag with `crossplane xpkg push ` -By default the command looks in the current directory for a single `.xpkg` file -to push. +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 +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. +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 +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`. @@ -293,13 +297,13 @@ DockerHub organization `crossplane-docs/my-package:v0.14.0` use: 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`. +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 +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 +Specify the package kind, package file and optionally the name of the package already installed in Crossplane. `crossplane xpkg update []` @@ -307,7 +311,7 @@ already installed in Crossplane. The package file must be an organization, image and tag on the `xpkg.upbound.io` registry on [Upbound Marketplace](https://marketplace.upbound.io/). -For example, to update to version 0.42.0 of the +For example, to update to version 0.42.0 of the [AWS S3 provider](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/v0.42.0): `crossplane xpkg update provider xpkg.upbound.io/upbound/provider-aws-s3:v0.42.0` @@ -315,39 +319,39 @@ For example, to update to version 0.42.0 of the ## beta -Crossplane `beta` commands are experimental. These commands may change the -flags, options or outputs in future releases. +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 +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 +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]({{}}) -to a [DeploymentRuntimeConfig]({{}}) -or a Composition using [patch and transforms]({{}}) -to a +to a [DeploymentRuntimeConfig]({{}}) +or a Composition using [patch and transforms]({{}}) +to a [Composition pipeline function]({{< ref "../concepts/compositions#use-composition-functions" >}}). 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. +standard out. -For example, to convert a ControllerConfig to a DeploymentRuntimeConfig use +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`. +`crossplane beta convert pipeline-composition`. -Optionally, use the `-f` flag to provide the name of the function. +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` @@ -363,34 +367,34 @@ By default the function name is "function-patch-and-transform." {{< /table >}} -### beta render +### beta render -The `crossplane beta render` command previews the output of a -[composite resource]({{}}) after applying +The `crossplane beta render` command previews the output of a +[composite resource]({{}}) after applying any [composition functions]({{}}). {{< hint "important" >}} -The `crossplane beta render` command doesn't apply +The `crossplane beta render` command doesn't apply [patch and transform composition patches]({{}}). The command only supports function "patch and transforms." {{< /hint >}} -The `crossplane beta render` command connects to the locally running Docker -Engine to pull and run composition functions. +The `crossplane beta render` command connects to the locally running Docker +Engine to pull and run composition functions. -{{}} +{{}} Running `crossplane beta 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. +Provide a composite resource, composition and composition function YAML +definition with the command to render the output locally. -For example, +For example, `crossplane beta render xr.yaml composition.yaml function.yaml` -The output includes the original composite resource followed by the generated -managed resources. +The output includes the original composite resource followed by the generated +managed resources. {{}} ```yaml @@ -438,45 +442,45 @@ Provide artificial managed resource data to the function. | | `--timeout=` | Amount of time to wait for a function to finish. | {{< /table >}} -The `crossplane beta 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. +The `crossplane beta 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-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. +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 +#### Include the composite resource -Composition functions can only change the `status` field of a composite +Composition functions can only change the `status` field of a composite resource. By default, the `crossplane beta render` command only prints the -`status` field with `metadata.name`. +`status` field with `metadata.name`. -Use `--include-full-xr` to print the full composite resource, +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 beta render` command treats the -provided inputs as if they were resources in a Crossplane cluster. +Provide mocked, or artificial data representing a managed resource with +`--observed-resources`. The `crossplane beta 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 +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 +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 +Inside the YAML file include an {{}}apiVersion{{}}, {{}}kind{{}}, {{}}metadata{{}} and @@ -498,10 +502,10 @@ The schema of the resource isn't validated and may contain any data. ### beta top The command `crossplane beta top` shows CPU and memory usage of Crossplane -related pods. +related pods. ```shell -crossplane beta top +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 @@ -510,11 +514,11 @@ provider default upbound-provider-family-aws-48b3b5ccf964-76c9686b6-bgg6 ``` {{}} -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`. +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 +Follow the installation instructions on the [metrics-server GitHub page](https://github.com/kubernetes-sigs/metrics-server#installation). {{< /hint >}} @@ -533,7 +537,7 @@ Follow the installation instructions on the {{< /table >}} The Kubernetes metrics server may take some time to collect data for the -`crossplane beta top` command. Before the metrics server is ready, +`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)` @@ -542,24 +546,24 @@ running the `top` command may produce an error, for example, ### 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. +Crossplane objects. The `trace` command supports claims, compositions, +functions, managed resources or packages. -The command requires a resource type and a resource name. +The command requires a resource type and a resource name. `crossplane beta trace ` -For example to view a resource named `my-claim` of type `example.crossplane.io`: +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 `/` input. -For example, +The command also accepts Kubernetes CLI style `/` 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`. +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 +Define a custom Kubernetes configuration file location with the environmental variable `KUBECONFIG`. #### Flags @@ -582,8 +586,8 @@ variable `KUBECONFIG`. 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: +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 @@ -623,10 +627,10 @@ Configuration/platform-ref-aws ``` #### Wide outputs -Print the entire "Ready" or "Status" message if they're longer than -64 characters with `--output=wide`. +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. +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 @@ -644,13 +648,13 @@ Cluster/platform-ref-aws (default) True False #### Graphviz dot file output -Use the `--output=dot` to print out a textual -[Graphviz dot](https://graphviz.org/docs/layouts/dot/) 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. +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 +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` @@ -691,7 +695,7 @@ 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. +dependency. ```shell crossplane beta trace configuration platform-ref-aws --show-package-dependencies all @@ -816,25 +820,25 @@ Configuration/platform-ref-aws v0.9.0 True ### beta validate -The `crossplane beta validate` command validates -[compositions]({{}}) against provider or XRD +The `crossplane beta validate` command validates +[compositions]({{}}) against provider or XRD schemas using the Kubernetes API server's validation library. -The `crossplane beta validate` command supports validating the following +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 beta render` as [validation input](#validate-render-command-output). -- Validate an [XRD against Kubernetes Common Expression Language](#validate-common-expression-language-rules) +- Validate a managed resource or composite resource + [against a Provider or XRD schema](#validate-resources-against-a-schema). +- Use the output of `crossplane beta 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. +The `crossplane beta validate` command performs all validation offline. -A Kubernetes cluster running Crossplane isn't required. +A Kubernetes cluster running Crossplane isn't required. {{< /hint >}} #### Flags @@ -852,15 +856,15 @@ A Kubernetes cluster running Crossplane isn't required. #### 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. +The `crossplane beta validate` command can validate an XR and one or more +managed resources against a provider's schema. {{}} 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. +Access to a Kubernetes cluster or Crossplane pod isn't required. Validation requires the ability to download the provider package. {{< /hint >}} @@ -872,12 +876,12 @@ 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://marketplace.upbound.io/providers/upbound/provider-aws-iam/v1.0.0) +from Provider AWS, use the +[Provider AWS IAM](https://marketplace.upbound.io/providers/upbound/provider-aws-iam/v1.0.0) manifest. {{}} -To validate a +To validate a "[family provider](https://blog.upbound.io/new-provider-families)" use the provider manifests of the resources to validate. {{< /hint >}} @@ -893,9 +897,9 @@ spec: Now include the XR or managed resource to validate. -For example, to validate an +For example, to validate an {{}}AccessKey{{}} managed resource, -provide a managed resource YAML file. +provide a managed resource YAML file. ```yaml {label="iamAK"} apiVersion: iam.aws.upbound.io/v1beta1 @@ -910,7 +914,7 @@ spec: ``` Run the `crossplane beta validate` command providing the provider and managed -resource YAML files as input. +resource YAML files as input. ```shell crossplane beta validate provider.yaml managedResource.yaml @@ -921,13 +925,13 @@ Total 1 resources: 0 missing schemas, 1 success case, 0 failure cases #### Validate render command output -You can pipe the output of `crossplane beta render` into +You can pipe the output of `crossplane beta render` into `crossplane beta validate` to validate complete Crossplane resource pipelines, -including XRs, compositions and composition functions. +including XRs, compositions and composition functions. -Use the `--include-full-xr` command with `crossplane beta render` and the `-` -option with `crossplane beta validate` to pipe the output from -`crossplane beta render` to the input of `crossplane beta validate`. +Use the `--include-full-xr` command with `crossplane beta render` and the `-` +option with `crossplane beta validate` to pipe the output from +`crossplane beta render` to the input of `crossplane beta validate`. ```shell {copy-lines="1"} crossplane beta render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml - @@ -942,11 +946,11 @@ 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 +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 +Apply a CEL rule with the {{}}x-kubernetes-validations{{}} key inside the schema {{}}spec{{}} object of an XRD. @@ -970,14 +974,14 @@ spec: type: integer maxReplicas: type: integer - replicas: + replicas: type: integer # Removed for brevity ``` The rule in this example checks that the vale of the {{}}replicas{{}} field of an XR is between -the {{}}minReplicas{{}} and +the {{}}minReplicas{{}} and {{}}maxReplicas{{}} values. ```yaml {label="celXR"} @@ -1003,14 +1007,14 @@ Total 1 resources: 0 missing schemas, 0 success cases, 1 failure cases #### Validate against a directory of schemas -The `crossplane beta render` command can validate a directory of YAML files. +The `crossplane beta 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. +With a directory of files, provide the directory and resource to validate. -For example, using a directory named +For example, using a directory named {{}}schemas{{}} containing the XRD and Provider schemas. @@ -1025,8 +1029,8 @@ schemas `-- xrd.yaml ``` -Provide the directory name and a resource YAML file to the -`crossplane beta validate` command. +Provide the directory name and a resource YAML file to the +`crossplane beta validate` command. ```shell crossplane beta validate schema resources.yaml @@ -1041,11 +1045,11 @@ Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases ### beta xpkg init -The `crossplane beta xpkg init` command populates the current directory with -files to build a package. +The `crossplane beta 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 +Provide a name to use for the package and the package template to start from +with the command `crossplane beta xpkg init