crossplane / crossplane/docs

Document the per-invocation Docker network that `composition render` creates since CLI v2.3.0

Open
#1,150 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
SCSS
Stars
60
Forks
163
Avg merge
15h 20m
Merged PRs (30d)
9

Description

### What's Missing?

Since Crossplane CLI v2.3.0, `crossplane composition render` runs the Crossplane render engine as its own Docker container. So that the engine can reach the function containers, the CLI creates a **new, randomly named `crossplane-render-` bridge network on every invocation** and injects `render.crossplane.io/runtime-docker-network` into every function that doesn't already carry that annotation.

That's a significant behaviour change from pre-2.3 render, and it isn't documented. Three specific gaps:

**1. No prose explaining that render now needs a Docker network.**

The `important` hint under `composition render` only says the command requires a working Docker installation and points at `--crossplane-binary`. Nothing explains that a network is created per run, or why.

**2. The consequences for preloaded function containers are undocumented.**

The annotation table documents `render.crossplane.io/runtime-docker-name` as "Create or reuse a container with the given name" and `render.crossplane.io/runtime-docker-cleanup: "Orphan"` as "Don't stop the Function's Docker container after rendering" — together, the documented way to start functions once and render many times against them.

Since v2.3.0 that combination breaks. A reused named container is not attached to the new network the run just created, so the second and every subsequent render fails with:

```
container "" is not connected to Docker network "crossplane-render-XXXXXXXX";
verify the "render.crossplane.io/runtime-docker-network" annotation value matches an existing network
```

Anyone following the current docs has no way to anticipate this, nor to discover that the fix is to pre-create a single network and pass `--crossplane-docker-network`. Related CLI issue: https://github.com/crossplane/cli/issues/75

**3. `render.crossplane.io/runtime-docker-network` is missing from the annotation table**, even though it is the annotation the CLI writes itself. And `--crossplane-docker-network` (added in CLI v2.4.0) appears only as a one-line entry in the flag table, with no usage guidance.

### Affected pages

- https://docs.crossplane.io/cli/v2.5/command-reference/ — `composition render` and `operation render`
- https://docs.crossplane.io/cli/v2.4/command-reference/ — same
- https://docs.crossplane.io/cli/v2.3/command-reference/ — worse: `--crossplane-docker-network` doesn't exist in v2.3, so there is no documented way to keep preloaded containers working on that release. `--crossplane-binary` is the only escape hatch and isn't presented as one.

### Suggested content

A short subsection under `composition render`, next to "Function runtime configuration":

- The render engine runs in its own container by default, and the CLI creates a temporary Docker network per invocation so the engine and the function containers can reach each other.
- Add `render.crossplane.io/runtime-docker-network` to the annotation table.
- To preload functions and render repeatedly against them — or to run several renders in parallel — create the network up front and reuse it:

```shell
docker network create crossplane-render

crossplane composition render xr.yaml composition.yaml functions.yaml \
--crossplane-docker-network=crossplane-render
```

- `--crossplane-binary=` runs the engine as a local process instead, with no Docker network involved at all. Worth noting it is mutually exclusive with `--crossplane-docker-network`.
- Note the CLI version each flag landed in (`--crossplane-docker-network` is v2.4.0+).

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.