Document the per-invocation Docker network that `composition render` creates since CLI v2.3.0
- 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.