Appearance

Labels, selectors, and namespaces

Organize API objects and choose exactly which set a controller or Service observes.

What you will understand

  • Use equality and set-based selectors correctly
  • Separate labels from annotations and ownership
  • Explain namespace scope without assuming isolation

Builds on: Objects, YAML, and apply

Mental model: identity, grouping, and scope

Names address individual objects; labels group objects. A label is a string key/value pair attached under metadata.labels. Many Pods can share app: catalog. That is useful precisely because labels are not unique identifiers. A selector expresses requirements for a set of objects. Controllers and Services use these sets for different purposes, so a correct-looking label on the wrong object can still break behavior.

A Service selector matches Pod labels in its own namespace. A Deployment selector must match its Pod template labels, and the Deployment manages replicas through ReplicaSets. The label on the Deployment object itself does not automatically label its Pods. Think of parent metadata and template metadata as two distinct object records at different places in the tree.

An annotation is also string metadata, but it holds descriptive or tool-specific information rather than ordinary label-selection dimensions. A release-note URL belongs naturally in an annotation. So does a tool’s structured configuration when that tool documents an annotation contract. An annotation only changes behavior if a component understands and acts on it; adding a plausible annotation name does not teach Kubernetes a new policy.

Selectors evaluate the actual Pod labels

Evaluate an AND selector and distinguish annotations from labels.

Policy viewStep 1 of 3
Attach grouping labelsPod A has app=catalog and tier=api. Pod B shares the app but has tier=worker. Their names need not resemble their labels.. A: catalog / api, ready. B: catalog / worker, ready. app=catalog,tier=api, activeA: catalog / api
A: catalog / apiReady
B: catalog / worker
B: catalog / workerReady
app=catalog,tier=api
app=catalog,tier=apiIn focus
A: catalog / apiReady
B: catalog / workerReady
app=catalog,tier=apiIn focus
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: label placed only on the parent
Attach grouping labels

Pod A has app=catalog and tier=api. Pod B shares the app but has tier=worker. Their names need not resemble their labels.

Read the complete visual sequence
  1. Attach grouping labels

    Pod A has app=catalog and tier=api. Pod B shares the app but has tier=worker. Their names need not resemble their labels.

  2. Select a set, not a name

    The selector includes A and excludes B. Commas mean AND across requirements; matching one requirement is insufficient.

  3. Keep descriptive metadata separate

    An annotation can hold a purpose or URL. It does not become an ordinary label selector dimension.

Failure: label placed only on the parent

Failure: label placed only on the parent

  1. The Deployment has the label

    Parent metadata says app=catalog, but its Pod template labels are different.

  2. No intended backend matches

    The Service selector cannot infer labels from the parent Deployment. The Pod must satisfy the selection itself.

  3. Correct the template labels

    Align intended workload and Service selectors. A Deployment’s selector must remain valid for its Pod template.

About this model

All shown Pods are in one namespace; label syntax constraints are omitted from the diagram.

Walkthrough: select a precise set

Create a disposable namespace named selection-lab, then save and apply this object there:

apiVersion: v1
kind: Pod
metadata:
  name: catalog-demo
  namespace: selection-lab
  labels:
    app: catalog
    tier: api
    environment: training
  annotations:
    training.example.com/purpose: "Selector exploration"
spec:
  containers:
    - name: web
      image: nginx:1.27.5
kubectl create namespace selection-lab
kubectl apply -f catalog-demo.yaml
# Comma-separated requirements are AND, not OR.
kubectl -n selection-lab get pods -l app=catalog,tier=api
# Quote selectors with shell-sensitive parentheses.
kubectl -n selection-lab get pods -l 'environment in (training,staging)'
kubectl -n selection-lab get pods --show-labels

The first query selects Pods that meet both requirements. The second selects either listed value for one key, but does not create a general OR across unrelated keys. Set-based selectors can also require a key’s presence or absence. Read the exact operator semantics: a negative match can include objects where the key is missing, which may be broader than your intended “all production objects except frontend.”

A namespace scopes names for many API resources. catalog-demo in selection-lab is distinct from an identically named Pod in another namespace. Namespaces are not nested folders, and an individual namespaced object belongs to one namespace. Some resources, including Nodes and Namespaces themselves, are cluster scoped. Use kubectl api-resources --namespaced=true and --namespaced=false to inspect that distinction.

Scope and ownership answer different questions

Show namespaced identity and UID-based owner relationships.

Ownership viewStep 1 of 3
Names are scopedA Pod named web can exist in team-a and team-b. Namespace is part of the address for this resource type.. team-a / Pod web, ready. team-b / Pod web, ready. Node: cluster scoped, readyteam-a / Pod web
team-a / Pod webReady
team-b / Pod web
team-b / Pod webReady
Node: cluster scoped
Node: cluster scopedReady
team-a / Pod webReady
team-b / Pod webReady
Node: cluster scopedReady
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Failure: a reference names the wrong namespace
Names are scoped

A Pod named web can exist in team-a and team-b. Namespace is part of the address for this resource type.

Read the complete visual sequence
  1. Names are scoped

    A Pod named web can exist in team-a and team-b. Namespace is part of the address for this resource type.

  2. Ownership uses a particular UID

    The Deployment owns a ReplicaSet, and the ReplicaSet owns a Pod through owner references. Shared labels do not create this chain.

  3. Policy still needs configuration

    Namespace scope helps organize names and attach policy. Network and authorization isolation require their own configured mechanisms.

Failure: a reference names the wrong namespace

Failure: a reference names the wrong namespace

  1. Pod expects local configuration

    A Pod in team-a references ConfigMap settings. Ordinary volume and environment references use its own namespace.

  2. Matching name is insufficient

    A ConfigMap with that name in team-b does not satisfy the Pod’s namespaced reference. Preparation can fail before execution.

  3. Create configuration in the intended scope

    Provide the correctly named object in team-a and preserve deliberate policy boundaries rather than copying credentials indiscriminately.

About this model

A Deployment-to-ReplicaSet-to-Pod chain is shown in one namespace; Nodes are cluster scoped.

Practice: selection does not imply ownership

Owner references link a dependent object to a particular owner’s UID and support lifecycle behavior such as garbage collection. Labels alone do not express that relationship. A Pod labeled app: catalog is not automatically owned by a similarly labeled Deployment. For managed workloads, let the appropriate controller create child objects and their owner references. Hand-writing owner references without understanding scope and controller rules is not an ordinary grouping operation.

Inspect both mechanisms on a Deployment-created Pod:

kubectl -n selection-lab get pods --show-labels
# Substitute the actual managed Pod name from a Deployment exercise.
kubectl -n selection-lab get pod ACTUAL_MANAGED_POD \
  -o jsonpath='{.metadata.ownerReferences}'

If the example Pod is standalone, owner references should be absent. That absence explains why deleting it does not obligate a ReplicaSet to replace it. A controller can sometimes adopt an eligible unowned matching object; avoid overlapping workload selectors rather than relying on accidental adoption.

Pitfalls

A namespace is an API organization and policy attachment boundary, not automatic network isolation or a separate Linux namespace. Without appropriate authorization, network policy, admission, and resource controls, workloads in different namespaces can still interfere or communicate. Secret and ConfigMap references from ordinary Pods are namespace scoped; creating the same name elsewhere does not satisfy the reference.

Changing a label can change who selects the object immediately after observers catch up. Treat labels used by Services and controllers as operational configuration, not decorative tags. Namespace deletion also removes namespaced resources within it, so only delete dedicated training namespaces in this exercise.

Check your understanding

A Service selects app=catalog, but only the Deployment object has that label. Will it select the Deployment’s Pods?

Only if the Pods themselves also carry the label. The Service evaluates Pod labels, not the Deployment’s metadata or its name. Put the intended labels in the Pod template, verify the created Pods, and inspect the Service’s EndpointSlices later. Selection and ownership remain separate questions.

Practice label inspection and namespace-qualified commands in the module lab. Next, make cluster context explicit before issuing any mutation.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.