`--crossplane-binary` requires the Crossplane core binary, but the docs example points at the CLI
- Dominant language
- Go
- Stars
- 19
- Forks
- 31
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 52
Description
### What happened?
`--crossplane-binary` requires the Crossplane **core** binary (`crossplane/crossplane`), but nothing
says so, and the docs example points at the path where the **CLI** installs itself. The documented
invocation always fails.
Flag help (`cmd/crossplane/render/engine.go:73`):
```text
--crossplane-binary=PATH Path to a local crossplane binary to use instead of Docker.
```
Docs example (`cmd/crossplane/render/xr/help/render.md#L49-L54`). `/usr/local/bin/crossplane` is
exactly where `install.sh` puts the CLI:
```shell
crossplane composition render xr.yaml composition.yaml functions.yaml \
--crossplane-binary=/usr/local/bin/crossplane
```
The local engine shells out to `crossplane internal render`
(`cmd/crossplane/render/engine_local.go:66`), and `internal render` is a **hidden** subcommand of the
core binary (`crossplane/crossplane`, `cmd/crossplane/internal.go`, `cmd/crossplane/main.go#L57`),
not of the CLI:
```console
$ crossplane composition render xr.yaml composition.yaml functions.yaml \
--crossplane-binary=$(command -v crossplane)
crossplane: error: cannot render composite resource: crossplane internal render returned error with output:
crossplane: error: unexpected argument internal
: exit status 80
```
Nothing there says "wrong binary", and since `internal` is `hidden:""`, `crossplane --help` lists it
on neither binary. The requirement isn't discoverable from the tooling.
The core binary does work, but it's not a GitHub release asset and `install.sh` doesn't fetch it. It
lives at `https://releases.crossplane.io/stable//bin/_/crossplane`; verified with
v2.4.0:
```console
$ ./crossplane-core internal --help
Usage: crossplane internal [flags]
Commands:
internal render [flags]
Render resources using the real reconciler engine. Not for direct use.
```
`cmd/crossplane/internal.go` first appears in core v2.3.0 (absent in v2.2.0), so v2.3.0 is the floor.
Both pieces of affected text live in this repo (the kong flag help in `cmd/crossplane/render/engine.go` and the embedded help page `cmd/crossplane/render/xr/help/render.md`), so this isn't a docs-site issue.
### How can we reproduce it?
1. Install the CLI (`curl -sL https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh | sh`).
2. Run `crossplane composition render ... --crossplane-binary=$(command -v crossplane)`, as the docs example shows.
3. `crossplane: error: unexpected argument internal`.
Reproduced with CLI v2.4.0 and v2.4.1.
### What environment did it happen in?
* Crossplane CLI version: v2.4.0 and v2.4.1
* Platform (e.g., linux/amd64): darwin/arm64
* Crossplane version (if applicable): core v2.4.0 (works), CLI v2.4.0/v2.4.1 (fails)
### Why it matters
`--crossplane-binary` is the documented escape hatch for machines without a working Docker daemon,
and those are the machines that need it. Podman is the common case (#299, and the same failure with
`409` instead of `500`):
```text
cannot render composite resource: crossplane internal render in Docker returned error with output:
: failed to attach to container: unable to upgrade to tcp, received 409
```
So a Podman user follows the docs to `--crossplane-binary`, points it at the `crossplane` on their
`PATH` as the example shows, and hits `unexpected argument internal`. At that point `render` has no
working path at all, and no error in the chain points at the cause.
### What would help
- **Say "core" wherever the flag appears.** Flag help: "Path to a local Crossplane **core** binary
(not the Crossplane CLI)...", plus a line in `render.md` with the download location
(`https://releases.crossplane.io/stable//bin/_/crossplane`) and the v2.3.0 minimum.
- **Fix the docs example.** `/usr/local/bin/crossplane` is the CLI's own install path, so it reads as
an endorsement of the one binary that can't work.
- **Fail actionably.** A preflight check, or matching `unexpected argument internal` on stderr, could
say: "the binary at PATH doesn't support `internal render`; `--crossplane-binary` needs the
Crossplane core binary (v2.3.0+), not the CLI. Get it from releases.crossplane.io/stable/...".
- **A Podman note in the docs**, since the attach failure gives no hint that the runtime is the problem.
Happy to send a PR for the docs and flag-help wording.
Contributor guide
Research direction
Read cmd/crossplane/render/engine.go:73 and cmd/crossplane/render/xr/help/render.md#L49-L54, then review the documented invocation and the local engine entry point in cmd/crossplane/render/engine_local.go. Done means the flag and embedded example clearly require the Crossplane core binary, identify the v2.3.0 minimum and download location, and no longer point users to the CLI path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100