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

[kaessert]

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-<random> 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 "<name>" 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: crossplane/cli#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:

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

• --crossplane-binary=<path> 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+).

[haarchri]

the command reference is generated, let's Update the help texts in the cli