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

docs/design/proposals/labels.md

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?

ah thats the whole point of the proposal.
I guess the problem statement did not do a good job. Let me know how i can update the problem statement to make the need for 2 labels more apparent.

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?

what do you mean by RGD Ref ? in the ownerrefs ?

docs/design/proposals/labels.md

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.

docs/design/proposals/labels.md

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?

docs/design/proposals/labels.md

- 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

k8s-ci-robot · 2025-10-11T05:51:19Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: barney-s

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [barney-s]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

barney-s · 2025-10-11T07:07:35Z

@jakobmoellerdev @a-hilaly @matthchr - Please Take a look at this updated proposal.

jakobmoellerdev

For me this is looking good to go. Thanks a lot for the investment @barney-s !

tjamet · 2025-11-07T17:28:20Z

docs/design/proposals/labels.md

+
+## Problem statement
+
+The current labels in KRO are used to track ownership and metadata of resources managed by the orchestrator. While these labels provide essential information, they lack a clear and standardized way to represent the relationships between different KRO components, such as ResourceGraphDefinitions (RGDs), instances, and the resources they generate. This ambiguity can make it difficult to query for related objects and understand the provenance of resources within a cluster.


It would be interesting to remind about the current set of annotations/labels to better understand the problem and how it gets fixed

tjamet · 2025-11-07T17:45:35Z

docs/design/proposals/labels.md

+      - `kro.run/instance-gvk: mygroup.example.com/v1/MyKind`: The Group Version Kind (GVK) of the instance
+      - `kro.run/instance: default/my-instance`: The namespace and name of the instance.
+      - `app.kubernetes.io/instance: MyKind/default/my-instance`: Kind namespace and name of the instance


Labels are extremely useful to select resources kubectl -n my-namespace get X -l my=label and identify them in a human readable manner.

Given that we refer to 2 owning objects, would it make sense to rather use dns notation:

instance.kro.run/apiVersion: mygroup.example.com/v1 instance.kro.run/kind: MyKind instance.kro.run/name: my-instance instance.kro.run/namespace: my-namespace rgd.kro.run/name: some-rgd rgd.kro.run/apiVersion: kro.run/v1alpha1 app.kubernetes.io/instance: MyKind/default/my-instance

that way we can easily perform different queries kubectl -n my-namespace get X -l instance.kro.run/kind to get all namespaced resources deployed by a certain kind, kubectl -n my-namespace get -A X -l instance.kro.run/name=my-instance

tjamet · 2025-11-07T17:46:57Z

docs/design/proposals/labels.md

+    - 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.
+    - **Proposed Labels:**
+      - `kro.run/part-of: my-rgd-name` - The name of the ResourceGraphDefinition
+      - `app.kubernetes.io/part-of: my-rgd-name`


Do we really need both?

tjamet · 2025-11-07T17:51:30Z

docs/design/proposals/labels.md

+    - Currently we dont differentiate, it results in a conflict (https://github.com/kro-run/kro/pull/631)
+    - To indicate that an instance is being actively reconciled against a specific RGD. This label will be applied to the instance itself.
+    - **Proposed Labels:**
+      - `kro.run/managed-by-rgd: my-rgd-name` - name of the ResourceGraphDefinition that reconciles the instance.


What about

instance.kro.run/managed-by: my-rgd-name

Could it help reveal the hierarchy for humans?

tjamet · 2025-11-07T17:54:24Z

docs/design/proposals/labels.md

+## Other solutions considered
+
+1. We could continue using the existing labels, but their purpose is not as explicit for relationship tracking, which can lead to confusion for users and client tools.
+2. We could also use annotations, but labels are better suited for this purpose as they are queryable via the Kubernetes API, which is a key requirement for observability and tooling.


I would suggest 1 or 2 annotations for programmatic access that include IDs

for example

instance.kro.run/reference: {"apiVersion": "kro.run/v1alpha1", "kind": "MyKind", "resource": "mykinds", "namespace": "default", "name": "my-instance", "id": "$id"} rgd.kro.run/reference: {"apiVersion": "kro.run/v1", "name": "my-rgd", "id": "${id}"}

ID would help reconcilers detect that the instance (or RGD) was fully replaced between 2 reconciliation loops

tjamet · 2025-11-07T17:58:07Z

docs/design/proposals/labels.md

+-  Updating the instance controller to apply these labels to instances and created resources during reconciliation.
+-  Updating the official KRO documentation to reflect the new labels and their usage.
+-  Adding docs reflecting the new labels. Old labels would not be documented.
+-  Deprecate old labels in next minor release or the one after that.


isn't 1-2 versions a bit short?
Are we confident most users will upgrade to migrate all their labels?

tjamet · 2025-11-07T17:59:36Z

docs/design/proposals/labels.md

+#### Test plan
+
+-   **Unit tests:** Add unit tests for any new labeler functions in `pkg/metadata/labels.go` to ensure they construct the correct labels.
+-   **Integration tests:**


we may want a migration test, to ensure we don't mess up deployed objects with the new version.

We may also want to ensure that in case users jumps directly from the current labels layout to the proposed one (i.e. skip the transition versions) kro keeps running as expected

tjamet

overall looks good. i left some comments for discussion

k8s-ci-robot · 2025-11-14T00:26:09Z

@barney-s: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
presubmits-build-image	`642aef4`	link	true	`/test presubmits-build-image`
presubmits-integration-tests	`642aef4`	link	true	`/test presubmits-integration-tests`
presubmits-e2e-tests	`642aef4`	link	true	`/test presubmits-e2e-tests`
presubmits-verify-lint	`642aef4`	link	true	`/test presubmits-verify-lint`

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

barney-s requested review from a-hilaly and matthchr 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

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

barney-s requested review from fabianburth and jakobmoellerdev 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

barney-s force-pushed the labels-proposal branch from c6397ab to 08244bf Compare October 11, 2025 05:51

k8s-ci-robot added approved Indicates a PR has been approved by an approver from all required OWNERS files. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Oct 11, 2025

barney-s force-pushed the labels-proposal branch from 08244bf to 3a20f8c Compare October 11, 2025 06:27

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Oct 11, 2025

barney-s force-pushed the labels-proposal branch from 3a20f8c to 4ae5396 Compare October 11, 2025 06:58

k8s-ci-robot removed the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Oct 11, 2025

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Oct 11, 2025

barney-s force-pushed the labels-proposal branch from 4ae5396 to 16f7be0 Compare October 11, 2025 07:05

barney-s requested review from a-hilaly and jakobmoellerdev October 11, 2025 07:05

barney-s force-pushed the labels-proposal branch 2 times, most recently from 95048ee to 9c1b2a3 Compare October 12, 2025 00:03

Adding a propsal for changing the KRO instance and resource labels

642aef4

barney-s force-pushed the labels-proposal branch from 9c1b2a3 to 642aef4 Compare October 12, 2025 01:07

jakobmoellerdev reviewed Oct 16, 2025

View reviewed changes

a-hilaly modified the milestones: 0.5, 0.6 Oct 21, 2025

a-hilaly removed this from the 0.6 milestone Oct 29, 2025

tjamet reviewed Nov 7, 2025

View reviewed changes


		## Problem statement

		The current labels in KRO are used to track ownership and metadata of resources managed by the orchestrator. While these labels provide essential information, they lack a clear and standardized way to represent the relationships between different KRO components, such as ResourceGraphDefinitions (RGDs), instances, and the resources they generate. This ambiguity can make it difficult to query for related objects and understand the provenance of resources within a cluster.

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

Uh oh!

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!

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!

k8s-triage-robot commented Sep 12, 2025

Uh oh!

a-hilaly 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!

Uh oh!

Uh oh!

k8s-ci-robot commented Oct 11, 2025

Uh oh!

barney-s commented Oct 11, 2025

Uh oh!

jakobmoellerdev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tjamet Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

tjamet left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Nov 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

tjamet Nov 7, 2025 •

edited

Loading