All jobs

Add Common Labels to a Kustomize App Without Breaking Selectors

Yes. An agent adds app.kubernetes.io labels with the labels transformer, keeps every selector unchanged and proves it with a build diff, in a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the manifests before it adds a label. In a repository like argoproj/argocd-example-apps, sock-shop/kustomization.yaml is a plain list of the twenty-nine files under sock-shop/base/, deployments, services and one ingress, with no transformers at all. base/front-end-dep.yaml selects pods with matchLabels: name: front-end and labels the pod template name: front-end; base/carts-dep.yaml does the same with name: carts and also labels the Deployment itself; base/front-end-svc.yaml selects name: front-end. The only label key in use is name. kustomize-guestbook/kustomization.yaml has a namePrefix and two resources, and pre-post-sync/kustomization.yaml still uses the deprecated bases: key to pull the guestbook in. The apps/ chart deploys each directory as an Argo CD Application, and Argo CD tracks resources with its own app.kubernetes.io/instance label by default, which matters for what the agent must not set.

It uses the labels transformer, not commonLabels. commonLabels rewrites spec.selector and pod template labels too, and a Deployment's selector is immutable, so a cluster that already runs sock-shop would refuse the apply and Argo CD would show the app out of sync forever. The agent adds a labels: block with includeSelectors: false and includeTemplates: true carrying app.kubernetes.io/part-of: sock-shop and app.kubernetes.io/managed-by: argocd, so every object and every pod gets the labels while matchLabels and service selectors stay exactly name: <service>. It leaves app.kubernetes.io/instance alone, because Argo CD writes that key for tracking and a value set in git would fight the controller.

Per-component labels are set where they belong. app.kubernetes.io/name and app.kubernetes.io/component differ per service, so a common transformer cannot set them; the agent edits each file under base/, adding app.kubernetes.io/name: front-end and app.kubernetes.io/component: frontend or database to metadata.labels and to the pod template labels, and nowhere else. The same pass gives kustomize-guestbook its labels: block, and replaces bases: in pre-post-sync with resources:, since the current kustomize build warns on the old key and the guestbook's new labels should reach the hooked variant too.

Then it proves nothing else moved. It runs kustomize build sock-shop on the branch and on master, strips the new label keys from the branch output, and diffs the two: an empty diff shows that selectors, template labels and everything else are byte for byte what they were. It repeats the build for kustomize-guestbook and pre-post-sync, checks the rendered Services still select the pods their Deployments produce by comparing spec.selector to template labels per service, and attaches both diffs to the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Kubernetes recommended labels to the Kustomize apps in this repository without changing any selector. Read sock-shop/kustomization.yaml, every file under sock-shop/base, kustomize-guestbook/kustomization.yaml and its two resources, pre-post-sync/kustomization.yaml, apps/templates/applications.yaml and README.md first. Use the labels transformer with includeSelectors false and includeTemplates true, not commonLabels, to add app.kubernetes.io/part-of and app.kubernetes.io/managed-by. Do not set app.kubernetes.io/instance, which Argo CD uses for tracking. Add app.kubernetes.io/name and app.kubernetes.io/component per service by editing metadata.labels and pod template labels in each base file, never matchLabels or a Service selector. Replace the deprecated bases key in pre-post-sync with resources. Run kustomize build for each app on this branch and on the default branch, diff the outputs with the new keys removed, and confirm every Service selector still matches its pods. Open a pull request that includes the diffs and lists the labels added.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that edits sock-shop/kustomization.yaml, kustomize-guestbook/kustomization.yaml and pre-post-sync/kustomization.yaml, and adds app.kubernetes.io/name and app.kubernetes.io/component to the metadata and pod template labels of each file under sock-shop/base/. The description lists the label keys and values per service, states that no matchLabels or Service selector changed, and pastes the empty diff of the rendered output with the new keys filtered out.

The run's record keeps the kustomize build output for each app on both branches and the commands that diffed them, so a reviewer can see the comparison was made against the default branch and not against a guess.

Before merging, a reviewer checks the Argo CD app's resource tracking method, confirms app.kubernetes.io/instance was not written, and syncs one app to a staging cluster to see the labels land without a selector error.

Run it on every Linear issue labelled platform-labels

In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, filtered to the platform-labels label and the platform team. When someone labels an issue such as "cost dashboard cannot group sock-shop pods by component", the trigger puts the issue after the prompt and the run scopes itself to the app and label keys it names. Only label changes made by a person in your Rush org fire the trigger, and the automation starts at most max_runs_per_hour runs in an hour.

From your own server, the same body goes to POST /o/{org}/sessions with the repository in resources and the issue URL beside it, read through your Linear connection, and a request_id that is a UUID v5 of the issue id, so a retried call returns the run already started rather than opening a second pull request.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

The dangerous version of this change is one line long: a commonLabels block renders fine, passes review, and then fails on the cluster because it rewrote an immutable Deployment selector, leaving Argo CD stuck out of sync. The agent renders both branches in its own sandbox and diffs them, so the claim that selectors are untouched is checked output, not a reading of the YAML.

The builds and diffs stay with the run, so the pull request can carry the filtered diff and the per-service selector check, and a reviewer who manages the cluster only has to confirm the tracking label and sync once.

Frequently asked questions

Why not just use commonLabels?

commonLabels adds the labels to selectors as well, and a Deployment's spec.selector cannot change on a running object, so the first sync after the change fails. The labels transformer with includeSelectors: false adds the labels to objects and pod templates only.

Will Argo CD keep tracking the resources?

Yes. Argo CD tracks with app.kubernetes.io/instance by default, and the agent leaves that key alone; setting it in git would make every sync fight the controller. The pull request names the tracking method to confirm.

How does it set app.kubernetes.io/name when it differs per service?

A common transformer cannot, so the agent edits each base file's metadata.labels and pod template labels directly, adding the name and a component value such as frontend or database, and leaves matchLabels and Service selectors as they are.

What happens to the pre-post-sync app?

It inherits the guestbook's new labels through its base, and its kustomization.yaml moves from the deprecated bases: key to resources: so kustomize build stops warning. Its hook jobs are rendered and diffed like the rest.

More Kustomize jobs

More jobs like this: Turn a Linear label into a PR

Keep reading