Chapter 7: Organizing pods and other resources using namespaces and labels

Introduction

The introduction distinguishes two ways to organize objects in a shared Kubernetes cluster: namespaces separate teams’ objects, while labels show what objects belong to and what roles they play.

• Team separation with namespaces: Explain that namespaces address the problem of multiple teams deploying objects to the same cluster without accidentally modifying one another’s objects.
  Why it matters: This identifies why a shared cluster needs a way to separate teams’ objects.
• Object identity with labels: Explain that labels address a different organization problem: making it easy to see where an object belongs and what role it has, such as which application a pod belongs to.
  Why it matters: Labels make a large collection of objects easier to understand and navigate.

Key terms: object namespaces, object labels

7.1 Organizing objects into namespaces

This section explains how Kubernetes namespaces organize objects in a shared cluster, scope object names and user privileges, and differ from cluster-scoped resources.

• Namespace organization and naming: Explain how namespaces let teams or clients organize their objects within one Kubernetes cluster and reuse object names without collisions.
  Why it matters: Namespaces make a shared cluster easier to organize without requiring every team to invent globally unique object names.
• Namespaced and cluster-scoped resources: Distinguish resources that belong to namespaces from resources that are cluster scoped, and state how to check a resource’s scope.
  Why it matters: The distinction tells you which kinds of objects can be organized within a namespace.
• Namespace privilege scope: Explain how namespaces can limit where a user has permission to manage objects in a shared cluster.
  Why it matters: Privilege scoping helps teams share a production cluster while managing access to their respective objects.

Key terms: Kubernetes namespaces, Kubernetes API objects, scope for object names, namespaced, cluster scoped, kubectl api-resources, NAMESPACED column, scope for user privileges, namespace

7.1.1 Listing namespaces and the objects they contain

Shows how to list Kubernetes namespaces and inspect objects in one namespace or across the cluster.

• Namespace objects and default scope: Explain how to list namespaces and why an ordinary kubectl object listing shows only objects in the default namespace.
  Why it matters: A pod missing from an ordinary listing may be in another namespace.
• Specific and cluster-wide listings: Describe how to list pods in a specified namespace or across all namespaces, and how the latter output identifies each pod’s namespace.
  Why it matters: These options let you find objects without confusing a namespace-limited view with the whole cluster.
• Separation of system pods: Explain why Kubernetes system pods are kept in a separate namespace from user-created pods.
  Why it matters: The separation makes system resources easier to distinguish from your own.

Key terms: Namespace object, default namespace, kubectl get, ns, --namespace, -n, --all-namespaces, -A, NAMESPACE column, kube-system

7.1.2 Creating namespaces

This section shows two ways to create namespaces, explains why operators may include them in manifests, and states the naming rules for namespaces.

• Namespace creation methods: Describe how to create a namespace with kubectl create namespace or by posting a YAML or JSON Namespace manifest with kubectl apply, and explain why operators may choose the manifest approach.
  Why it matters: You can choose between creating one namespace quickly and including namespace creation in a larger deployment.
• Namespace naming constraints: State the naming constraints given for namespaces and distinguish them from the general object-name rule described here.
  Why it matters: These constraints help you choose a namespace name that Kubernetes will accept.

Key terms: kubectl create namespace, Namespace object, manifest file, kubectl apply, DNS subdomain names, namespace names

7.1.3 Managing objects in other namespaces

This section explains how kubectl chooses a namespace for objects and how to work in a different namespace using a command option, an object manifest, or the current context.

• Current and explicit namespaces: Explain where an object is created when no namespace is specified and how to target another namespace with kubectl’s namespace option.
  Why it matters: It helps you create and inspect objects in the namespace you intend.
• Namespace in object manifests: Describe how a manifest specifies an object’s namespace and what happens if a conflicting namespace option is also supplied.
  Why it matters: A namespace written into a manifest determines where its object is created and cannot be contradicted by the command.
• Current context namespace setting: Explain how to make kubectl use a different current namespace for subsequent commands.
  Why it matters: Switching the context’s namespace avoids repeating the namespace option during ongoing work.

Key terms: current namespace, default, --namespace, -n, metadata.namespace, object manifest, kubectl apply, current context, kubeconfig, kubectl config set-context --current --namespace

7.1.4 Understanding the (lack of) isolation between namespaces

This section explains that namespaces prevent object-name conflicts but do not, by themselves, isolate workloads at runtime or on the network.

• Namespace scoped object names: Explain how namespaces let users create objects with the same name in one cluster, and why that does not make each namespace a fully isolated virtual cluster.
  Why it matters: It helps distinguish what namespaces organize from what they actually isolate.
• Shared node runtime risks: Explain why pods in different namespaces can still affect one another at runtime, and justify using separate physical clusters for production, staging, and development.
  Why it matters: Separate names do not protect workloads from risks created by sharing physical nodes.
• Default cross namespace connectivity: Describe the default network relationship between applications in different namespaces and state what can be used to restrict permitted connections.
  Why it matters: A namespace boundary alone does not stop applications from connecting across it.

Key terms: namespaces, naming conflicts, virtual cluster, physical cluster, cluster node, OS kernel, container technologies, network isolation, NetworkPolicy

7.1.5 Deleting namespaces

This subsection explains what happens when a namespace is deleted and how to investigate a deletion that remains stuck.

• Namespace deletion behavior: Explain that deleting a Namespace object automatically deletes the objects in it, and describe why kubectl delete may keep running while the namespace shows a Terminating status.
  Why it matters: It helps you interpret a delete command that is still running without assuming you must remove every object yourself.
• Stuck namespace deletion diagnosis: Explain why namespace deletion can remain stuck and how the namespace status helps identify the remaining object. Describe why an empty kubectl get all result is not proof that the namespace is empty.
  Why it matters: It gives you a way to investigate a namespace that stays Terminating even when a quick object listing looks empty.

Key terms: Namespace object, Terminating, kubectl delete, --wait=false, kubectl get all, status field, custom object, custom controller, finalizer

7.2 Organizing pods with labels

This section uses a growing, multi-service Kiada deployment to explain why labels are a better way than namespaces to group related pods and objects.

• Labels for service organization: Explain why a growing application suite needs a way to identify which pods and other objects belong to each service, and why this example calls for labels rather than a namespace per service.
  Why it matters: Labels help people make sense of which resources belong together as an application grows.
• Canary release purpose: Describe what a canary release is and why it runs alongside a stable release.
  Why it matters: The stable and canary pods illustrate why one service can have multiple releases to keep track of.

Key terms: Pod object, object labels, namespaces, replicas, canary release, stable version

7.2.1 Introducing labels

Introduces labels as flexible key–value metadata and shows how application and release labels organize pods along two dimensions.

• Label meaning and properties: Explain what a Kubernetes label is and how labels are attached to objects.
  Why it matters: Labels let people identify what an object is for without relying on its name alone.
• Application and release dimensions: Describe how the example uses app and rel labels to identify pods by both application and release.
  Why it matters: Using both labels makes each pod’s application and release apparent at a glance.

Key terms: label, key–value pair, label key, label value, app label, rel label, stable release, canary release

7.2.2 Adding labels to pods

This section shows how to define, inspect, add, change, and remove labels on pods.

• Labels in object manifests: Describe where labels are defined in an object manifest and how the example pod uses them.
  Why it matters: Putting labels in a manifest makes them part of the object definition.
• Inspecting pod labels: Explain how to display all or selected labels on pods with kubectl.
  Why it matters: Displaying labels lets you check which pods have them and spot incorrect values.
• Changing labels on existing pods: Explain how to add, correct, and remove labels on existing pods, including when --overwrite, --all, and a trailing minus sign are needed.
  Why it matters: These distinctions let you fix mistaken labels and apply or remove labels across a group of pods.

Key terms: metadata.labels, app, rel, kubectl describe, --show-labels, --label-columns, -L, kubectl label, --overwrite, --all

7.2.3 Label syntax rules

This section explains how label keys and values are named, including prefix conventions, syntax limits, and when to use an annotation instead.

• Label key prefix conventions: Distinguish unprefixed, Kubernetes-reserved, and organization-prefixed label keys, and explain how an organization can avoid naming conflicts.
  Why it matters: Choosing an appropriate prefix helps keep your labels distinct from Kubernetes labels.
• Label key syntax: Describe the syntax and length restrictions for a label key's optional prefix and required name.
  Why it matters: These rules let you tell whether a proposed label key is valid.
• Label value syntax: State the restrictions on label values and explain what to use when a value does not fit them.
  Why it matters: The value rules help you choose between a label and an annotation for identifying information.

Key terms: label key, prefix, kubernetes.io/, k8s.io/, label name, DNS subdomain, label value, annotation

7.2.4 Using standard label keys

This section distinguishes labels Kubernetes uses on system objects from recommended labels users can apply consistently to related application components.

• Kubernetes system object labels: Distinguish labels Kubernetes uses on system objects from labels on user-created objects, and describe how cloud providers may add further labels.
  Why it matters: It helps you interpret labels you find on cluster objects without assuming Kubernetes added them to your own objects.
• Shared application instance labels: Explain why objects belonging to one application instance should share the recommended label set.
  Why it matters: Consistent labels make related components recognizable and manageable as a group.

Key terms: well-known labels, system objects, nodes, recommended labels, application instance, label selectors, bulk operations

7.3 Filtering objects with label selectors

This section explains how label selectors filter Kubernetes objects by label values or key presence, and how multiple selectors work together.

• Label filtering and equality: Explain how a label selector filters pods or other objects, and describe what the equality-based selectors app=quote and app!=quote select.
  Why it matters: Selectors let you act on the objects you mean rather than merely read their labels.
• Set-based selection options: Describe how set-based selectors test whether a label value is in or not in a set, or whether a label key is present or absent.
  Why it matters: Set-based selectors express choices that a single value comparison cannot.
• Combined selector matching: Explain what an object must satisfy when multiple label selectors are combined, using app=quote,rel=canary as an example.
  Why it matters: Combining selectors narrows a selection to objects that meet all the stated label criteria.

Key terms: label selector, equality-based selector, label key, label value, set-based selectors, in, notin, app, !app, combining multiple selectors

7.3.1 Using label selectors for object management with kubectl

This section shows how to use label selectors with kubectl to list matching objects and delete matching pods, with a warning about deletion.

• Value-based object filtering: Apply label selectors with kubectl get to list objects whose labels match specified values, including combined equality requirements and set-based choices.
  Why it matters: Selectors make it practical to find the relevant objects when a namespace contains many of them.
• Label presence filtering: Distinguish selectors that test whether a label key is present from those that test whether it is absent.
  Why it matters: Presence tests let you find objects even when the label's value is not what matters.
• Selector-based deletion risk: Explain how a label selector can delete multiple matching objects in one operation and why that operation requires care.
  Why it matters: A selector saves repetitive deletion commands but can also remove more objects than intended without a confirmation prompt.

Key terms: label selector, kubectl get, --selector, -l, equality-based selector, set-based selector, label key, presence, absence, !rel

7.3.2 Using label selectors in object manifests

This section shows how labels and selectors in Pod manifests constrain which nodes can run a pod, from simple node selectors to more expressive node affinity.

• Scheduling by node criteria: Explain why a pod may need to run on a subset of nodes and why selecting eligible nodes by label is preferable to naming one node.
  Why it matters: Selecting by requirements gives Kubernetes flexibility without losing the placement you need.
• Equality-based node selection: Describe how to label nodes for frontend workloads and use a Pod manifest’s spec.nodeSelector to make only matching nodes eligible.
  Why it matters: Matching a Pod’s selector to node labels is the basic way this section controls pod placement.
• Set-based node affinity: Explain how set-based expressions in a Pod’s nodeAffinity select or exclude nodes, including how multiple terms and expressions combine.
  Why it matters: Node affinity can express placement requirements that a simple key–value node selector cannot.

Key terms: node labels, selectors, worker nodes, node-role: front-end, spec.nodeSelector, equality-based label selector, nodeAffinity, nodeSelectorTerms, matchExpressions, In

7.4 Filtering objects with field selectors

This section introduces field selectors as a way to filter Kubernetes objects by properties other than labels and identifies which fields are available.

• Field selector purpose and scope: Explain that field selectors filter objects by properties other than labels, such as the node a pod runs on. State that supported fields depend on the object kind, while metadata.name and metadata.namespace are always supported.
  Why it matters: This helps you recognize when filtering by an object's own properties is useful and why a field may not work for every kind of object.

Key terms: field selectors, label selectors, object kind, metadata.name, metadata.namespace

7.4.1 Using a field selector in kubectl

This subsection shows how to filter pods with kubectl field selectors, using node assignment and running phase as examples.

• Pod filtering with field selectors: Apply kubectl field selectors to list pods assigned to a particular node or pods whose phase is not Running. Explain that -A extends the search from the current namespace to all namespaces.
  Why it matters: These filters help you find relevant pods without scanning every pod in a namespace or cluster.
• Finding usable selector fields: Describe how kubectl explain helps identify object field names and how to find out whether a field is supported in a field selector.
  Why it matters: It gives you a way to find candidate fields without assuming every object field can be used as a selector.

Key terms: field selector, spec.nodeName, status.phase!=Running, -A, --all-namespaces, kubectl explain, pod.spec, field selectors

7.4.2 Using field selectors in object manifests

This subsection shows that object manifests can select objects by field values, using a pod’s node affinity as an example.

• Field matching in node affinity: Explain that a pod’s nodeAffinity can match nodes by field values using matchFields instead of matchExpressions, for example to prevent scheduling on a specific node.
  Why it matters: It connects field-based selection to a concrete scheduling use in a pod manifest.

Key terms: nodeAffinity, matchFields, matchExpressions

7.5 Annotating objects

The section introduces annotations as an alternative when information does not fit the constraints of labels.

• Why objects have annotations: Explain why Kubernetes allows annotations in addition to labels: labels help manage objects and identify members of a set, but their values have restrictions that make them unsuitable for some information.
  Why it matters: It helps you recognize why an object might need metadata other than labels.

Key terms: labels, label value, annotations

7.5.1 Introducing object annotations

Introduces annotations as flexible object metadata, explains why Kubernetes uses them for emerging features, and shows what users can store in them.

• Annotation purpose and format: Distinguish annotations from labels and describe the rules for annotation keys and values.
  Why it matters: This distinction helps you choose the right place for information attached to an object.
• Annotations for emerging features: Explain why Kubernetes may introduce an annotation before adding a new API field, and what can happen after the feature has been tried in practice.
  Why it matters: An annotation on an object may represent a feature that has not yet become a permanent API field.
• User-defined annotation uses: Describe how users and tools can use annotations to attach information or instructions to objects.
  Why it matters: Annotations keep useful context and tool-facing signals with the object they describe.

Key terms: annotations, labels, annotation keys, annotation values, object annotation, Kubernetes API, schema, deprecated, Git commit hash, build timestamp

7.5.2 Adding annotations to objects

This subsection shows how to add annotations to existing Kubernetes objects or to object manifests, and warns that some YAML annotation values must be quoted.

• Two ways to add annotations: Describe how to add an annotation to an existing object with kubectl annotate or include annotations in an object manifest before creating it.
  Why it matters: These are the two approaches this section gives for adding annotations.
• Quoting YAML annotation values: Explain when an annotation value in a YAML manifest should be enclosed in quotes and what can happen if it is not.
  Why it matters: Quoting values that YAML might misinterpret avoids a cryptic error when applying the manifest.

Key terms: annotations, kubectl annotate, object manifest, annotation value, YAML parser, string

7.5.3 Inspecting an object’s annotations

This section shows how to inspect an object’s annotations and explains why one kubectl-managed annotation may be absent from kubectl describe output.

• Object annotation inspection: Describe how to view an object’s annotations with kubectl describe or by examining its YAML or JSON definition, including extracting them from JSON with jq. Distinguish these methods from the kubectl get object list, which has no option to display annotations.
  Why it matters: Choosing the right inspection method lets you find annotations that the ordinary object list does not show.
• Hidden kubectl annotation: Explain why kubectl describe may omit the kubectl.kubernetes.io/last-applied-configuration annotation even when it appears in the object’s JSON definition.
  Why it matters: A difference between describe output and the JSON definition does not necessarily mean an annotation was lost.

Key terms: annotations, kubectl get, kubectl describe, jq, YAML, JSON, kubectl.kubernetes.io/last-applied-configuration

7.5.4 Updating and removing annotations

This subsection explains how to change or remove an object annotation with kubectl annotate.

• Annotation updates and removal: Describe how to change an existing annotation and how to remove one using kubectl annotate.
  Why it matters: These two syntax details distinguish updating an annotation from removing it.

Key terms: kubectl annotate, --overwrite, annotation key

7.6 Summary

This summary explains how namespaces, labels, selectors, and annotations organize and identify Kubernetes objects.