Kubernetes Labels vs Annotations: Key Differences

Kubernetes stores two kinds of user-defined metadata on most objects: labels in metadata.labels and annotations in metadata.annotations. They sit beside each other in YAML, but Kubernetes treats them differently. Labels identify and group resources for selectors; annotations describe resources without participating in selection.

This page is a comparison only. For hands-on work, use the labels and annotations guides listed in Related guides above.

Quick answer

If Kubernetes or kubectl get -l must match the value, use a label. If the value is informational and should not drive routing, ownership, or filtering, use an annotation.

Basic difference

Labels answer: Which group does this object belong to? Services, Deployments, ReplicaSets, and kubectl get -l read labels to find related Pods and controllers. Labels used by controller or Service selectors should remain stable; other labels, such as app.kubernetes.io/version, can change between releases.

Annotations answer: What extra context describes this object? Runbook URLs, owner contacts, tool-specific JSON, and release metadata that should not drive selection live here. Git commits and build IDs can also appear as labels — for example app.kubernetes.io/version — when users or tools need to filter by them. Selectors ignore annotations. Some controllers read specific annotation keys they document (for example Ingress controllers), but that is not the general label-selector mechanism.

Both use optional DNS-style key prefixes (example.com/owner). Neither replaces object names, and neither should store secrets.

Labels and annotations compared

Labels and annotations are independent maps. The same object can carry both without conflict.

Side-by-side on one Deployment

The same Deployment can carry identifying labels and descriptive annotations at once. They serve different roles:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
    environment: production
    tier: frontend
  annotations:
    example.com/owner: platform-team
    example.com/git-commit: a1b2c3d4
    example.com/documentation: https://docs.example.com/web
spec:
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
        environment: production
        tier: frontend
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine

• Labels on the Deployment and Pod template — app, environment, tier — are what selectors and kubectl get -l environment=production can match.
• Annotations on the Deployment — owner, Git commit, documentation URL — describe the release. They do not appear in spec.selector and are not queried with -l.

To propagate annotations onto every Pod, add them under spec.template.metadata.annotations in the same manifest. Pod-template placement is covered in the Kubernetes annotations guide linked in Related guides.

Wrong vs right choices

Git commit and build ID metadata can be a label or an annotation depending on whether selection matters. Kubernetes documents app.kubernetes.io/version for a revision hash when tools or users need to filter by it.

Other metadata types have a clearer split:

Putting selectable data only in annotations is a common mistake: the object looks documented in kubectl describe, but Services and kubectl get -l behave as if that key does not exist. Changing ordinary informational labels is valid; the risk applies mainly when that label participates in workload ownership, routing, policy, or another selector.

When to use labels

Use labels when the value must identify or group objects:

• Application identity — app, app.kubernetes.io/name
• Version or revision when selectable — app.kubernetes.io/version for a Git or build identifier tools must filter on
• Environment or tier for filters — environment=production, tier=frontend
• Controller ownership — keys in spec.selector.matchLabels and matching Pod-template labels
• Service endpoints — keys in Service spec.selector that Pods must carry
• Node selection — node labels read by nodeSelector or affinity (label the node first)

For syntax, kubectl label, selector grammar, and troubleshooting, continue to the Kubernetes labels and selectors guide in Related guides.

When to use annotations

Use annotations when the value describes the object and should not drive selection:

• Release traceability when selectors do not need the value — or use a label such as app.kubernetes.io/version when users or tools must filter by revision
• Owner, on-call, or team contact strings
• Links to runbooks, diagrams, or external docs
• Tool-specific configuration read by one controller (check that controller’s docs)
• Structured JSON for operators or GitOps — as a single string value

For kubectl annotate, overwrite/remove syntax, and the 256 KiB limit, continue to the Kubernetes annotations guide in Related guides.

Selectors ignore annotations

kubectl get -l, Services, Deployments, and NetworkPolicies evaluate metadata.labels; they never search metadata.annotations. Annotations are ignored by label selectors, but annotations used by Ingress controllers, operators, or other extensions can alter object behavior when those tools watch documented keys.

Decision checklist

What's Next

• Kubernetes Api Resources
• Kubernetes CNI, CSI and CRI Interfaces Explained
• Add, Remove, Reset and Rejoin Kubernetes Nodes

References

• Labels and Selectors
• Annotations
• Recommended Labels

Summary

Labels in metadata.labels identify and group objects; selectors and kubectl get -l match them. Annotations in metadata.annotations store descriptive metadata selectors ignore. Use labels for app identity, environment, tier, and anything Services or controllers must match — including a version or build ID when you need to select by it. Use annotations for traceability-only release metadata, URLs, owner contacts, and tool-specific data that should not drive selection.