Topic 07

Labels and Selectors

MetadataCore

Labels are key-value tags attached to objects, and selectors are queries over them. Together they are the loose-coupling mechanism that wires Kubernetes together: a Service finds its Pods by selector, a Deployment owns its Pods by selector, and you operate on groups of objects by selector.

Nothing in Kubernetes is connected by hard reference. A Service does not list the Pods it routes to; it describes them with a label query, and membership is whatever currently matches. Internalizing that indirection explains a great deal of the system's flexibility.

Labels vs Annotations

Both are key-value metadata, but they serve opposite purposes. Labels are for identification and selection — short, indexed, queryable; this is what selectors match on. Annotations are for arbitrary non-identifying data — build IDs, checksums, tool configuration — and are never used to select. If you will query on it, it is a label; if it is just attached information, it is an annotation.

Labels and annotations on a Pod

metadata:
  labels:
    app: web              # identifying — selectors match these
    tier: frontend
    version: v2
  annotations:
    build: "2026-05-27-abc123"   # informational — never selected on
    kubernetes.io/change-cause: "bump to v2"

Selectors

Selectors come in two forms. Equality-based selectors match exact values (app=web, tier!=cache). Set-based selectors match membership (version in (v1, v2), tier notin (cache), or app exists). Services use the simpler equality form; Deployments and many tools accept set-based selectors via matchExpressions.

A selector defines a live set. Add a label to a Pod and it joins every Service and controller whose selector now matches; remove it and it drops out. This is how a canary works — a Service selecting app=web sends traffic to both version=v1 and version=v2 Pods at once, simply because both carry app=web.

How Controllers Use Selectors

A Deployment's selector.matchLabels must match the labels in its Pod template — that is how it knows which Pods are its replicas. The selector is immutable after creation, because changing which Pods an object owns mid-flight would be chaos. A common first error is a mismatch between the selector and the template labels, which the API server rejects.

The danger at the other extreme is two controllers with overlapping selectors fighting over the same Pods, each trying to drive the count to its own desired value. Keep selectors specific enough that each set of Pods has exactly one owner.

Conventions That Pay Off

Kubernetes recommends a set of standard labels under the app.kubernetes.io/ prefix — name, instance, version, component, part-of, managed-by. Adopting them early makes dashboards, cost attribution, and bulk operations work across every tool without bespoke conventions per team.

Labels are also your operational scalpel: kubectl get pods -l app=web,version=v2 selects exactly the Pods you mean, for inspection, deletion, or rollout control. A consistent labeling scheme is the difference between surgical operations and guesswork.

Label vs annotation

Label — identifying, indexed, queryable. Selectors match on labels. Keep them short and few.

Annotation — non-identifying, arbitrary, never selected on. The place for build metadata, checksums, and tool config.

Common Mistakes

Using labels for large or free-form data — that belongs in annotations; labels are indexed and size-limited.
Overlapping selectors so two controllers fight over the same Pods, each forcing its own replica count.
A Deployment selector that doesn't match its own Pod-template labels — the API server rejects it.
Trying to change a controller's selector after creation; it is immutable for good reason.
Inventing a per-team labeling scheme instead of adopting the standard app.kubernetes.io/ labels.

Best Practices

Decide deliberately: identifying and queryable → label; informational → annotation.
Adopt the recommended app.kubernetes.io/ labels so tooling, dashboards, and cost reports work out of the box.
Keep selectors specific enough that every set of Pods has exactly one owning controller.
Use -l label selectors for safe, surgical bulk operations instead of naming objects one by one.
Add a version label to enable canary and blue-green patterns via a shared Service selector.

RelatedAnnotations — the non-identifying sibling of labelsServices / controllers — everything that connects objects does so by selectorCloud resource tags — the closest analog for grouping and attribution

Knowledge Check

What is the right place for a build timestamp you will never query on?

An annotation — non-identifying metadata
A label, so selectors can match and filter on it later
Encoded into the Pod's own name
A ConfigMap mounted into the Pod as a file

How does a Service decide which Pods it routes to?

By a label selector — membership is whatever Pods currently match, not a fixed list
By an explicit hard-coded list of Pod names written into its spec
By the fixed set of Pod IP addresses recorded at the moment the Service was created
By which worker node each candidate Pod happens to run on

Why must a Deployment's selector match its Pod-template labels?

The selector is how the Deployment identifies which Pods are its replicas; a mismatch is rejected
Because every label on a Pod must be globally unique across the cluster
To give the scheduler the information it uses to place the Pods on nodes
Selectors and template labels are entirely unrelated, so any match between them is purely coincidental

You got correct