observe-kro

observe-kro

The controller-specific observer skill for kro (Kubernetes Resource Orchestrator) — the project at kro-run/kro. cub-scout classifies kro-managed resources via labels, annotations, and owner-reference chains, and recognizes three distinct kro writer identities in metadata.managedFields.

Verified against pkg/agent/ownership.go detectKroOwnership and pkg/agent/manager_strings.go kro constants.

When to use

• "Is this a kro instance?"
• "Which ResourceGraphDefinition produced deploy/api?"
• "Show me kro applyset writes"
• "What does the kro.run/applyset manager string mean?"
• "Trace this resource back to the kro instance"
• "Distinguish a kro Instance from a kro ResourceGraphDefinition"

Do not load for

• Generic ownership detection — scout-observe
• Crossplane (similar composition concept, completely different writers) — observe-crossplane
• Argo / Flux / Helm — their specific skills
• Authoring kro CRDs (writing ResourceGraphDefinitions) — out of cub-scout scope

Detection signals (in detectKroOwnership)

cub-scout walks three signal sources in order; the first hit wins:

Pass	Signal	SubType	Confidence	Notes
1	Any label key starting with kro.run/ with a non-empty value	instance	high	Most common path — kro writes its instance identity into labels. The first matching label's value populates Name.
2	Any annotation key starting with kro.run/ with a non-empty value	instance	high	Fallback for resources where the identity is in annotations rather than labels.
3	ownerReferences[].apiVersion matches a kro API group	instance or definition	high	The owner-reference fallback for kro-generated children. definition when the owner kind is ResourceGraphDefinition.
4	Resource's own apiVersion matches a kro API group	instance or definition	high	Catches the ResourceGraphDefinition / Instance CRDs themselves when they have no labels or owner-refs to walk.

The kro API group recognition is in isKroAPIVersion (in ownership.go) — recognizes the kro.run group family.

Manager strings (writers in metadata.managedFields)

Three distinct writers, all qualified with kro.run/:

Manager	Source	Reconciles
kro.run/applyset	kro-run/kro applyset.FieldManager	Applyset-managed child resources — the bulk of kro writes
kro.run/applyset-parent	kro-run/kro applyset.FieldManager + "-parent"	Applyset metadata on the parent Instance
kro.run/labeller	kro-run/kro FieldManagerForLabeler	Finalizer/label SSA writes on Instances

controllerManagersForOwner(OwnerKro, ...) returns all three matchers as exact strings.

Applyset semantics

kro uses Kubernetes' applyset feature to track which resources belong to a logical group. The kro.run/applyset manager identifies writes to the managed children of an applyset; kro.run/applyset-parent identifies writes to the applyset parent metadata on the Instance.

Operationally:

• kro reads a ResourceGraphDefinition (the recipe — kinds, dependencies, transforms)
• kro instantiates it as an Instance (or a CRD it generates from the RGD)
• kro applyset-controller produces and reconciles the child resources, writing kro.run/applyset to their managedFields
• kro labeller writes finalizers + applyset labels on the Instance via kro.run/labeller

Worked example

$ kubectl get deploy api -n prod -o yaml | yq '.metadata.labels, .metadata.ownerReferences, .metadata.managedFields[].manager'
labels:
  kro.run/instance: payments-platform
  kro.run/applyset-id: applyset-7m4k9
ownerReferences:
  - apiVersion: kro.run/v1alpha1
    kind: PaymentsPlatform                                # generated by an RGD
    name: payments-platform
managers:
  - kro.run/applyset

cub-scout reads this as:

$ cub-scout explain deploy/api -n prod
Resource: Deployment/api in prod
  Owner:    kro instance "payments-platform" (label:kro.run/instance)
  Drift:    None detected
  Mutation cause: controller-drift (manager: kro.run/applyset)

When the labels are missing

If the labels were stripped (older kro, custom admission webhook, etc.), cub-scout falls back to ownerReferences:

$ kubectl get deploy api -n prod -o yaml | yq '.metadata.ownerReferences, .metadata.managedFields[].manager'
ownerReferences:
  - apiVersion: kro.run/v1alpha1
    kind: PaymentsPlatform
    name: payments-platform
managers:
  - kro.run/applyset

Same classification: OwnerKro instance=payments-platform. Pass 3 (ownerReferences) catches it.

Edge cases

• ResourceGraphDefinition itself: When the RGD is the resource being observed (not an instance), Pass 4 catches it via apiVersion matching the kro group, with SubType=definition. The RGD is OwnerKro even though it has no kro labels of its own.
• Multiple kro labels: A resource can have several kro.run/* labels (instance ID, applyset ID, etc.). Pass 1 picks the FIRST matching label by Go map iteration order, which is non-deterministic. The Name populated may differ across cluster reads, but the Type=kro classification is stable. This is a known limitation; see #427-adjacent discussion.
• Empty-value labels: A kro.run/foo: "" label is skipped (Pass 1 explicitly requires value != ""); the next signal source is tried. Prevents cub-scout from labelling resources with stray empty kro annotations.
• Cross-controller composition: kro + Crossplane / kro + Flux is possible. Ownership detection precedence is Flux -> Argo -> Sveltos -> Modelplane -> Helm -> Terraform -> ConfigHub -> Crossplane -> kro -> Custom -> K8s native. kro runs LATE in the chain, so if Flux labels are also present, the resource classifies as OwnerFlux and kro is invisible to the ownership detector.
• Generated CRDs: kro can generate new CRDs from an RGD (e.g., the PaymentsPlatform kind in the example). Resources of those generated kinds are still classifiable — the generated owner-reference apiVersion matches the kro group.

References

• Code: pkg/agent/ownership.go detectKroOwnership + isKroAPIVersion, pkg/agent/manager_strings.go ManagerKroApplyset / ManagerKroApplysetParent / ManagerKroLabeller
• Upstream:
  • Applyset field manager: kro-run/kro applyset.FieldManager
  • Labeller field manager: kro-run/kro FieldManagerForLabeler
  • Applyset spec: Kubernetes applyset KEP
• Related skills: scout-observe, scout-attribute, observe-crossplane (similar composition pattern, different writers)
• Examples: kro composition layout in examples/kro-composition/

Constraints

• This skill is read-only. kro Instance creation / RGD mutation are out of allowed-tools.
• kro ownership precedence runs AFTER Flux / Argo / Helm / Terraform / ConfigHub / Crossplane. Resources with any of those labels classify under those owners, not kro, even if kro is also writing.
• Pass-1 label iteration is non-deterministic when multiple kro labels are present. The Type classification is stable; the Name field may vary.