3.3 Namespaces, Labels, Selectors & Annotations

3.3 Namespaces, Labels, Selectors & Annotations

As Kubernetes clusters expand to accommodate dozens of applications and multi-tenant engineering teams, managing resource organization, isolation, and metadata becomes vital. Kubernetes satisfies these management challenges using Namespaces, ResourceQuotas, LimitRanges, Labels, Selectors, and Annotations.

---

1. Virtual Isolation with Namespaces

A Namespace is a logical abstraction that divides a single physical Kubernetes cluster into multiple virtual clusters. Namespaces provide scoped naming boundaries, resource quota boundaries, and access control scopes (via Role-Based Access Control / RBAC).

Default Kubernetes Namespaces

Every fresh Kubernetes cluster starts with four standard system namespaces:

1. default: The fallback namespace for any object created without an explicit .metadata.namespace specification.
2. kube-system: The system namespace reserved for Kubernetes control plane components, system add-ons, CoreDNS, and ingress controllers.
3. kube-public: A readable namespace created automatically for resources that should be publicly discoverable across the whole cluster (e.g., cluster-info ConfigMap).
4. kube-node-lease: A specialized namespace holding Lease objects for worker nodes. Node heartbeats are updated here to reduce control plane traffic overhead.

[!NOTE] Namespaces scope cluster names (you cannot have two Pods named frontend in the default namespace, but you can have one frontend Pod in development and another frontend Pod in production). However, Namespaces do not provide network isolation by default; NetworkPolicies must be configured to block cross-namespace traffic.

---

2. Namespace Resource Management: ResourceQuota & LimitRange

To prevent one tenant or buggy microservice from exhausting all cluster resources in a shared cluster, administrators apply resource controls at the namespace level.

ResourceQuota

A ResourceQuota enforces aggregate resource consumption caps across an entire namespace. If a namespace reaches its quota, the API server rejects any further creation of objects that would exceed the defined caps.

ResourceQuotas can restrict:

• Compute Resources: Total CPU requests/limits (e.g., requests.cpu: "10", limits.cpu: "20") and total memory requests/limits.
• Storage Resources: Total PersistentVolumeClaim storage requests (e.g., requests.storage: 500Gi).
• Object Count Limits: Maximum total count of Pods, Services, ConfigMaps, Secrets, or Deployments.

LimitRange

While a ResourceQuota sets namespace-wide aggregate limits, a LimitRange enforces resource constraints at the individual Pod or container level within a namespace.

A LimitRange can:

• Enforce minimum and maximum CPU and memory requests/limits for individual containers.
• Define default resource requests and limits automatically injected into any container submitted without resource specifications.

apiVersion: v1
kind: ResourceQuota
metadata:
  name: dev-quota
  namespace: development
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 8Gi
    limits.cpu: "8"
    limits.memory: 16Gi
    pods: "10"
---
apiVersion: v1
kind: LimitRange
metadata:
  name: dev-limit-range
  namespace: development
spec:
  limits:
  - default:
      cpu: 500m
      memory: 512Mi
    defaultRequest:
      cpu: 250m
      memory: 256Mi
    type: Container

---

3. Metadata Identification: Labels vs. Annotations

Kubernetes objects can be tagged with key-value metadata pairs. However, Kubernetes makes a fundamental architectural distinction between Labels and Annotations.

Labels and Label Selectors

Labels are identifying key-value pairs attached to API objects (such as Pods, Nodes, and Services). They are intended to specify identifying attributes of objects that are meaningful and relevant to users, without implying semantic changes to the core system.

Labels are queried using Label Selectors to group and bind resources dynamically. There are two types of selectors:

1. Equality-Based Selectors: Filter resources using =, ==, or != operators.
   • Example: environment = production, tier != frontend
2. Set-Based Selectors: Filter resources using set operations (in, notin, exists).
   • Example: environment in (production, staging), tier notin (legacy)

Labels power core Kubernetes operations:

• Services use label selectors to route network traffic to matching Pod endpoints.
• Deployments use label selectors to discover and manage ReplicaSet Pods.
• kubectl CLI commands use selectors to target specific resources (kubectl get pods -l env=prod).

Annotations

Annotations are key-value pairs used to attach non-identifying, arbitrary metadata to objects. Unlike Labels, Annotations cannot be queried by label selectors and are not used by Kubernetes to identify or group objects.

Common annotation use cases include:

• Storing build info, git commit hashes, or release timestamps.
• Ingress controller configuration directives (e.g., nginx.ingress.kubernetes.io/rewrite-target: /).
• Storage provisioner options or container runtime parameters.
• Pointer fields for external management and orchestration tools.

---

4. Metadata Feature Comparison Matrix

apiVersion: v1
kind: Pod
metadata:
  name: order-service
  namespace: production
  labels:
    app.kubernetes.io/name: order-service
    app.kubernetes.io/tier: backend
    environment: production
  annotations:
    build.info/commit: "a1b2c3d4e5f6"
    prometheus.io/scrape: "true"
    prometheus.io/port: "8080"
spec:
  containers:
  - name: app
    image: order-service:v2.1.0