Annotations vs labels in Kubernetes - CLI Comparison

Introduction

Kubernetes uses labels and annotations to add extra information to objects. Labels help group and select objects, while annotations store non-identifying metadata.

When you want to organize pods by environment like development or production using labels.

When you need to add a description or contact info to a pod without affecting its selection.

When you want to filter services or deployments based on labels for updates or scaling.

When you want to store build or version details on a pod without changing its behavior.

When you want to track deployment history or debugging info using annotations.

Config File - pod.yaml

pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
  labels:
    environment: production
    app: my-app
  annotations:
    description: "This pod runs the main application."
    contact: "[e-mail]"
spec:
  containers:
  - name: my-container
    image: nginx:1.23.3

metadata.labels are key-value pairs used to identify and select this pod for grouping or filtering.

metadata.annotations store extra information that does not affect pod selection or behavior.

Commands

This command creates the pod with the specified labels and annotations so Kubernetes can manage it accordingly.

Terminal

kubectl apply -f pod.yaml

Expected Output

pod/example-pod created

This command lists pods and shows their labels, helping you see how pods are grouped.

Terminal

kubectl get pods --show-labels

Expected Output

NAME          READY   STATUS    RESTARTS   AGE     LABELS

example-pod   1/1     Running   0          10s     environment=production,app=my-app

→

--show-labels - Displays labels of each pod in the list

This command shows detailed information about the pod, including annotations which are not shown in the basic list.

Terminal

kubectl describe pod example-pod

Expected Output

Name:         example-pod

Namespace:    default

Labels:       environment=production

              app=my-app

Annotations:  description=This pod runs the main application.

              contact=[e-mail]

Status:       Running

Containers:

  my-container:

    Image:  nginx:1.23.3

    State:  Running

    Ready:  True

Key Concept

Labels are for identifying and selecting objects, while annotations store extra information that does not affect selection or behavior.

Common Mistakes

Using annotations when you need to select or filter objects.

Annotations are not indexed and cannot be used to select or group objects, so filtering will fail.

Use labels for any information you want to filter or select objects by.

Putting large or sensitive data in labels.

Labels have size limits and are visible in selectors, so large or sensitive data can cause errors or leaks.

Store large or sensitive metadata in annotations instead.

Summary

Labels help group and select Kubernetes objects like pods.

Annotations store extra metadata that does not affect object selection.

Use kubectl commands to apply, view labels, and describe annotations on pods.