Label-based attribution

Your workloads already carry team: payments and kubeadapt-department: engineering labels. You want those labels to drive cost attribution without anyone clicking through the Assignment Workbench. Kubeadapt does this for you automatically — every cluster, every update.

The four label keys

Kubeadapt reads four label keys to build attributions. The keys themselves are configurable in Settings → Label Keys:

The defaults are conventions, not requirements. Override any of the four to match an existing taxonomy — acme.io/team instead of team, cost-center instead of kubeadapt-department, anything that's already on your pods.

The label set is per organization, not per cluster. The same keys apply across every cluster you connect.

How sync works

Your Kubeadapt agent sends a snapshot of the cluster to Kubeadapt approximately once per minute. On every snapshot, Kubeadapt:

1. Reads the configured label keys from each workload, namespace, and cluster.
2. Creates any Team or Department it hasn't seen before from new label values.
3. Updates label-based assignments to match the current state of the cluster.
4. Removes label-based assignments for labels that no longer exist.

Manual assignments and suppressed entities (see below) are never touched.

Manual wins. Always.

This is the most important rule in attribution.

When Kubeadapt would write a label-based assignment for a workload, it first checks for an existing manual assignment on that workload. If one exists, the label-based write is skipped. The manual assignment vetoes the label.

The reverse never happens: a label can never overwrite a manual assignment. Even removing a manual assignment doesn't trigger an immediate re-attribute — it'll get rebuilt on the next cluster update if a label is present.

In practice this means:

• Day 1. Pod has team: foo label. Kubeadapt records a label-based assignment to Team foo. Cost rolls up to foo.
• Day 2. Someone uses the Assignment Workbench to attribute the pod to Team bar. A manual assignment to Team bar is recorded. Cost rolls up to bar. The label is still there, ignored.
• Day 3. Someone clicks Unassign. The manual assignment is removed. On the next cluster update, Kubeadapt re-creates the label-based assignment for Team foo (because the label is still present). Cost rolls up to foo again.

The label is "always there in the background"; the manual assignment is "we said otherwise".

Assignment sources

Every assignment Kubeadapt records is either:

• Manual — created from an in-product action (Assignment Workbench or admin API). Never automatically removed.
• Label-based — created from a Kubernetes label. Automatically removed when the label disappears.

These two kinds of assignment can coexist on the same workload, but the manual one always wins.

Suppression

There's a third way to control attribution: suppression. A suppressed workload, namespace, or cluster is excluded from label-based attribution entirely. The use case is "this workload has a stale label we don't trust, and we don't want to fight it every cluster update". A suppressed entity's only path back to attribution is a manual assignment.

Suppression is an admin-controlled state managed outside the standard Cost Attribution UI.

How removed labels are cleaned up

Label-based assignments are kept in sync with what's actually on the cluster. Concretely:

• Remove team: foo from a pod → on the next cluster update, the label-based assignment for that pod and Team foo is gone.
• Stop running the workload entirely → on the next cluster update, every label-based assignment pointing at the now-absent workload is gone.
• Switch the pod's label to team: bar → on the next cluster update, the foo assignment is removed and a fresh bar assignment is created.

Manual assignments are never touched by this cleanup.

Edge cases

• Multiple replicas under one Deployment. All replicas share the Deployment's labels and attribute to the same Team. (If you've manually labeled individual pods differently, Kubeadapt reads the pod-level labels, but in practice everyone uses controller-level labels.)
• A label value with no matching Team. New label values create the Team automatically. You don't have to pre-create.
• A label value pointing at a deleted Team. If the Team was explicitly deleted in the UI, the deletion is honored — Kubeadapt won't re-create the Team or the assignment. The workload becomes unattributed via label and shows up that way in the Workbench's Available tab.
• A label whose value is empty. Empty values are skipped.
• No label. The workload is unattributed by label. A manual assignment can still apply; a cluster-level or namespace-level rule from the Workbench can still apply. Otherwise the workload's cost rolls up to "Unassigned" in attribution views.

Roll-out tips

If you're enabling label-driven attribution against a cluster that's been running for a while:

1. Decide your taxonomy first. Pick the four label keys before applying anything. Changing keys later is an org-wide event.
2. Label controllers, not pods. A Deployment-level label flows to every replica without per-pod fiddling.
3. Watch the Workbench's Available tab. It surfaces unattributed workloads; that's your gap list.
4. Use manual assignments as a stop-gap. While you negotiate the label rollout with each team, manually assign the cluster default; remove the manual assignments as labels arrive.

Next steps

• Cost attribution overview — the three-layer model, including how manual fits in.
• Teams and Departments — what gets created when a new label value appears.
• Assignment Workbench — the manual override surface.