Adding a propsal for changing the KRO instance and resource labels #639

barney-s · 2025-08-18T23:57:14Z

Related PR that triggered this doc: #631

jakobmoellerdev

Mostly LGTM. Just thinking we should really start unifying everything and not keep the old labels.

docs/design/proposals/labels.md

fabianburth

Looks good!

docs/design/proposals/labels.md

- Based on proposal: kubernetes-sigs#639 - Move to new labels and remove old labels - Add new testcase for nested RGD and update existing testcase labels - Have separate instance labellers for different reconcile paths. This is needed when we have RGD2 instance in RGD1 resources. Today both paths use the same label resulting in conflict. path 1: RGD2.instance created as part of an RGD1 instance reconciliation path 2: RGD2.instance reconciled by RGD2 reconciler

- Based on proposal: kubernetes-sigs#639 - Move to new labels - Add deprecate TODO for old labels - Add new testcase for nested RGD and update existing testcase labels - Have separate instance labellers for different reconcile paths. This is needed when we have RGD2 instance in RGD1 resources. Today both paths use the same label resulting in conflict. path 1: RGD2.instance created as part of an RGD1 instance reconciliation path 2: RGD2.instance reconciled by RGD2 reconciler

- Based on proposal: kubernetes-sigs#639 - Move to new labels - Add deprecate TODO for old labels - Add new testcase for nested RGD and update existing testcase labels - Add docs - Have separate instance labellers for different reconcile paths. This is needed when we have RGD2 instance in RGD1 resources. Today both paths use the same label resulting in conflict. path 1: RGD2.instance created as part of an RGD1 instance reconciliation path 2: RGD2.instance reconciled by RGD2 reconciler

jakobmoellerdev · 2025-08-30T10:46:45Z

docs/design/proposals/labels.md

+      - `kro.run/reconciled-by-rgd`
+    - **Value:** The name of the ResourceGraphDefinition (e.g., `my-rgd-name`).
+    - **Purpose:** To indicate that an instance is being actively reconciled against a specific RGD. This label will be applied to the instance itself.
+    - **Alternative Names:**


are these alternative names set too or are these just suggestions? I would prefer to limit us to one.

jakobmoellerdev · 2025-08-30T10:47:17Z

docs/design/proposals/labels.md

+    - **Purpose:** To identify which RGD was used as a template to create a resource during the reconciliation of an instance. This label will be applied to all resources created by the instance controller.
+    - **Alternative Names:**
+      - kro.run/created-by-rgd
+      - kro.run/managed-by-rgd


I think managed-by probably fits best since we continuously work on it

I think if we have kro.run/managed-by-rgd it could be reused for the instance too. Is there a specific need to have two labels here?

jakobmoellerdev · 2025-08-30T10:49:09Z

docs/design/proposals/labels.md

+      - kro.run/instance-namespace: default
+    - **Proposed Labels:**
+      - `kro.run/managed-by-instance-group`: The API group of the instance (e.g., `mygroup.example.com`).
+      - `kro.run/managed-by-instance-kind`: The kind of the instance (e.g., `MyKind`).


if you define a group+kind, don't you also need to define a version?

How about:

kro.run/instance: production/my-web-app # namespace/name format kro.run/instance-gvk: myapp.io/v1/WebService # optional for additional context ?

another approach would be to just include an RGD ref?

jakobmoellerdev · 2025-08-30T10:50:26Z

docs/design/proposals/labels.md

+      - `kro.run/owner-`
+      - `kro.run/created-by-`
+
+## Other solutions considered


Im wondering if it doesn't make sense to reuse the kubernetes labels or at least co-apply them. Im sure you thought about this too so it would be good to have a thought about this in the proposal

+1 here i would love for us to adopt k8s standard labels. at least the app.kuberentes.io/managed-by and app.kubernets.io/part-of

k8s-triage-robot · 2025-09-12T20:27:39Z

Unknown CLA label state. Rechecking for CLA labels.

Send feedback to sig-contributor-experience at kubernetes/community.

/check-cla
/easycla

a-hilaly

Thanks for putting this together @barney-s ! you've identified an important issue - the current labeling scheme is definitely confusing with both resource-graph-definition-id and resource-graph-definition-name without clear semantics.

a-hilaly · 2025-09-14T07:44:57Z

docs/design/proposals/labels.md

+
+1.  **Label for an instance being reconciled:**
+    - **Existing Labels:**
+      - kro.run/resource-graph-definition-id: 761e8fb7-14d5-4da1-b4f9-0a16fc334d6c


I wanted to add some context about why I originally introduced the RGD ID label. The goal was to help the controller detect when RGDs are deleted and recreated, which creates completely new RGDs and can trigger unwanted cleanup. I was thinking we could have an RGD annotation like kro.run/allow-recreation (or maybe kro.run/allow-rgd-replacement?) that users would need to explicitly set. Without this annotation, kro would reject the recreation as a conflict to prevent accidental data loss. cc @matthchr @jakobmoellerdev @n3wscott

This might influence how we think about the labeling scheme - we still need some way to track RGD identity beyond just the name. but i fully agree the current implementation could be clearer

I think the Kubernetes UID field is sufficient for this purpose because it is effectively an ID that gets recreated when the object is recreated. Any specific reason why you would want to roll your own?

a-hilaly · 2025-09-14T07:48:01Z

docs/design/proposals/labels.md

+      - kro.run/instance-namespace: default
+    - **Proposed Labels:**
+      - `kro.run/managed-by-instance-group`: The API group of the instance (e.g., `mygroup.example.com`).
+      - `kro.run/managed-by-instance-kind`: The kind of the instance (e.g., `MyKind`).


How about:

kro.run/instance: production/my-web-app # namespace/name format kro.run/instance-gvk: myapp.io/v1/WebService # optional for additional context ?

a-hilaly · 2025-09-14T07:48:55Z

docs/design/proposals/labels.md

+      - kro.run/instance-namespace: default
+    - **Proposed Labels:**
+      - `kro.run/managed-by-instance-group`: The API group of the instance (e.g., `mygroup.example.com`).
+      - `kro.run/managed-by-instance-kind`: The kind of the instance (e.g., `MyKind`).


another approach would be to just include an RGD ref?

a-hilaly · 2025-09-14T07:50:04Z

docs/design/proposals/labels.md

+      - `kro.run/owner-`
+      - `kro.run/created-by-`
+
+## Other solutions considered


+1 here i would love for us to adopt k8s standard labels. at least the app.kuberentes.io/managed-by and app.kubernets.io/part-of

a-hilaly · 2025-09-14T08:07:16Z

docs/design/proposals/labels.md

+
+This aligns with the common Kubernetes practice of using labels for discovery and organization of related resources, as seen in tools like Helm and Kustomize.
+
+#### Design details


should we have a section addressing deeply nested RGDs (3+ levels)? thinking what happens when RGD1 creates an RGD2 instance, which creates an RGD3 instance, which creates an RGD4 instance ? With the two label scheme, we lose the intermediate relationships e.g an RGD4 instance would only show it was defined by RGD3 and controlled by RGD4, with no trace of RGD1 or RGD2. this means queries like "show me all resources that originated from RGD1, including those created indirectly through nested RGDs" won't be possible - which is fine, but worth noting.

We could get around this by having a root RGD, although this starts to get reaaaally complicated by then :D

- Based on proposal: kubernetes-sigs#639 - Move to new labels - Add deprecate TODO for old labels - Add new testcase for nested RGD and update existing testcase labels - Add docs - Have separate instance labellers for different reconcile paths. This is needed when we have RGD2 instance in RGD1 resources. Today both paths use the same label resulting in conflict. path 1: RGD2.instance created as part of an RGD1 instance reconciliation path 2: RGD2.instance reconciled by RGD2 reconciler

Adding a propsal for changing the KRO instance and resource labels

e08ef60

barney-s requested review from matthchr and a-hilaly August 19, 2025 16:13

barney-s mentioned this pull request Aug 19, 2025

Change KRO labels #631

Open

jakobmoellerdev reviewed Aug 20, 2025

View reviewed changes

docs/design/proposals/labels.md Outdated Show resolved Hide resolved

docs/design/proposals/labels.md Outdated Show resolved Hide resolved

fabianburth reviewed Aug 20, 2025

View reviewed changes

docs/design/proposals/labels.md Outdated Show resolved Hide resolved

barney-s added this to the 0.5 milestone Aug 20, 2025

Addressing review comments

c6397ab

barney-s force-pushed the labels-proposal branch from b2f9271 to c6397ab Compare August 21, 2025 17:33

barney-s requested review from jakobmoellerdev and fabianburth August 25, 2025 17:49

jakobmoellerdev reviewed Aug 30, 2025

View reviewed changes

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Sep 12, 2025

a-hilaly reviewed Sep 14, 2025

View reviewed changes


		This aligns with the common Kubernetes practice of using labels for discovery and organization of related resources, as seen in tools like Helm and Kustomize.

		#### Design details

Adding a propsal for changing the KRO instance and resource labels #639

Are you sure you want to change the base?

Adding a propsal for changing the KRO instance and resource labels #639

Conversation

barney-s commented Aug 18, 2025

Uh oh!

jakobmoellerdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

fabianburth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k8s-triage-robot commented Sep 12, 2025

Uh oh!

a-hilaly left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!