Pod Labels Discipline

Labels drive selectors. The discipline.

Required labels

The required labels track the basic identity of every pod: the application, the instance, the version, the component. Without these, debugging a pod becomes guess-work; with them, every selector, every dashboard, and every audit query has a stable surface to query against.

• app.kubernetes.io/name. The application name; the standard k8s recommended label that drives most selectors.
• app.kubernetes.io/instance. The deployment instance; supports per-environment and per-replica disambiguation.
• app.kubernetes.io/version. The version string; critical for tracking which version is running where during rollout debugging.
• app.kubernetes.io/component. The component (api, worker, scheduler); useful in multi-pod applications where the role differs.

Ownership labels

Ownership labels make the pod actionable during an incident. The on-call needs the team, the owner, and the contact channel in the alert payload; without them, the page becomes an investigation into who to call before the actual triage even begins.

• team. The team that owns the workload; page routing, cost attribution, and debugging all start with team.
• owner. Specific engineer or rotation; for incident response and questions outside business hours.
• contact. Slack channel or email; the on-call should know who to ping in 30 seconds.
• per-pod ownership audit. Pods without ownership labels surface in the quarterly audit; orphaned workloads get assigned or removed.

Environment and lifecycle

Environment and lifecycle labels drive policy enforcement and capacity planning. Prod-versus-staging routing depends on the environment label; scheduler decisions and alert tier depend on the criticality label; capacity planning depends on the lifecycle label.

• environment. prod, staging, dev; drives policy enforcement and alerting tier.
• lifecycle. long-running, ephemeral, batch; supports capacity planning and scheduler decisions.
• criticality. tier-0, tier-1, tier-2; drives priority class, dedicated nodes, alert routing.
• per-cluster policy match. Production clusters reject pods missing environment labels; the policy enforces the discipline at admission.

What not to put in labels

Labels are selectable indices, not free-form storage. High-cardinality values blow up metrics cost; free-form descriptions belong in annotations; secrets do not belong in labels at all because labels are visible to anyone with cluster read access.

• High-cardinality values. user_id, request_id, transaction_id; cardinality explosion in metrics; expensive in observability bills.
• Free-form descriptions. Use annotations; labels should be selectable, annotations are documentation.
• Secrets or sensitive data. Labels are visible to anyone with cluster read access; secrets belong in Secrets, not labels.
• Per-incident transient state. Labels are not the place for ephemeral status; use annotations or a dedicated status field.

Enforcement

Enforcement is what keeps label discipline real. OPA Gatekeeper or Kyverno policy at admission rejects non-compliant pods; CI lint catches missing labels at PR time; quarterly audit surfaces drift across the cluster.

• Admission policy. OPA Gatekeeper or Kyverno; required labels enforced at admission, non-compliant pods are rejected.
• CI lint. Catches missing labels at PR time, before deploy; the feedback loop is faster than admission rejection.
• Quarterly audit. Cluster-wide query for label compliance; per-team report; drift addressed before it becomes incident-shaped.
• Per-team scorecard. Label compliance percentage per team; supports continuous improvement of the discipline.