Labels are key-value pairs attached to Kubernetes resources that enable flexible organization, identification, and selection. Unlike Annotations, labels are designed for identification and are used by selectors to query and group resources.
Purpose and Design
Labels enable organizing resources across multiple orthogonal dimensions simultaneously. A Pod might have labels for:
- Application tier (frontend, backend, database)
- Environment (dev, staging, production)
- Version (v1.2.3)
- Team ownership (team-search, team-checkout)
This multi-dimensional organization allows different systems and processes to slice resources in different ways, all using the same underlying label data.
Selection Mechanism
Label Selectors are the query language for labels. They enable resources to find other resources dynamically:
- Services use label selectors to identify which Pods to route traffic to
- ReplicaSets use selectors to determine which Pods they manage
- Namespace-scoped queries can filter resources by any label combination
This selection-based approach is central to distributed primitives - rather than hardcoded references, resources discover each other through flexible queries.
Common Label Patterns
Application Identity
app: shopping-cart
component: cacheVersion and Release
version: "2.1.0"
release: stableEnvironment and Tier
environment: production
tier: frontendLabels vs Annotations
While both are metadata, they serve different purposes:
Labels are for:
- Identifying resources
- Querying and selection
- Organizing and grouping
- Human-readable organization
Annotations are for:
- Non-identifying metadata
- Tool-specific data
- Machine-readable information
- Build/release/deployment details
Organizational Scope
Within Namespaces, labels provide finer-grained organization. While namespaces create hard boundaries, labels create soft, overlapping categories within those boundaries.
Labels also enable ResourceQuotas and LimitRanges to apply selectively to subsets of resources within a namespace.