Skip to content

feat(resource): report live health in resource simulate - #566

Draft
jcogilvie wants to merge 30 commits into
crossplane:mainfrom
jcogilvie:jco-simulate-health-resource
Draft

jcogilvie wants to merge 30 commits into
crossplane:mainfrom
jcogilvie:jco-simulate-health-resource

Conversation

@jcogilvie

Copy link
Copy Markdown
Collaborator

Note

Depends on #554 (which depends on #546) and contains their commits, since a fork's PR can't target another fork branch. Review only the commits from feat(resource): carry the live resource's health on each plan onward. Once #546 and #554 merge, this diff narrows to them.

Description of your changes

Third of three stacked PRs for #539. #546 and #554 added live health to crossplane {xr,composition,project} simulate. This PR gives crossplane resource simulate the same treatment, so a managed resource that is already failing doesn't look like a safe change.

  • Health on each plan. Planner.Plan already fetches each input's live object, and now sets the plan's health from it with health.Of. There are no new cluster reads. A create has no live object and so has no health.
  • Plan output. An unhealthy resource gets a ⚠ <tier> (<condition>, <reason>): <message> line under its header. Unchanged inputs ([=]) get it too, since this command already lists every input. A Health: line follows Plan:, naming only the non-zero counts. Healthy runs print exactly what they print today; no existing golden changed.
  • --full-messages. Prints condition messages in full instead of cut to one line, as in the other simulate commands. With -o json|yaml it has no effect, and the command now warns about that on stderr, with the same wording as the other commands. The wording lives in one shared helper, simulate.WarnIgnoredFullMessages.
  • JSON/YAML. Each plan carries health, and summary.health carries the counts, in the shape feat(simulate): report the live health of XRs and composed resources #546 defined. HealthSummary moves from internal/simulate to internal/plan so both results share it; xr/composition/project output is unchanged. unhealthyComposites is always 0 here, since this command takes no composites. formatVersion stays 0.2, the constant the other commands use.
  • Exit status. An errored plan still exits 1. Otherwise the status is the same bitmask as feat(simulate): show health in simulate output and exit 4 when a resource is failing #554: 3 = changes, 4 = a failing (Synced=False) resource before apply, 7 = both. Not ready or paused never sets 4. help/simulate.md's exit and output sections are rewritten to match.
  • Tests.
    • Table tests cover the health wiring (create, no conditions, failing), the ⚠ and Health: lines, JSON and YAML summary.health, and exit codes 4 and 7.
    • Run's rendering and exit status move into two small functions, renderer and report, with no change in behaviour, so a test can drive them through real kong parsing. It checks the warning, that --full-messages reaches the renderer, and the exit status.
    • There's no integration test: the envtest harness only wires up xr, composition and project simulate, and this command has none today.

Example (-o plan, as asserted in internal/plan's output tests): a failing input with a change, plus a not-ready and a paused input without one.

[~] Subnet.ec2.aws.upbound.io my-subnet (update)
    ⚠ failing (Synced=False, ReconcileError): The vpc ID 'vpc-048777c3b8a8ee173' does not exist status code: 400
    spec:
      forProvider:
        ~ cidrBlock: "10.0.1.0/24" -> "10.0.2.0/24"

[=] VPC.ec2.aws.upbound.io my-vpc (no-op)
    ⚠ not ready (Ready=False, Creating)

[=] VPC.ec2.aws.upbound.io paused-vpc (no-op)
    ⚠ paused

Plan: 0 to add, 1 to change, 0 to destroy.
Health: 1 resource failing (Synced=False), 1 not ready, 1 paused.

This run exits 7.

Points for review:

  • Exit codes 4 and 7 are new public behaviour for this command too.
  • plan.NewRenderer now takes (format, fullMessages). It's internal, and every caller is updated.

Stack (#539):

  1. feat(simulate): report the live health of XRs and composed resources #546: health model, engine plumbing, JSON output.
  2. feat(simulate): show health in simulate output and exit 4 when a resource is failing #554: text and -o diff rendering, exit bit 4, --full-messages, for xr/composition/project simulate.
  3. This PR: the same for crossplane resource simulate.

I have:

  • Read and followed Crossplane's contribution process.
  • Read and followed Crossplane's AI policy and confirmed a human stands behind this PR.
  • Run ./nix.sh flake check to ensure this PR is ready for review. Ran go build, go vet (with and without the integration tag), go test ./..., golangci-lint run ./... (with and without the integration tag) and nix run .#integration-test instead, since nix.sh needs Docker.
  • Added or updated unit tests.
  • Linked a PR or a docs tracking issue to document this change. The command's help (cmd/crossplane/simulate/help/simulate.md) is updated in this PR.
  • Added backport release-x.y labels to auto-backport this PR. Not a backport candidate.

Need help with this checklist? See the cheat sheet.

🤖 Generated with Claude Code

jcogilvie and others added 30 commits November 19, 2026 14:49
Add a leaf package that maps a live object to a health tier: paused (the
crossplane.io/paused annotation, overriding conditions), failing
(Synced=False), notReady (Ready=False) or healthy, carrying the Synced and
Ready conditions it was classified from.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Record the health of each XR's live object and of the composed resources
the diff engine already fetched to render it, on XRDiffGroup and XRImpact.
No new cluster reads: the XR comes from the resolved composite's cluster
copy, and composed resources from the observed resources render consumes,
before --eventual-state synthesizes any Ready condition. A nested XR's
observed resources merge into its parent's once, keyed by identity.

DiffSingleResource now returns the RenderedResources it built, so the
composition path gets health along with the unchanged renderings.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Each plan with a live object carries its health; each composite carries
the health of its live XR and lists the not-healthy composed resources
that have no plan of their own. The summary counts unhealthy composites
and failing, notReady and paused resources, each once. Bump the result
format version to 0.2 and document the new fields.

Text and diff output are unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
…health once

A claim mirrors only part of its backing XR's conditions, so the composite
health of a claim input is now its backing XR's.

RenderedResources classifies health as it records the live objects instead
of retaining them. Merge now records each nested composite's health, with
the nested composite as the via of what it composes directly, so every
composed resource is listed once with the composite that composes it. That
also covers a nested XR found by name rather than in its parent's observed
set, which previously lost its health when it had no plan.

The comp path stores each XR's computed health rather than its render.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
…ummary health

Each unhealthy entry names the nested composite that composes it under
via. The health counts move under summary.health, and a composite in two
entries is counted once. The help documents via, summary.health, a claim's
health, and that a composite that was not simulated has no health.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
PR 1 reports each composite's live health, so the project simulate
integration cases now see Health: healthy on every composite.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
A composition run gives a nested composite of the diffed composition's type
an entry of its own, now marked composedBy. Its parent's health also lists
it and what it composes, so each of those appeared in two unhealthy lists.

A nested composite with an entry and health of its own now shows its health
there and lists what it composes itself; its parent lists neither. One whose
entry has no health, because it wasn't simulated, stays listed under its
parent and counts there as a resource.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
An unhealthy XR's header and a plan whose live resource is not healthy now
carry a one-line health description: the tier, the condition it was read
from with its reason, and its message cut to 120 runes. Under each XR an
"Unhealthy resources without changes:" block lists the composed resources
that are unhealthy and have no plan, nesting each under the nested XR that
composes it. A Health: line after Plan: summarizes the counts. Healthy runs
print what they did before.

--full-messages prints the messages in full, wrapped and indented, and is
ignored, with a warning, for -o json and -o yaml. The formatting lives in
internal/health so the diff renderer can share it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
-o diff now shows what plan output does. An XR's health heads its section,
or the output for a single XR. A diffed resource that is not healthy is
marked on its header. Each XR's unhealthy resources without changes are
listed after its diffs, or after "No changes.". A Health: line closes the
run. The composition diff marks each affected XR's line and lists those
resources after the impact analysis. Both use the formatting in
internal/health and honour --full-messages. Healthy runs print what they
did before.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Without an error, a simulate run's exit status now adds 4 when a composite
resource, or a resource it composes, was failing (Synced=False) before
apply, including one the change would delete. So 4 means no changes and
something failing, and 7 means both. Errors still come first: 130 over 1
over 2. DetermineExitCode takes the failing state and composes the bits
in place of returning the first match. The exit help and the harness's
exit-code comment describe the new statuses.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
…tegration

Fixtures carry Synced=False, Ready=False and paused. The cases assert the
text output, the JSON health fields and summary.health, and exit codes 4
and 7. Under envtest no controller writes status, so the fixture loader
now writes a fixture's status through the status subresource.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
The paused fixture carried crossplane.io/paused under the Crossplane field
manager, so the dry-run apply removed it and the plan golden showed the
annotation being dropped. Apply it under kubectl instead, as a user would.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
When the XR's health line is printed for its group, the XR's own diff entry
carries only its tier marker, without the condition and message again.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
… diff

A nested XR with its own impact and health listed what it composes, and
its parent listed the same resources again. Share the plan output's rule
as health.OwnedElsewhere, used by both the simulate assembler and the
composition diff renderer across every composition in the run: each
resource is listed under the most deeply nested composite entry that has
health of its own.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
tallyComposite counted an XR without health, as one not yet in the
cluster or whose entry errored or was filtered, as a healthy composite.
That inflated the XR count past plan output's, and hid a nested XR's
failure: added as a composite, it was then skipped as a resource, so a
run that exits 4 printed no Health: line. Count a composite only when it
has health, as simulate's healthTally does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Planner.Plan already fetches each managed resource's live counterpart;
it now records that object's health on the plan it returns. A create has
no live object and so no health. No cluster reads are added.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Plan output gives each managed resource that isn't healthy before apply
a ⚠ line under its plan, unchanged inputs included, and adds a Health:
line after Plan: when anything is unhealthy. Healthy runs print what
they printed before. --full-messages prints condition messages in full,
wrapped, rather than cut to one line.

The JSON and YAML result carries summary.health, counted from the plans'
health, beside the per-plan health. HealthSummary moves to plan so both
results share it. formatVersion stays 0.2, which plan.ResultFormatVersion
already shares with the other simulate commands.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
resource simulate's exit status is now the same bitmask the other
simulate commands use: 3 for changes, 4 when a resource was failing
(Synced=False) before apply, 7 for both. Not ready and paused resources
don't set bit 4. An errored plan still exits 1 whatever else was found.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Add an output section to resource simulate's help covering the ⚠ line,
the Health: line, --full-messages and the JSON health fields, and
rewrite its exit statuses to match the bitmask.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
…yaml

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Replaces TestWarnIgnoredFullMessages, which called the warning directly,
with a test of the renderer and report functions Run calls.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
@codecov

codecov Bot commented Nov 19, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.15116% with 54 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.72%. Comparing base (cd703a0) to head (5a052e0).
⚠️ Report is 23 commits behind head on main.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant