Skip to content

Update render documentation #1093

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

Open
adamwg wants to merge 1 commit into
base: master
Choose a base branch
from
+63 −41
Open

Update render documentation #1093

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
37 changes: 27 additions & 10 deletions content/master/composition/compositions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,19 +344,20 @@ learn how to install and use the Crossplane CLI.
{{< /hint >}}

{{<hint "important">}}
Running `crossplane render` requires [Docker](https://www.docker.com).
Running `crossplane composition render` requires
[Docker](https://www.docker.com).
{{< /hint >}}

Provide a composite resource, composition and composition functions to render
the output locally.

```shell
crossplane render xr.yaml composition.yaml functions.yaml
crossplane composition render xr.yaml composition.yaml functions.yaml
```

`crossplane render` prints resources as YAML to stdout. It prints the
composite resource first, followed by the resources the composition functions
created.
`crossplane composition render` prints resources as YAML to stdout. It prints
the composite resource first, followed by the resources the composition
functions created.

```yaml
---
Expand Down Expand Up @@ -387,8 +388,8 @@ spec:

{{<expand "The xr.yaml, composition.yaml and function.yaml files used in the example">}}

You can recreate the output below by running `crossplane render` with
these files.
You can recreate the output below by running `crossplane composition render`
with these files.

The `xr.yaml` file contains the composite resource to render:

Expand Down Expand Up @@ -451,7 +452,8 @@ Crossplane CLI runs a function by adding an annotation in `functions.yaml`. Add
the `render.crossplane.io/runtime` annotation to a Function to change how it's
run.

`crossplane render` supports two `render.crossplane.io/runtime` values:
`crossplane composition render` supports two `render.crossplane.io/runtime`
values:

* `Docker` (the default) connects to Docker Engine. It uses Docker to pull and
run a function runtime.
Expand Down Expand Up @@ -482,8 +484,8 @@ Use the `Development` runtime when you
function end-to-end.
{{</hint>}}

`crossplane render` also supports the following Function annotations. These
annotations affect how it runs Functions:
`crossplane composition render` also supports the following Function
annotations. These annotations affect how it runs Functions:

* `render.crossplane.io/runtime-docker-cleanup` - When using the `Docker`
runtime this annotation specifies whether the CLI should stop the function
Expand All @@ -497,6 +499,21 @@ the container, and `Orphan`, to leave it running.
running at the specified target. It uses
[gRPC target syntax](https://github.com/grpc/grpc/blob/v1.59.1/doc/naming.md).

{{<hint "tip">}}
The `crossplane composition render` CLI command runs the `crossplane internal
render` command from the Crossplane controller binary. By default, it runs the
latest stable version of Crossplane in a Docker container so that you don't need
to download the controller binary.

You can use the following flags to render using a different Crossplane version:

* `--crossplane-version` to run a different Crossplane version in Docker.
* `--crossplane-image` to select an arbitrary Crossplane Docker image (for
example, from a local mirror).
* `--crossplane-binary` to provide an arbitrary Crossplane controller binary
(for example, to test local changes to Crossplane).
{{</hint>}}

## Verify a composition

View all available Compositions with `kubectl get composition`.
Expand Down
22 changes: 11 additions & 11 deletions content/master/guides/write-a-composition-function-in-go.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,8 +449,8 @@ for the SDK.

## Test the function end-to-end

Test your function by adding unit tests, and by using the `crossplane render`
command.
Test your function by adding unit tests, and by using the `crossplane
composition render` command.

Go has rich support for unit testing. When you initialize a function from the
template it adds some unit tests to `fn_test.go`. These tests follow Go's
Expand Down Expand Up @@ -617,8 +617,8 @@ Expand the following block to see example files.

{{<expand "The xr.yaml, composition.yaml and function.yaml files">}}

You can recreate the output below using by running `crossplane render` with
these files.
You can recreate the output below using by running `crossplane composition
render` with these files.

The `xr.yaml` file contains the composite resource to render:

Expand Down Expand Up @@ -677,9 +677,9 @@ spec:

The Function in `functions.yaml` uses the
{{<hover label="development" line="6">}}Development{{</hover>}}
runtime. This tells `crossplane render` that your function is running
locally. It connects to your locally running function instead of using Docker to
pull and run the function.
runtime. This tells `crossplane composition render` that your function is
running locally. It connects to your locally running function instead of using
Docker to pull and run the function.

```yaml {label="development"}
apiVersion: pkg.crossplane.io/v1
Expand All @@ -702,10 +702,10 @@ to run without encryption or authentication. Only use it during testing and
development.
{{</hint>}}

In a separate terminal, run `crossplane render`.
In a separate terminal, run `crossplane composition render`.

```shell
crossplane render xr.yaml composition.yaml functions.yaml
crossplane composition render xr.yaml composition.yaml functions.yaml
```

This command calls your function. In the terminal where your function is running
Expand All @@ -717,8 +717,8 @@ go run . --insecure --debug
2023-10-31T16:17:32.159-0700 INFO function-xbuckets/fn.go:125 Added desired buckets {"xr-version": "example.crossplane.io/v1", "xr-kind": "XBuckets", "xr-name": "example-buckets", "region": "us-east-2", "count": 3}
```

The `crossplane render` command prints the desired resources the function
returns.
The `crossplane composition render` command prints the desired resources the
function returns.

```yaml
---
Expand Down
25 changes: 12 additions & 13 deletions content/master/guides/write-a-composition-function-in-python.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,8 +335,8 @@ for further details.

## Test the function end-to-end

Test your function by adding unit tests, and by using the `crossplane render`
command.
Test your function by adding unit tests, and by using the `crossplane
composition render` command.

When you initialize a function from the
template it adds some unit tests to `tests/test_fn.py`. These tests use the
Expand Down Expand Up @@ -479,8 +479,8 @@ Expand the following block to see example files.

{{<expand "The xr.yaml, composition.yaml and function.yaml files">}}

You can recreate the output below using by running `crossplane render` with
these files.
You can recreate the output below using by running `crossplane composition
render` with these files.

The `xr.yaml` file contains the composite resource to render:

Expand Down Expand Up @@ -537,11 +537,10 @@ spec:
```
{{</expand>}}

The Function in `functions.yaml` uses the
{{<hover label="development" line="6">}}Development{{</hover>}}
runtime. This tells `crossplane render` that your function is running
locally. It connects to your locally running function instead of using Docker to
pull and run the function.
The Function in `functions.yaml` uses the {{<hover label="development"
line="6">}}Development{{</hover>}} runtime. This tells `crossplane composition
render` that your function is running locally. It connects to your locally
running function instead of using Docker to pull and run the function.

```yaml {label="development"}
apiVersion: pkg.crossplane.io/v1
Expand All @@ -563,10 +562,10 @@ hatch run development
Only use it during testing and development.
{{</hint>}}

In a separate terminal, run `crossplane render`.
In a separate terminal, run `crossplane composition render`.

```shell
crossplane render xr.yaml composition.yaml functions.yaml
crossplane composition render xr.yaml composition.yaml functions.yaml
```

This command calls your function. In the terminal where your function is running
Expand All @@ -578,8 +577,8 @@ hatch run development
2024-01-11T22:12:58.153792Z [info ] Added desired buckets count=3 filename=fn.py lineno=68 region=us-east-2 tag=
```

The `crossplane render` command prints the desired resources the function
returns.
The `crossplane composition render` command prints the desired resources the
function returns.

```yaml
---
Expand Down
20 changes: 13 additions & 7 deletions content/master/operations/operation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -524,17 +524,23 @@ learn how to install and use the Crossplane CLI.
{{< /hint >}}

{{<hint "important">}}
Running `crossplane alpha render op` requires [Docker](https://www.docker.com).
The CLI hides alpha commands, including `crossplane operation render`, by
default. Run `crossplane config set features.enableAlpha true` to make it
visible.
{{< /hint >}}

{{<hint "important">}}
Running `crossplane operation render` requires [Docker](https://www.docker.com).
{{< /hint >}}

Provide an operation, composition functions, and any required resources to render
the output locally.

```shell
crossplane alpha render op operation.yaml functions.yaml --required-resources=ingress.yaml
crossplane operation render operation.yaml functions.yaml --required-resources=ingress.yaml
```

`crossplane alpha render op` prints the Operation status and any resources the
`crossplane operation render` prints the Operation status and any resources the
operation functions created or modified. It shows what would happen if you
applied the Operation to a cluster.

Expand Down Expand Up @@ -578,17 +584,17 @@ need access to. You can specify multiple files or use glob patterns:

```shell
# Multiple specific files
crossplane alpha render op operation.yaml functions.yaml \
crossplane operation render operation.yaml functions.yaml \
--required-resources=deployment.yaml,service.yaml,configmap.yaml

# Glob pattern for all YAML files in a directory
crossplane alpha render op operation.yaml functions.yaml \
crossplane operation render operation.yaml functions.yaml \
--required-resources="resources/*.yaml"
```

{{<hint "tip">}}
Use the `crossplane alpha render op` command to test your Operations locally
before deploying them to a cluster. The command helps validate function logic
Use the `crossplane operation render` command to test your Operations locally
before deploying them to a cluster. The command helps validate function logic
and required resource access patterns.
{{</hint>}}

Expand Down
Loading