diff --git a/config.yaml b/config.yaml index 7484a7429..17bf050ae 100644 --- a/config.yaml +++ b/config.yaml @@ -94,7 +94,7 @@ security: # Global parameters accessible by any Page params: # The current "latest" version. Used in the version dropdown - latest: "2.3" + latest: "2.4" # The current "latest" version of the CLI docs. Used in the CLI version # dropdown. cliLatest: "2.4" diff --git a/content/cli/v2.1/_index.md b/content/cli/v2.1/_index.md deleted file mode 100644 index 6be6e03fb..000000000 --- a/content/cli/v2.1/_index.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -weight: 50 -title: CLI Overview -description: "Command-line tools for Crossplane development" -cascade: - version: "2.1" ---- - -The Crossplane CLI helps simplify some development and administration aspects of -Crossplane. - -The Crossplane CLI includes: -* tools to build, install, update and push Crossplane Packages -* standalone Composition Function testing and rendering without the need to access a Kubernetes cluster running Crossplane -* troubleshoot Crossplane Compositions, Composite Resources and Managed Resources - -## Installing the CLI - -The Crossplane CLI is a single standalone binary with no external dependencies. - -{{}} -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 >}} - -To download the latest version for your CPU architecture with the Crossplane -install script. - -```shell -curl -sL "https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh" | sh -``` - -[The script](https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh) -detects your CPU architecture and downloads the latest stable release. - -{{}} - -If you don't want to run shell script you can manually download a binary from -the Crossplane releases repository at -https://releases.crossplane.io/stable/current/bin - -{{}} - -The release repository names the CLI `crank`. Download this file. - - -The `crossplane` binary is the Kubernetes Crossplane pod image. -{{< /hint >}} - -Move the binary to a location in your `$PATH`, for example `/usr/local/bin`. -{{< /expand >}} - -### Download other CLI versions - -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 `v1.20.0` add `XP_VERSION=v1.20.0` to the -download script curl command: - -```shell -curl -sL "https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh" | XP_VERSION=v1.20.0 sh -``` - -To install the CLI from the `master` channel add `XP_CHANNEL=master`: - -```shell -curl -sL "https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh" | XP_CHANNEL=master sh -``` diff --git a/content/cli/v2.1/command-reference.md b/content/cli/v2.1/command-reference.md deleted file mode 100644 index 88d83644c..000000000 --- a/content/cli/v2.1/command-reference.md +++ /dev/null @@ -1,1101 +0,0 @@ ---- -weight: 100 -title: Command Reference -description: "Command reference for the Crossplane CLI" ---- - - - -The `crossplane` CLI provides utilities to make using Crossplane easier. - -Read the [Crossplane CLI overview]({{}}) 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]({{}}) after applying -any [composition functions]({{}}). - -{{< 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. - -{{}} -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. - -{{}} - -```yaml ---- -apiVersion: nopexample.org/v1 -kind: XBucket -metadata: - name: test-xrender -status: - bucketRegion: us-east-2 ---- -apiVersion: s3.aws.m.upbound.io/v1beta1 -kind: Bucket -metadata: - annotations: - crossplane.io/composition-resource-name: my-bucket - generateName: test-xrender- - labels: - crossplane.io/composite: test-xrender - namespace: default - ownerReferences: - - apiVersion: nopexample.org/v1 - blockOwnerDeletion: true - controller: true - kind: XBucket - name: test-xrender - uid: "" -spec: - forProvider: - region: us-east-2 -``` - -{{< /expand >}} - -### Flags - -{{< table "table table-sm table-striped">}} - -| Short flag | Long flag | Description | -| ------------ | ------------- | ------------------------------ | -| | `--context-files==,=` | A comma separated list of files to load for function "contexts." | -| | `--context-values==,=` | A comma separated list of key-value pairs to load for function "contexts." | -| `-r` | `--include-function-results` | Include the "results" or events from the function. | -| `-o` | `--observed-resources=` | Provide artificial managed resource data to the function. | -| `-e` | `--extra-resources=PATH` | A YAML file or directory of YAML files specifying extra resources to pass to the Function pipeline. | -| `-c` | `--include-context` | Include the context in the rendered output as a resource of kind: Context. | -| `-x` | `--include-full-xr` | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. | -| | `--timeout=` | Amount of time to wait for a function to finish. (Default 1 minute) | - -{{< /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 -{{}}apiVersion{{}}, -{{}}kind{{}}, -{{}}metadata{{}} and -{{}}spec{{}}. - -```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]({{}}) and 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 "/v2.1/packages/configurations" >}}), -[function]({{}}) and -[provider]({{}}) package types. - -#### Flags - -{{< table "table table-sm table-striped">}} - -| Short flag | Long flag | Description | -| ------------ | ------------- | ------------------------------ | -| | `--embed-runtime-image=NAME` | The image name and tag of an image to include in the package. Only for provider and function packages. | -| | `--embed-runtime-image-tarball=PATH` | The filename of an image to include in the package. Only for provider and function packages. | -| `-e` | `--examples-root="./examples"` | The path to a directory of examples related to the package. | -| | `--ignore=PATH,...` | List of files and directories to ignore. | -| `-o` | `--package-file=PATH` | Directory and filename of the created package. | -| `-f` | `--package-root="."` | Directory to search for YAML files. | -{{< /table >}} - -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 and a container image for their runtime. - -Using `--embed-runtime-image` runs a specified image and -includes the image inside the function or provider package. - -{{}} -Images referenced with `--embed-runtime-image` 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