Say a resource was kept in a condition, not a warning every reconcile

When a value a resource is built from goes missing and the scope keeps
the resource's current spec, it said so in a warning result. That's
right the first time, but it repeats on every reconcile for as long as
the value is missing - through a whole cluster teardown, say - and each
one is a Warning event on the XR.

composing now reports on an XR condition, DependencyValuesAvailable:
False with reason KeptCurrentSpec while any resource was kept, naming
each and the value it's waiting for, and True otherwise. Every scope
reports, so the condition is returned on every reconcile: Crossplane
keeps a condition a function set earlier until it's set again, so one
returned only while False would never clear. Scopes in one function
share it, and one with nothing kept doesn't turn another's False back
to True.

The message is built from resource names and field paths only, so it
holds still while the situation does, and Crossplane leaves an
unchanged condition alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: stevendborrelli

crossplane/function/dependency.py

@@ -66,6 +66,13 @@
 _EXTERNAL_NAME = "@externalName"
 _EXTERNAL_NAME_ANNOTATION = "crossplane.io/external-name"
 
+CONDITION_TYPE = "DependencyValuesAvailable"
+"""The XR condition composing reports whether any resource was kept.
+
+False while a resource was kept at its current spec because a value it's
+built from isn't available, naming each one. True otherwise.
+"""
+
 _COMPOSED = "composed"
 _REQUIRED = "required"
 
@@ -373,6 +380,7 @@ def __init__(
         self.name = name
         self._sources: set[_Source] = set()
         self._unresolved: list[str] = []
+        self._kept = False
 
     def ref(self, value: V) -> V:
         """Read a field of a named resource, and depend on that resource.
@@ -488,14 +496,17 @@ def _close(self) -> None:
         if self.name in self.rsp.desired.resources or exists:
             _record(self.rsp, self.name, self._sources)
 
+        _report(self.rsp, self.name, self._unresolved if self._kept else [])
+
     def _keep_current_spec(self) -> None:
         """Keep an existing resource's spec while a reference it needs is gone.
 
         The fields that refer to what's missing came back None and were left
         out, and applying that would unset them. A function that didn't
         compose the resource at all, because the value it needed wasn't
         there, would have it deleted. Either way, keep what the resource
-        already has for anything this function doesn't set, and say so.
+        already has for anything this function doesn't set, and say so in
+        the CONDITION_TYPE condition.
         """
         observed = resource.struct_to_dict(
             self.req.observed.resources[self.name].resource
@@ -517,12 +528,39 @@ def _keep_current_spec(self) -> None:
                 body["spec"] = observed["spec"]
             resource.update(self.rsp.desired.resources[self.name], body)
 
-        response.warning(
-            self.rsp,
-            f"{self.name}: kept its current spec, because "
-            f"{', '.join(self._unresolved)} isn't available",
+        self._kept = True
+
+
+def _report(rsp: fnv1.RunFunctionResponse, name: str, missing: list[str]) -> None:
+    """Report on CONDITION_TYPE for one scope.
+
+    Every scope reports, so the condition is always returned: Crossplane
+    keeps a condition a function set earlier until the function sets it
+    again, so one returned only while something was kept would stay False
+    after it recovered. Scopes in one function share the condition, which
+    turns False on the first that kept its resource and names each.
+
+    The message is built from resource names and field paths only, so it
+    holds still while the situation does. Crossplane then leaves the
+    condition alone, where a result would be an event every reconcile.
+    """
+    c = next((c for c in rsp.conditions if c.type == CONDITION_TYPE), None)
+    if c is None:
+        c = rsp.conditions.add(
+            type=CONDITION_TYPE, status=fnv1.STATUS_CONDITION_TRUE, reason="Available"
         )
 
+    if not missing:
+        return
+
+    line = f"{name} kept its current spec: {', '.join(missing)} isn't available"
+    if c.status == fnv1.STATUS_CONDITION_TRUE:
+        c.status = fnv1.STATUS_CONDITION_FALSE
+        c.reason = "KeptCurrentSpec"
+        c.message = line
+    else:
+        c.message = f"{c.message}; {line}"
+
 
 def _without_none(v: typing.Any) -> typing.Any:
     """Return v with every None value left out, recursing into dicts and lists."""
@@ -573,15 +611,15 @@ def composing(
     The dependencies are recorded when the block exits, so an exception
     inside it records nothing.
 
-    A value that isn't available yet comes back as None, and the field is
-    left out: when the block exits, None fields are removed from the resource
+    A value that isn't available yet comes back as None, and the field is left
+    out: when the block exits, None fields are removed from the resource
     however it was written, because sending one would clear the field. If the
     resource doesn't exist yet that's what ordering is for: Crossplane waits
-    for the dependency before creating it. If it does exist,
-    it keeps its current spec for the fields that were left out, and the
-    response carries a warning saying why. That holds even if the block
-    doesn't compose the resource at all because the value it needed is
-    missing: an existing resource is kept rather than deleted.
+    for the dependency before creating it. If it does exist, it keeps its
+    current spec for the fields that were left out, and the XR's
+    DependencyValuesAvailable condition turns False, saying why. That holds
+    even if the block doesn't compose the resource at all because the value it
+    needed is missing: an existing resource is kept rather than deleted.
 
     Dependencies are declared only for a resource that's composed or already
     exists. A block that composes nothing declares nothing.

tests/test_dependency.py

@@ -110,6 +110,18 @@ def edges(rsp: fnv1.RunFunctionResponse) -> list[dict]:
     ]
 
 
+def conditions(rsp: fnv1.RunFunctionResponse) -> list[dict]:
+    return [
+        json_format.MessageToDict(c, preserving_proto_field_name=True)
+        for c in rsp.conditions
+    ]
+
+
+def kept(name: str) -> str:
+    """The condition message for a resource kept while the VPC's id is missing."""
+    return f"{name} kept its current spec: vpc.status.atProvider.id isn't available"
+
+
 def body(rsp: fnv1.RunFunctionResponse, name: str) -> dict:
     return resource.struct_to_dict(rsp.desired.resources[name].resource)
 
@@ -331,9 +343,67 @@ def test_existing_resource_keeps_its_spec(self) -> None:
             body(rsp, "subnet")["spec"]["forProvider"],
             {"region": "us-west-2", "vpcId": "vpc-0123"},
         )
-        self.assertEqual(len(rsp.results), 1)
-        self.assertEqual(rsp.results[0].severity, fnv1.SEVERITY_WARNING)
-        self.assertIn("vpc.status.atProvider.id", rsp.results[0].message)
+        self.assertEqual(rsp.results, [])
+        self.assertEqual(
+            conditions(rsp),
+            [
+                {
+                    "type": "DependencyValuesAvailable",
+                    "status": "STATUS_CONDITION_FALSE",
+                    "reason": "KeptCurrentSpec",
+                    "message": kept("subnet"),
+                }
+            ],
+        )
+
+    def test_condition_is_true_when_nothing_is_kept(self) -> None:
+        # Returned even so: Crossplane keeps a condition a function set
+        # earlier, so one only returned while False would never clear.
+        req = fnv1.RunFunctionRequest(meta=ORDERED)
+        rsp = response.to(req)
+        with dependency.composing(req, rsp, "subnet") as c:
+            c.ref(dependency.named("vpc", VPC).status.atProvider.id)
+
+        self.assertEqual(
+            conditions(rsp),
+            [
+                {
+                    "type": "DependencyValuesAvailable",
+                    "status": "STATUS_CONDITION_TRUE",
+                    "reason": "Available",
+                }
+            ],
+        )
+
+    def test_condition_names_every_kept_resource(self) -> None:
+        existing = {
+            "spec": {"forProvider": {"region": "us-east-1", "vpcId": "vpc-0123"}}
+        }
+        req = fnv1.RunFunctionRequest(
+            meta=ORDERED, observed=observed(a=existing, b=existing, c=VPC_OBSERVED)
+        )
+        rsp = response.to(req)
+        vpc = dependency.named("vpc", VPC)
+
+        # A kept resource, one that's fine, then another kept one: the one
+        # that's fine mustn't turn the condition back to True.
+        for name in ("a", "c", "b"):
+            with dependency.composing(req, rsp, name) as c:
+                if name == "c":
+                    continue
+                c.ref(vpc.status.atProvider.id)
+
+        self.assertEqual(
+            conditions(rsp),
+            [
+                {
+                    "type": "DependencyValuesAvailable",
+                    "status": "STATUS_CONDITION_FALSE",
+                    "reason": "KeptCurrentSpec",
+                    "message": f"{kept('a')}; {kept('b')}",
+                }
+            ],
+        )
 
     def test_composing_nothing_declares_nothing(self) -> None:
         req = fnv1.RunFunctionRequest(meta=ORDERED)
@@ -379,7 +449,7 @@ def test_existing_resource_not_composed_is_kept(self) -> None:
         self.assertEqual(
             edges(rsp), [{"resource": "subnet", "composed_resource": "vpc"}]
         )
-        self.assertEqual(rsp.results[0].severity, fnv1.SEVERITY_WARNING)
+        self.assertEqual(conditions(rsp)[0]["reason"], "KeptCurrentSpec")
 
     def test_without_capability_holds_back_by_omission(self) -> None:
         req = fnv1.RunFunctionRequest(meta=UNORDERED)