Skip to main content
Hello and welcome! I’m Mumshad Mannambeth, and in this article we explore how Kubernetes leverages labels, selectors, and annotations to efficiently organize and manage objects within a cluster. Understanding these concepts is crucial for maintaining large-scale, dynamic environments. Labels and selectors offer a systematic approach for grouping and filtering objects. Think of them like product filters in an online store or YouTube video tags; you attach specific properties (labels) to each item and then use selectors to filter items based on those properties. This helps when you want to narrow down a collection—for instance, filtering for green animals or green birds from a larger set. In Kubernetes, objects such as Pods, Services, ReplicaSets, and Deployments are often created simultaneously. Over time, as clusters grow to include hundreds or thousands of these objects, using labels and selectors to group and locate them by attributes like type, application, or functionality is essential.
The image shows various colorful shapes and patterns under the title "Labels & Selectors in Kubernetes."
For each Kubernetes object, you can attach labels (e.g., app, function, etc.). When selecting objects, you define a condition—such as app equals “App1”—to filter exactly the objects you need.
The image illustrates "Labels & Selectors in Kubernetes" using various colored shapes representing different applications (APP1 to APP5).
Consider the following diagram that demonstrates how you can label objects with attributes like “Front-end,” “Auth,” and “DB” and then filter them accordingly:
The image shows a diagram with labeled shapes representing different applications and their functions, such as "Front-end," "Auth," and "DB."

​
Specifying Labels in Kubernetes

Labels are specified in a Pod definition file under the metadata section as key-value pairs. For example: 
apiVersion: v1
kind: Pod
metadata:
  name: simple-webapp
  labels:
    app: App1
    function: Front-end
spec:
  containers:
  - name: simple-webapp
    image: simple-webapp
    ports:
    - containerPort: 8080
Once the Pod is created, use the following command to select it based on its label: 
kubectl get pods --selector app=App1
The output might look similar to: 
NAME            READY   STATUS      RESTARTS   AGE
simple-webapp   0/1     Completed   0          1d

​
Using Labels and Selectors with ReplicaSets

Kubernetes objects use labels and selectors to form relationships. For instance, when deploying a ReplicaSet that manages multiple Pods, each Pod’s definition includes labels that the ReplicaSet uses to identify and manage them. See the example below of a ReplicaSet definition: 
apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: simple-webapp
  labels:
    app: App1
    function: Front-end
  annotations:
    buildversion: "1.34"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: App1
  template:
    metadata:
      labels:
        app: App1
        function: Front-end
    spec:
      containers:
      - name: simple-webapp
        image: simple-webapp
In the ReplicaSet configuration above:
  • The labels in the ReplicaSet metadata describe its properties.
  • The selector matches the Pods based on labels.
  • The labels in the Pod template (metadata.labels) specify which Pods the ReplicaSet should manage.
  • Annotations, like buildversion: "1.34", are used for storing metadata that does not affect selection.
Beginners often confuse the labels on the ReplicaSet with those on the Pods. Remember, the ReplicaSet’s selector is key—it connects the ReplicaSet to the corresponding Pods based on matching labels. Using a single common label (e.g., app: App1) will cause the ReplicaSet to manage only those Pods. For finer control, additional labels can be added to avoid unintentional matches. Whenever other objects (such as Services) need to identify these Pods, they use selectors that match the labels assigned directly to the Pods.

​
Understanding Annotations

While labels and selectors are used for grouping and selection, annotations are designed for storing non-identifying metadata. This metadata might include tool information, version numbers, build details, or contact information. Annotations provide additional context for integrations, debugging, and information sharing without affecting how objects are grouped or selected. In our ReplicaSet example, the annotation buildversion: "1.34" demonstrates how version-specific metadata can be coupled with object definitions.
Annotations are especially useful for external systems or processes that require insight into the object’s metadata without impacting the operational logic in Kubernetes.
That concludes our comprehensive review of labels, selectors, and annotations. Practice these concepts to enhance your expertise on how Kubernetes organizes and manages its objects. For further reading, visit the following resources:

Watch Video

Practice Lab