Skip to content

Commit

Permalink
Merge pull request #818 from stevendborrelli/extra-resources
Browse files Browse the repository at this point in the history 
add extra-resources to cli docs
  • Loading branch information
@phisco
phisco authored Oct 15, 2024
2 parents 362c90c + 2d631c6 commit e0b13c5
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 109 deletions.
121 changes: 67 additions & 54 deletions content/master/cli/command-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,22 @@ description: "Command reference for the Crossplane CLI"


<!-- vale Google.Headings = NO -->
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]({{<ref "../cli">}}) page for information on
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
Expand All @@ -28,29 +31,29 @@ and the control plane.

```shell
crossplane version
Client Version: v1.16.0
Server Version: v1.16.0
Client Version: v1.17.0
Server Version: v1.17.0
```

## render
## render

The `crossplane render` command previews the output of a
[composite resource]({{<ref "../concepts/composite-resources">}}) after applying
[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
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.
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`
Expand All @@ -59,6 +62,7 @@ The output includes the original composite resource followed by the generated
managed resources.

{{<expand "An example render output" >}}

```yaml
---
apiVersion: nopexample.org/v1
Expand Down Expand Up @@ -87,62 +91,64 @@ 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.
|
| `-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.
{{< /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
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 render` command only prints the
`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 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 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
{{<hover label="apiVersion" line="1">}}apiVersion{{</hover>}},
{{<hover label="apiVersion" line="2">}}kind{{</hover>}},
{{<hover label="apiVersion" line="3">}}metadata{{</hover>}} and
Expand All @@ -161,31 +167,40 @@ spec:

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.
and publishing of Crossplane packages to a Crossplane package registry.

### xpkg build

Using `crossplane xpkg build` provides automation and simplification to 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
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/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.

[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. |
Expand All @@ -196,12 +211,12 @@ 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

Expand Down Expand Up @@ -972,16 +987,15 @@ crossplane beta validate provider.yaml managedResource.yaml
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
You can pipe the output of `crossplane 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 render` and the `-`
option with `crossplane beta validate` to pipe the output from
`crossplane render` to the input of `crossplane beta validate`.
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 -
Expand All @@ -994,8 +1008,8 @@ crossplane render xr.yaml composition.yaml function.yaml --include-full-xr | cro
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/)).

Expand Down Expand Up @@ -1031,7 +1045,7 @@ spec:

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
the {{<hover label="celXR" line="7">}}minReplicas{{</hover>}} and
{{<hover label="celXR" line="8">}}maxReplicas{{</hover>}} values.

```yaml {label="celXR"}
Expand All @@ -1054,17 +1068,16 @@ error.
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 `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.
With a directory of files, provide the directory and resource to validate.

For example, using a directory named
For example, using a directory named
{{<hover label="validateDir" line="2">}}schemas{{</hover>}} containing the XRD
and Provider schemas.

Expand All @@ -1079,8 +1092,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
Expand Down
Loading

0 comments on commit e0b13c5

Please sign in to comment.