Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

`--crossplane-binary` requires the Crossplane core binary, but the docs example points at the CLI

Aperta
  • Qualcosa non va?
#314 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 3 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
72/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
go
Ambito
cli, documentation

Direzione di ricerca

Leggi cmd/crossplane/render/engine.go:73 e cmd/crossplane/render/xr/help/render.md#L49-L54, quindi esamina l’invocazione documentata e il punto di ingresso dell’engine locale in cmd/crossplane/render/engine_local.go. Il lavoro è completato quando il flag e l’esempio incorporato richiedono chiaramente il binario principale di Crossplane, indicano la versione minima v2.3.0 e la posizione da cui scaricarlo, e non indirizzano più gli utenti al percorso CLI.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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):

--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:

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:

$ 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/<version>/bin/<os>_<arch>/crossplane; verified with
v2.4.0:

$ ./crossplane-core internal --help
Usage: crossplane internal <command> [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):

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/<version>/bin/<os>_<arch>/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.

Lingua principale
Go
Stelle
20
Fork
33
Merge medio
3g 10h
PR unite (30g)
24

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di crossplane/cli

Tutte le issue di crossplane/cli

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.