Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add extra-resources to cli docs #818

Merged
merged 2 commits into from
Oct 15, 2024
Merged

add extra-resources to cli docs #818

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
060fb97
add extra-resources to cli
stevendborrelli Sep 27, 2024
2d631c6
vale fixes
stevendborrelli Sep 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 67 additions & 54 deletions content/master/cli/command-reference.md
View file
Open in desktop
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
Loading