Kubernetes Fundamentals · Module 04 of 14

Labels, selectors and annotations

Use metadata to organize resources and understand how controllers and Services find the objects they manage or route to.

Learning objectives

By the end of this module, you should be able to:

Apply labels for grouping and selection.
Distinguish labels from annotations.
Predict which objects match a selector.

Labels are queryable identity

Labels are key/value metadata intended for identifying and selecting objects. Controllers and Services rely heavily on label selectors, so a label mismatch can break workload ownership or traffic routing without producing a syntax error.

Selectors connect resources

A Deployment selector identifies the Pods it manages. A Service selector identifies Pods that become Service endpoints. Selectors should represent stable workload identity rather than transient operational facts.

Annotations carry non-identifying metadata

Annotations store metadata that does not need to participate in selection, such as tooling information, checksums or external references.

Worked examples

See the idea in practice.

Select by label

kubectl -n gnu-k8s-fundamentals get pods -l app=web
kubectl -n gnu-k8s-fundamentals get pods -l 'tier in (frontend,api)'

Equality and set-based selectors filter API results.
The same selector model appears in multiple Kubernetes APIs.

Hands-on lab

Lab — Build a selectable set

Goal: Create labeled Pods, query them, and attach an annotation without changing selection.

Before you start

kubectl is installed and can reach the lab cluster.
Use the dedicated gnu-k8s-fundamentals namespace unless a step explicitly says otherwise.

STEP 1

Create three labeled Pods

kubectl -n gnu-k8s-fundamentals run label-web --image=nginx:alpine --labels=app=web,tier=frontend
kubectl -n gnu-k8s-fundamentals run label-api --image=nginx:alpine --labels=app=api,tier=api
kubectl -n gnu-k8s-fundamentals run label-db --image=nginx:alpine --labels=app=db,tier=data

STEP 2

Select only frontend

kubectl -n gnu-k8s-fundamentals get pods -l tier=frontend

STEP 3

Use a set selector

kubectl -n gnu-k8s-fundamentals get pods -l 'tier in (frontend,api)'

STEP 4

Add an annotation

kubectl -n gnu-k8s-fundamentals annotate pod label-web training.gnugroup.org/note="metadata-not-selector"

STEP 5

Clean up

kubectl -n gnu-k8s-fundamentals delete pod label-web label-api label-db

Verify

tier=frontend returns one Pod.
The set selector returns two Pods.
The annotation exists but does not change label selection.

Expected outcome

Selectors operate on labels only.

If it fails

If selectors return nothing, inspect --show-labels and check key/value spelling.
Remember that annotations and labels are separate maps.

Real-world connection

Reliable labeling conventions make rollouts, Services, policy and observability much easier to operate.

Avoid these traps

Common mistakes

Putting rapidly changing free-form data into labels.
Changing a Service selector without checking its endpoints.
Assuming annotations are selectable by normal label selectors.

Knowledge check

Can you explain it without looking back?

Open each answer only after you have tried to answer the question yourself.

1What metadata is intended for selection?

Labels.

2What happens when a Service selector matches no Pods?

The Service has no selected backends/endpoints for that selector.

3What is an annotation suited for?

Non-identifying metadata that tools or humans need but selectors do not.