Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
44de08a
feat(health): classify a live object's health from its conditions
jcogilvie Nov 18, 2026
09ffe08
feat(diff): carry live health on XR diff groups and impacts
jcogilvie Nov 18, 2026
cef0b34
feat(simulate): report live health in the structured result
jcogilvie Nov 18, 2026
c5abee5
fix(diff): read a claim's health from its backing XR and list nested …
jcogilvie Nov 18, 2026
d3deddc
feat(simulate): name the via of nested unhealthy resources and nest s…
jcogilvie Nov 18, 2026
4d13757
test(health): use args tables in the classifier tests
jcogilvie Nov 18, 2026
ffc70db
docs(simulate): reflow the MarshalJSON comment
jcogilvie Nov 18, 2026
601f356
test(project): expect healthy composites in project simulate JSON
jcogilvie Nov 18, 2026
2ef6498
test(project): expect healthy composites in project plan output JSON
jcogilvie Nov 18, 2026
4ce9bb1
docs(simulate): use contractions in the output help
jcogilvie Nov 19, 2026
a1a5d40
fix(simulate): list a nested composite's health on its own entry
jcogilvie Nov 19, 2026
50e8fad
feat(simulate): mark unhealthy resources in plan output
jcogilvie Nov 18, 2026
f06445c
feat(diff): mark unhealthy resources in diff output
jcogilvie Nov 18, 2026
5762950
feat(simulate): exit with bit 4 when a resource is failing
jcogilvie Nov 18, 2026
0239935
test(simulate): cover unhealthy XRs in xr, composition and project in…
jcogilvie Nov 18, 2026
86ed91d
test(simulate): apply the paused annotation under a user field manager
jcogilvie Nov 18, 2026
63b411e
fix(diff): print an unhealthy XR's message once in diff output
jcogilvie Nov 18, 2026
71b214f
refactor(health): name a health's tier without parsing its line
jcogilvie Nov 18, 2026
04878ef
docs(simulate): contract 'that is' in the exit help
jcogilvie Nov 19, 2026
693cc46
fix(diff): list a nested XR's unhealthy resources once in composition…
jcogilvie Nov 19, 2026
79ac845
fix(diff): count only XRs with health in the diff Health: line
jcogilvie Nov 19, 2026
bd96340
feat(resource): carry the live resource's health on each plan
jcogilvie Nov 19, 2026
939fae6
feat(resource): mark unhealthy resources in resource simulate output
jcogilvie Nov 19, 2026
aa8f424
feat(resource): exit with bit 4 when a managed resource is failing
jcogilvie Nov 19, 2026
5d86795
docs(resource): document health output and exit codes 4 and 7
jcogilvie Nov 19, 2026
af11efe
feat(resource): warn that --full-messages has no effect with -o json|…
jcogilvie Nov 19, 2026
3cc6e72
refactor(resource): split rendering and exit status out of Run
jcogilvie Nov 19, 2026
b085ded
test(resource): cover the renderer, warning and exit status Run uses
jcogilvie Nov 19, 2026
4fe52b8
test(resource): check summary.health in YAML output
jcogilvie Nov 19, 2026
5a052e0
docs(resource): say the health line prints under the resource header
jcogilvie Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions cmd/crossplane/composition/integration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,80 @@ Summary: 2 modified`,
WithDownstreamSummary(0, 0, 1).
WithDownstreamResource("removed", "XDownstreamResource", "resource-to-be-removed", "default"),
},
"UnhealthyXRWithChangesExits7": {
Reason: "A composition change on a failing XR prints the XR's health and its not-ready composed resource's in the impact analysis, then the Health: line, and exits 7: changes (3) and failing (4).",
SetupFiles: []string{
"../../../internal/testutils/integration/testdata/comp/resources/xrd.yaml",
"../../../internal/testutils/integration/testdata/comp/resources/original-composition.yaml",
"../../../internal/testutils/integration/testdata/comp/resources/functions.yaml",
},
CrossplaneManagedResources: []integration.HierarchicalOwnershipRelation{
integration.Composes(
"../../../internal/testutils/integration/testdata/comp/resources/existing-xr-1-failing.yaml",
"../../../internal/testutils/integration/testdata/comp/resources/existing-downstream-1-not-ready.yaml",
),
},
InputFiles: []string{"../../../internal/testutils/integration/testdata/comp/updated-composition.yaml"},
Namespace: "default",
NoColor: true,
ExpectedOutput: `
=== Affected Composite Resources ===

⚠ XNopResource/test-resource (namespace: default) ⚠ failing (Synced=False, ReconcileError): cannot compose resources: the vpc does not exist

Summary: 1 resource with changes

=== Impact Analysis ===

~~~ XDownstreamResource/test-resource ⚠ not ready (Ready=False, Creating)
apiVersion: ns.nop.example.org/v1alpha1
kind: XDownstreamResource
metadata:
annotations:
crossplane.io/composition-resource-name: nop-resource
labels:
crossplane.io/composite: test-resource
name: test-resource
namespace: default
spec:
forProvider:
- configData: existing-value
- resourceTier: basic
+ configData: updated-existing-value
+ resourceTier: premium

---

Summary: 1 modified

Health: 1 of 1 XR unhealthy before apply; 1 resource not ready.`,
ExpectedExitCode: dp.ExitCodeDiffDetected | dp.ExitCodeFailing,
},
"UnhealthyXRWithoutChangesExits4": {
Reason: "An unchanged composition analysed on a failing XR reports its health in -o json and exits 4: failing, no changes.",
SetupFiles: []string{
"../../../internal/testutils/integration/testdata/comp/resources/xrd.yaml",
"../../../internal/testutils/integration/testdata/comp/resources/original-composition.yaml",
"../../../internal/testutils/integration/testdata/comp/resources/functions.yaml",
},
CrossplaneManagedResources: []integration.HierarchicalOwnershipRelation{
integration.Composes(
"../../../internal/testutils/integration/testdata/comp/resources/existing-xr-1-failing.yaml",
"../../../internal/testutils/integration/testdata/comp/resources/existing-downstream-1-not-ready.yaml",
),
},
InputFiles: []string{"testdata/comp/composition-no-changes.yaml"},
Namespace: "default",
AnalyzeUnchanged: true,
OutputFormat: "json",
ExpectedExitCode: dp.ExitCodeFailing,
ExpectedStructured: simtest.Expect().
WithHealthSummary(1, 0, 1, 0).
WithXRs(simtest.XR("XNopResource", "test-resource", "default").
Status("unchanged").
Health("failing").
Unhealthy("XDownstreamResource", "test-resource", "notReady")),
},
"CompositionDiffIgnorePaths": {
Reason: "Validates that ArgoCD annotations are ignored in composition diffs",
SetupFiles: []string{
Expand Down
106 changes: 100 additions & 6 deletions cmd/crossplane/project/integration_plan_output_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,13 @@ import (
"testing"

"github.com/google/go-cmp/cmp"
corev1 "k8s.io/api/core/v1"
un "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
"sigs.k8s.io/controller-runtime/pkg/client"

dp "github.com/crossplane/cli/v2/internal/diff/diffprocessor"
"github.com/crossplane/cli/v2/internal/exitcode"
"github.com/crossplane/cli/v2/internal/health"
"github.com/crossplane/cli/v2/internal/plan"
"github.com/crossplane/cli/v2/internal/simulate"
"github.com/crossplane/cli/v2/internal/testutils/integration"
Expand Down Expand Up @@ -73,6 +75,20 @@ func TestSimulatePlanOutput(t *testing.T) {
another := xnop
another.Name = "another-resource"
comp := plan.ResourceRef{APIVersion: "apiextensions.crossplane.io/v1", Kind: "Composition", Name: "xnopresources.diff.example.org"}
// healthy is a live composite's health with no failing condition.
healthy := &health.Health{State: health.Healthy}

// unhealthyCase is compCase with test-resource failing (Synced=False) and
// its composed resource not ready (Ready=False), and the composed resource
// of another-resource paused.
unhealthyCase := compCase
unhealthyCase.CrossplaneManagedResources = []integration.HierarchicalOwnershipRelation{
integration.Composes("../../../internal/testutils/integration/testdata/comp/resources/existing-xr-1-failing.yaml", "../../../internal/testutils/integration/testdata/comp/resources/existing-downstream-1-not-ready.yaml"),
integration.Composes("../../../internal/testutils/integration/testdata/comp/resources/existing-xr-2.yaml", "../../../internal/testutils/integration/testdata/comp/resources/existing-downstream-2.yaml"),
}
unhealthyCase.FieldManagerApplies = []integration.FieldManagerApply{
{File: "../../../internal/testutils/integration/testdata/comp/resources/existing-downstream-2-paused-annotation.yaml", FieldManager: "kubectl"},
}

xrArgs := []string{"-f", "../../../internal/testutils/integration/testdata/diff/modified-xr.yaml"}
compArgs := []string{"-f", "../../../internal/testutils/integration/testdata/comp/updated-composition.yaml", "--namespace=default"}
Expand All @@ -86,6 +102,11 @@ func TestSimulatePlanOutput(t *testing.T) {
// tt, when set, runs `xr simulate` with args against its cluster
// instead of compCase's.
tt *integration.Setup
// cluster, when set, replaces compCase's cluster for a project or
// composition run.
cluster *integration.Setup
// wantExitCode is the exit code; zero means dp.ExitCodeDiffDetected.
wantExitCode int
// wantText is the -o plan output; empty for a json case.
wantText string
// wantResult is the -o json output, reduced by summarize.
Expand Down Expand Up @@ -140,7 +161,7 @@ Note: Provider plan not run: no provider diff server planned these resources.
args: append([]string{"-o", "json"}, xrArgs...),
wantResult: &planShape{
Summary: plan.Summary{Update: 2},
Composites: []simulate.CompositeResult{{Ref: xnop, Status: simulate.CompositeChanged}},
Composites: []simulate.CompositeResult{{Ref: xnop, Status: simulate.CompositeChanged, Health: healthy}},
Plans: []planEntry{
{Kind: "XDownstreamResource", Name: "test-resource", Action: plan.ActionUpdate, Composite: "test-resource"},
{Kind: "XNopResource", Name: "test-resource", Action: plan.ActionUpdate, Composite: "test-resource"},
Expand Down Expand Up @@ -184,7 +205,7 @@ Note: Provider plan not run: no provider diff server planned these resources.
args: append([]string{"-o", "json"}, compArgs...),
wantResult: &planShape{
Summary: plan.Summary{Update: 3, NoOp: 2},
Composites: []simulate.CompositeResult{{Ref: another, Status: simulate.CompositeChanged, Composition: &comp}, {Ref: xnop, Status: simulate.CompositeChanged, Composition: &comp}},
Composites: []simulate.CompositeResult{{Ref: another, Status: simulate.CompositeChanged, Composition: &comp, Health: healthy}, {Ref: xnop, Status: simulate.CompositeChanged, Composition: &comp, Health: healthy}},
Compositions: []simulate.CompositionResult{{
Ref: comp,
RevisionImpact: &simulate.RevisionImpact{ChangeScope: "spec", CreatesRevision: true, RepointedComposites: 2},
Expand All @@ -198,12 +219,73 @@ Note: Provider plan not run: no provider diff server planned these resources.
},
},
},
"UnhealthyPlanText": {
reason: "-o plan marks the failing XR's header and its not-ready and paused composed resources' plan entries, prints the Health: line after Plan:, and exits 7: changes (3) and failing (4).",
cluster: &unhealthyCase,
wantExitCode: dp.ExitCodeDiffDetected | dp.ExitCodeFailing,
wantText: `[~] Composition.apiextensions.crossplane.io xnopresources.diff.example.org (update)
Applying this creates a new CompositionRevision, which 2 composites would adopt.
spec:
pipeline[0]:
input:
inline:
~ template: "apiVersion: ns.nop.example.org/v1alpha1\nkind: XDownstreamResource\nmetadata:\n name: {{ .observed.composite.resource.metadata.name }}\n namespace: {{ .observed.composite.resource.metadata.namespace }}\n annotations:\n gotemplating.fn.crossplane.io/composition-resource-name: nop-resource\nspec:\n forProvider:\n configData: {{ .observed.composite.resource.spec.coolField }}\n resourceTier: basic\n" -> "apiVersion: ns.nop.example.org/v1alpha1\nkind: XDownstreamResource\nmetadata:\n name: {{ .observed.composite.resource.metadata.name }}\n namespace: {{ .observed.composite.resource.metadata.namespace }}\n annotations:\n gotemplating.fn.crossplane.io/composition-resource-name: nop-resource\nspec:\n forProvider:\n configData: updated-{{ .observed.composite.resource.spec.coolField }}\n resourceTier: premium\n"

XR: XNopResource.ns.diff.example.org default/another-resource
[~] XDownstreamResource.ns.nop.example.org default/another-resource (update)
⚠ paused
spec:
forProvider:
~ configData: "another-existing-value" -> "updated-another-existing-value"
~ resourceTier: "basic" -> "premium"

XR: XNopResource.ns.diff.example.org default/test-resource ⚠ failing (Synced=False, ReconcileError): cannot compose resources: the vpc does not exist
[~] XDownstreamResource.ns.nop.example.org default/test-resource (update)
⚠ not ready (Ready=False, Creating)
spec:
forProvider:
~ configData: "existing-value" -> "updated-existing-value"
~ resourceTier: "basic" -> "premium"

Plan: 0 to add, 3 to change, 0 to destroy.
Health: 1 of 2 XRs unhealthy before apply; 1 resource not ready, 1 paused.

Note: Provider plan not run: no provider diff server planned these resources.
`,
},
"UnhealthyPlanJSON": {
reason: "-o json carries the failing XR's health and each unhealthy plan entry's, and exits 7.",
cluster: &unhealthyCase,
args: []string{"-o", "json"},
wantExitCode: dp.ExitCodeDiffDetected | dp.ExitCodeFailing,
wantResult: &planShape{
Summary: plan.Summary{Update: 3, NoOp: 2},
Composites: []simulate.CompositeResult{
{Ref: another, Status: simulate.CompositeChanged, Composition: &comp, Health: healthy},
{Ref: xnop, Status: simulate.CompositeChanged, Composition: &comp, Health: &health.Health{
State: health.Failing,
Synced: &health.Condition{Status: corev1.ConditionFalse, Reason: "ReconcileError", Message: "cannot compose resources: the vpc does not exist"},
}},
},
Compositions: []simulate.CompositionResult{{
Ref: comp,
RevisionImpact: &simulate.RevisionImpact{ChangeScope: "spec", CreatesRevision: true, RepointedComposites: 2},
}},
Plans: []planEntry{
{Kind: "Composition", Name: comp.Name, Action: plan.ActionUpdate},
{Kind: "XDownstreamResource", Name: "another-resource", Action: plan.ActionUpdate, Composite: "another-resource", Health: health.Paused},
{Kind: "XNopResource", Name: "another-resource", Action: plan.ActionNoOp, Composite: "another-resource"},
{Kind: "XDownstreamResource", Name: "test-resource", Action: plan.ActionUpdate, Composite: "test-resource", Health: health.NotReady},
{Kind: "XNopResource", Name: "test-resource", Action: plan.ActionNoOp, Composite: "test-resource", Health: health.Failing},
},
},
},
"NameRepeatedScopesToEach": {
reason: "repeated --name with --namespace scopes the run to each named composite, as the unscoped run covers both.",
args: []string{"-o", "json", "-n", "default", "--name=another-resource", "--name=test-resource"},
wantResult: &planShape{
Summary: plan.Summary{Update: 3, NoOp: 2},
Composites: []simulate.CompositeResult{{Ref: another, Status: simulate.CompositeChanged, Composition: &comp}, {Ref: xnop, Status: simulate.CompositeChanged, Composition: &comp}},
Composites: []simulate.CompositeResult{{Ref: another, Status: simulate.CompositeChanged, Composition: &comp, Health: healthy}, {Ref: xnop, Status: simulate.CompositeChanged, Composition: &comp, Health: healthy}},
Compositions: []simulate.CompositionResult{{
Ref: comp,
RevisionImpact: &simulate.RevisionImpact{ChangeScope: "spec", CreatesRevision: true, RepointedComposites: 2},
Expand All @@ -222,7 +304,7 @@ Note: Provider plan not run: no provider diff server planned these resources.
args: []string{"-o", "json", "--name=default/test-resource"},
wantResult: &planShape{
Summary: plan.Summary{Update: 2, NoOp: 1},
Composites: []simulate.CompositeResult{{Ref: xnop, Status: simulate.CompositeChanged, Composition: &comp}},
Composites: []simulate.CompositeResult{{Ref: xnop, Status: simulate.CompositeChanged, Composition: &comp, Health: healthy}},
Compositions: []simulate.CompositionResult{{
Ref: comp,
RevisionImpact: &simulate.RevisionImpact{ChangeScope: "spec", CreatesRevision: true, RepointedComposites: 1},
Expand All @@ -248,6 +330,9 @@ Note: Provider plan not run: no provider diff server planned these resources.
if tc.tt != nil {
setup = *tc.tt
}
if tc.cluster != nil {
setup = *tc.cluster
}
cfg := integration.Start(t, setup).Config

var stdout, stderr bytes.Buffer
Expand All @@ -262,8 +347,12 @@ Note: Provider plan not run: no provider diff server planned these resources.
if err != nil {
t.Fatalf("\n%s\nsimulate: unexpected error: %v\nstderr:\n%s", tc.reason, err, stderr.String())
}
if code != dp.ExitCodeDiffDetected {
t.Errorf("\n%s\nsimulate: want exit code %d, got %d", tc.reason, dp.ExitCodeDiffDetected, code)
wantCode := dp.ExitCodeDiffDetected
if tc.wantExitCode != 0 {
wantCode = tc.wantExitCode
}
if code != wantCode {
t.Errorf("\n%s\nsimulate: want exit code %d, got %d", tc.reason, wantCode, code)
}

if tc.wantResult == nil {
Expand Down Expand Up @@ -302,6 +391,8 @@ type planEntry struct {
Kind, Name string
Action plan.Action
Composite string
// Health is the live object's state when it is not healthy, else empty.
Health health.State
}

func summarize(r simulate.Result) planShape {
Expand All @@ -311,6 +402,9 @@ func summarize(r simulate.Result) planShape {
if p.Composite != nil {
e.Composite = p.Composite.Name
}
if p.Health.Unhealthy() {
e.Health = p.Health.State
}
s.Plans = append(s.Plans, e)
}
// The revision's predicted name is a hash of the Composition's content.
Expand Down
3 changes: 2 additions & 1 deletion cmd/crossplane/project/integration_project_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ import (
"github.com/google/go-cmp/cmp"

dp "github.com/crossplane/cli/v2/internal/diff/diffprocessor"
"github.com/crossplane/cli/v2/internal/health"
"github.com/crossplane/cli/v2/internal/plan"
"github.com/crossplane/cli/v2/internal/simulate"
"github.com/crossplane/cli/v2/internal/testutils/integration"
Expand Down Expand Up @@ -71,7 +72,7 @@ func TestProjectSimulateIntegration(t *testing.T) {
changed := func(refs ...plan.ResourceRef) []simulate.CompositeResult {
out := make([]simulate.CompositeResult, 0, len(refs))
for _, r := range refs {
out = append(out, simulate.CompositeResult{Ref: r, Status: simulate.CompositeChanged, Composition: &comp})
out = append(out, simulate.CompositeResult{Ref: r, Status: simulate.CompositeChanged, Composition: &comp, Health: &health.Health{State: health.Healthy}})
}
return out
}
Expand Down
38 changes: 34 additions & 4 deletions cmd/crossplane/simulate/help/simulate.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,13 +86,43 @@ Provider packages are cached in `--cache-dir`, which defaults to
`$CROSSPLANE_XPKG_CACHE` or the same xpkg cache directory as
`project simulate` and `render`.

The `-o` flag picks the output format:

- `plan`, the default, prints each resource's field-level plan, including
the resources it leaves unchanged. A resource whose live object isn't
healthy before apply gets a `⚠` line under its header: `failing` (its Synced
condition is False), `not ready` (its Ready condition is False) or `paused`
(it carries the `crossplane.io/paused: "true"` annotation, whatever its
conditions), with the condition's reason and message. A `Health:` line
after the `Plan:` line counts them, and is left out when every resource is
healthy. Messages are cut to one line; `--full-messages` prints them in
full, wrapped and indented.
- `json` and `yaml` print the same plans as a structured result, for CI and
other tools, with messages always in full. Each plan with a live object
carries its `health`: `health.state` is `failing`, `notReady`, `paused` or
`healthy`, with the `synced` and `ready` conditions it was read from. A
plan has no `health` when there is no live object, as for a create.
`summary.health` counts the resources that are `failing`, `notReady` or
`paused`; `unhealthyComposites` is always 0, since this command takes no
composite resources.

The command exits with one of these statuses, so a CI pipeline can gate on
the result:

- 0: the simulation found no changes.
- 0: the simulation succeeded and found no changes.
- 1: the simulation failed, including when any resource couldn't be planned
(its error is in the output).
- 3: the simulation found changes: a plan would create, update, destroy or
replace a resource.
- 80: the flags were invalid, so nothing was simulated.
- 3: the simulation succeeded and found changes: a plan would create,
update, destroy or replace a resource.
- 4: the simulation succeeded, found no changes, and a resource was failing
(Synced=False) before apply. A resource that's only not ready, or is
paused, doesn't set it.
- 7: the simulation succeeded, found changes, and a resource was failing:
3 and 4 combined.
- 80: a flag was unknown or had an invalid value, so nothing was simulated.
- 130: the simulation was interrupted.

An error wins over what the simulation found: 130 over 1, and either of them
over 3, 4 and 7. Without an error, the status adds 4 for a failing resource
to 3 for changes, so 3 and 7 both mean changes, and 4 and 7 both mean a
failing resource.
Loading
Loading