[jcogilvie]

Description of your changes

Adds an alpha crossplane project simulate (#367) built on the crossplane diff engine, ported from crossplane-diff into internal/diff. It previews how a project's changed Compositions and embedded functions affect the XRs on a live cluster. Provider diff servers then plan each composed managed resource.

Builds on #429 (resource simulate, merged).

• Engine port (internal/diff/**): the renderer, types, ref, dockerrun, the core/kubernetes/crossplane clients and the diffprocessor, ported from crossplane-diff (import rewrites and gci grouping only), plus a client bundle client.New. It tracks upstream through crossplane-diff#591, #593, #594, #595, #597 and #598:

  • Object comparison lives in internal/diff/compare.
  • Processors return reports (XRReport, CompDiffOutput), and the command renders them.
  • The output model lives in internal/diff/result.
  • Filtered and pinned XRs are always recorded.
  • Errors print once, through kong, not inline.
  • Cluster lookups are built lazily, so a get-only identity works: no cluster-wide list of Functions, Compositions, XRDs or EnvironmentConfigs at startup.

  CLI-only engine additions, written to be upstreamable: an opt-in per-XR budget (WithXRTimeout), whose clock pauses while shared work runs (OutsideXRDeadline), and an after-XR hook (WithAfterXRDiff).

• Integration tests (internal/diff/integration): every case from crossplane-diff's TestDiffIntegration and TestCompDiffIntegration, run against envtest with the real Docker render engine. One runSimulate function translates each case's crossplane-diff arguments and runs the real project simulate command through kong. Structured assertions check plan.Result.

  • Both tables share one expectation builder (simtest.Expect() / AssertStructured), since every mode emits the same plan.Result. Each mode keeps its own matching rules, so no check got weaker or stricter.
  • There are also plan-output cases, least-privilege cases (a get-only user must produce the same output as admin), and provider-plan cases against an in-process fake diff server.
  • TestProjectSimulateIntegration runs the command on real project files: malformed and empty projects, a project mixed with other inputs, a plain project that must match Composition mode's result, an embedded function that must win over a same-named cluster Function, and a provider dependency that must decide which diff server is used (through a test-only SimulateHooks.Servers).
  • All cases pass except upstream's own two skips (CrossNamespaceResourceCollision, AddedResourceRetainsCompositionAuthoredStatus). No gap: skips remain.
  • They run natively on macOS as well as Linux (nix run .#integration-test, or ./nix.sh run .#integration-test in a container).

• Project glue:

  • project.LoadFunctions (lifted from render xr), project.LoadCompositions and project.LoadProviderDependencies.
  • An overlay FunctionProvider that serves project functions by name and falls back to the cluster's.
  • Detection of embedded functions whose digest differs from the cluster's, using the same index digest as project push.
  • kube.RESTConfig, now shared with resource simulate.

• project simulate command (alpha). -f/--input is repeatable and picks the mode from what it's given:

  • Project file (the default): Compositions from the project, with the project's functions overlaid on the cluster's.
  • Composition files: crossplane-diff's comp. XRs are found on the cluster, and the cluster's functions run.
  • XR or claim files: crossplane-diff's xr. Compositions and functions come from the cluster.
  • Rejected: a project file mixed with other inputs, and Compositions mixed with other resources.
  • Per-mode flags: a flag that doesn't apply to the chosen mode is rejected, as crossplane-diff's comp and xr do.
  • One path per -f: commas are part of the path; repeat -f for more inputs.
  • Validation before work: bad flag values (--name, -n, --max-concurrency, --max-iterations, --timeout) fail during parsing, before any function build or server start.
  • Other flags: -c/--context, impersonation, -n, --name (repeatable, comma-separated, accepts ns/name), --include-pinned, --max-iterations, --timeout, --max-concurrency, --cache-dir, -o plan|diff|json|yaml, the render-backend version flags, and crossplane-diff's other common flags (--ignore-paths, --function-credentials, --dry-run-on, --analyze-on, ...).

• Provider plans: each composed managed resource is planned by its provider's diff server, with resource simulate's Planner, now shared in internal/simulate. Unchanged provider-managed resources are planned too, so cloud drift shows.

  • Flags: --skip-plan, --providers, --image-configs and --session-id. Planning is on by default.
  • Which servers start: --providers overrides. Otherwise project mode uses the project's provider dependencies, and Composition and XR modes start the cluster's providers on demand for the kinds actually rendered. A failed lookup for a kind skips that kind with one warning.
  • Unsupported kinds: a kind no server serves keeps the cluster diff. A server that says it can't diff marks the plan approximate.

• Output: -o plan is the default terraform-style view. -o json|yaml emit plan.Result (formatVersion 0.3) through one mapper (internal/simulate.FromXRReport and FromCompReport). -o diff is crossplane-diff's diff, plus inline # forces replacement, (known after apply) and a (requires replacement) header and summary count, but only when provider plans ran. Without them it is byte-identical to crossplane-diff.

• plan.Result: each plan carries before (live) and after (rendered), the cleaned objects the diff compares, with Secret values redacted. It also carries composite grouping, typed errors with validation failures, warnings, revision impact for each Composition, dry-run verification, a deferred count, and notes. The notes say when the provider layer was skipped or no diff server served the resources. resource simulate shares the model, so its JSON gains before/after and the same stripping.

• Render: a typed render.ErrStaleRenderBackend, so the engine can tell a stale render backend apart from other errors.

• Pinned XRs: an XR on a Manual policy whose pinned revision calls a changed embedded function is rendered against that revision, with the project's functions, and reported with pinned: true and a detail naming the revision. Otherwise pinned XRs are deferred, still with pinned: true.

• Nix and CI: pinned Crossplane v2.4.1 CRDs and envtest v1.30.3 assets (Linux and macOS, amd64 and arm64) for the tests. The integration tests need Docker for the render engine, and the Nix sandbox has none.

  • So they sit behind an integration build tag, the same way the existing compilegate tests do, and lint still covers them.
  • They run through their own nix run .#integration-test app and integration-tests CI job, outside the sandbox. Unit tests and flake check are unchanged. The app keeps the host PATH (nix inputs first) so Docker's credential helpers resolve.
  • The integration job uploads a -coverpkg=./... profile to codecov under the integration flag, and codecov merges it with the unittests upload for the same commit.
  • A later e2e suite fits in as a third tag, app and job.

Still to do for #367:

• A docs PR for Document crossplane project simulate and crossplane resource simulate docs#1162, after this PR passes review.

Decisions to review (hard to reverse, even under alpha):

• project simulate writes into the project. In project mode, simulate builds the embedded functions the same way project build and render xr do. That generates language schemas into the project's schemas/ directory as a side effect. For a preview command, that may be unexpected: running it in CI or on a clean checkout leaves a modified working tree. Should simulate generate schemas into a temporary directory instead, leaving the project untouched? Or is writing them acceptable, since render xr already does it and the schemas are needed to build the functions anyway? If we change it, should render xr change with it?
• Output: -o plan is the default, -o json|yaml emit plan.Result, and crossplane-diff's v1/v2 JSON schemas are gone.
• plan.Result field shapes: every summary count is always present (deferred included); a composite's reason is a camelCase enum (manualPolicy, revisionSelectorMismatch, deleting, unknown), mapped explicitly from the engine's values so an upstream rename can't silently change the contract; an error's resource is errors[].ref; pinned is true for every XR on a Manual policy. Every input mode emits this one shape, but compositions and composites are omitempty, so an XR-mode result has no compositions key rather than []. Do reviewers agree, or should both always be present so consumers see the same keys whatever -f is given?
• before/after in plan.Result: they follow terraform's show -json and are null for a create or delete respectively. A resource whose only change is provider-side drift has no objects.
• Field path grammar in plan.Result: path is one string. Plain keys join with ., list indexes are [N], and any other key is quoted terraform-style as ["key"], e.g. metadata.annotations["crossplane.io/composite"]. This lets annotation and label keys round-trip, but json/yaml consumers must parse the grammar to split a path. An additive segments list is an option if that's a burden. Paths from upjet's diff servers don't quote dotted TF map keys (e.g. a tags key a.b), which needs an upjet change.
• Exit codes:
  • The codes are 0 (no changes), 1 (error), 2 (schema validation only), 3 (changes found), 80 (invalid flags or arguments, kong's usage-error code) and 130 (interrupted), with crossplane-diff's precedence 1 > 2 > 3, so changes exit 3 by default as in crossplane-diff.
  • Exit 3 counts both cluster changes and provider changes, including drift. Deferred and skipped results don't count. An approximate plan adds no change of its own, but the cluster change it annotates still counts.
  • Changes found are a result, not an error: simulate sets a kong-bound common.ExitStatus that main exits with after a run that returns no error. Errors still exit through kong's FatalIfErrorf.
• Failure unit: the XR, all-or-nothing, matching the engine.
  • --timeout (default 2m, must be > 0) is a per-XR budget covering the XR's render and its resources' provider plans.
  • Function and provider image pulls and server starts don't count against it. The crossplane render image pull still counts against the first XR's budget, and the help says so.
  • A plan error or timeout on any of an XR's resources fails that XR with none of its plans, and the run exits 1.
• Flag names: -f/--input, --name, --include-pinned, -c/--context, --skip-plan, --providers, --image-configs, --session-id.
• -f classification: a single file that isn't a project file and holds no Compositions is treated as XRs. Each one is checked against the cluster's XRDs, as a claim and then as an XR. Anything else (a Configuration, a Provider, a ConfigMap) is rejected with its kind, name and what -f accepts.
• Errors print once: the ported renderers no longer write each error to stderr inline as ERROR: Kind/name: .... kong prints the returned error once, as crossplane: error: ..., and that error names each failing resource. Structured output's errors[] is unchanged.
• Target cluster: the user's kubeconfig context, not the dev control plane.

Also worth a look:

• fix(project): project build with spec.paths.apis: "/" no longer packages XRDs and Compositions from examples, functions and operations. It's a separate commit, easy to cherry-pick on its own.
• resource simulate changes:
  • Its planning moved into internal/simulate, including fix(simulate): stop planning server-defaulted and late-initialized fields as removals in the approximate diff #441's CRD defaulting and Simulate development runtime #443's Development runtime, so project simulate's provider plans get both.
  • A failed CRD or ProviderRevision lookup now warns and keeps the cluster diff instead of failing the run.
  • --timeout 0 means no per-plan limit.
  • It still exits 0 on a failed provider plan; bringing it in line with project simulate is a follow-up.
• Dependency bumps forced by the port: go.yaml.in/yaml/v3 v3.0.5, golang.org/x/sys v0.48.0. The port's semver use moved to Masterminds v3.
• Exit code 80: a render version below the v2.3.4 floor also exits 80, as a usage error.
• Sequential engine: the engine renders XRs one at a time, and the provider-plan caches rely on that. Their docs say so.
• No manual end-to-end run: the command hasn't been run by hand against a real cluster or real provider diff servers; the integration tests use envtest and a fake diff server. Stdin input (-f -) hasn't been tested end to end.

I have:

• Read and followed Crossplane's contribution process.
• Run ./nix.sh flake check to ensure this PR is ready for review.
• Added or updated unit tests.
• Linked a PR or a docs tracking issue to document this change: Document crossplane project simulate and crossplane resource simulate docs#1162.
• Added backport release-x.y labels to auto-backport this PR.

🤖 Generated with Claude Code

[haarchri]

what happen if two XRs render the same composed resource differently, XR B report is merged with a provider plan computed from XR A desired object. Please key by (XR, diff key), or flag the conflict?!

[haarchri]

Keys that are already collected are still planned over gRPC, and the result is thrown away; if that call fails, XR B fails for nothing. Please skip keys you already have.

[haarchri]

The mutex only covers half of the contract, while the comment says the engine is sequential. Either drop it and document not safe for concurrent use, or lock all of AfterXRDiff

[haarchri]

There are three caches with three failure policies. crdDefaults refuses to cache transient errors, but RelevantProviderImages caches "" on any error and ProviderManaged caches false silently, which drops provider-found drift. Please use one rule: never cache non-definite answers.

[haarchri]

nit: the same CRD is fetched by multiple code paths:
ProviderManaged, RelevantProviderImages and default.go, on top of the engines own SchemaClient CRD cache. Please use one per-run CRD lookup and derive the answers from it

[haarchri]

resolveRenderImage is a copy of render.crossplaneImageFromFlags. Please export the render helper and delete this one. RenderImage() is used only in tests...

[haarchri]

The user-facing text says "use --include-manual", but the flag here is --include-pinned - think in the design doc we usinging include-manual right ?

[haarchri]

is this every used ? feels death code here

[haarchri]

This is a third container cleanup scheme next to internal/containerruntime and internal/diffserver, which use other labels and are never reaped. One command now has two cleanup strategies. Please either move lease/reap into containerruntime for everything, or drop it from this PR.

[haarchri]

Per run we now build two Kubernetes client stacks with two discovery caches (client/core + client/kubernetes vs simulate.NewKubeClient) and two CRD-default caches (diffprocessor/defaulter.go vs internal/simulate/defaults.go). Please share one.