Mastering Kubernetes from Scratch Part 12 - Understanding Labels and Annotations

Introduction to Labels and Annotations

Introduction

In Kubernetes, organizing and managing resources efficiently is crucial. Labels and annotations are two powerful tools for this. They allow you to assign metadata to Kubernetes objects like Pods, Services, and Deployments. While both use key-value pairs, they serve different purposes. We’ll explore them in this chapter.

What Are Labels?

Labels are key-value pairs that help you organize, select, and filter Kubernetes objects. They allow you to group resources based on specific attributes. For example, you can label Pods by application type, environment, or tier.

Creating Labels

• Imperatively:

  $ kubectl label pods <pod-name> app=myapp ver=a environment=production

• Declaratively:

  apiVersion: v1
  kind: Pod
  metadata:
    name: labeled-pod
    namespace: learning-k8s
    labels:
      app: myapp
      ver: a
      environment: production
  spec:
    containers:
      - name: app-container
        image: nginx

Working with Labels

• Show Labels: You can display labels of all Pods with the following command:

$ kubectl get pods --show-labels -n learning-k8s

Sample output:

NAME                READY   STATUS    RESTARTS       AGE     LABELS
my-example   1/1     Running   0              16m     type=B

• Add a Label: You can add a label to a running Pod:

$ kubectl label pod labeled-pod tier=frontend -n learning-k8s

• Change a Label: You can update an existing label with the --overwrite flag:

$ kubectl label pod labeled-pod tier=backend --overwrite -n learning-k8s

Label Selectors

Labels become useful when combined with selectors. Label selectors allow you to filter resources based on their labels.

For example, to list Pods labeled with tier=backend:

$ kubectl get pods -l tier=backend --show-labels -n learning-k8s

Label selectors are especially helpful in scenarios like network policies, where you might apply rules to only certain Pods based on their labels.

What Are Annotations?

Annotations are also key-value pairs, but unlike labels, they store non-identifying metadata. They are typically used for descriptive or operational information, such as Git commit hashes or release notes. Annotations cannot be used for selecting or filtering resources like labels.

How to Use Annotations

Annotations are added in the YAML manifest under the metadata.annotations section.

For example, add annotations to a Pod:

apiVersion: v1
kind: Pod
metadata:
  name: annotated-pod
  namespace: learning-k8s
  annotations:
    description: "This is a demo pod for learning annotations"
    contact: "admin@example.com"
spec:
  containers:
    - name: app-container
      image: nginx

Adding and Modifying Annotations

You can add or update annotations using the kubectl annotate command. For example, to add a purpose annotation:

$ kubectl annotate pod annotated-pod purpose=test -n learning-k8s

To view the updated annotations, use:

$ kubectl describe pod annotated-pod -n learning-k8s |  grep -C 2 Annotations:
Start Time:       Wed, 27 Nov 2024 16:05:28 +0100
Labels:           <none>
Annotations:      contact: admin@example.com
                  description: This is a demo pod for learning annotations
                  purpose: test

Reserved Annotations

Kubernetes and its extensions use reserved annotations to define behavior or configuration settings. For example, to enforce security standards on Pods in a namespace, you can use the following annotation:

pod-security.kubernetes.io/enforce: "baseline"

This annotation ensures that all Pods in the namespace adhere to the baseline security policy.

Conclusion

In this chapter, you learned how labels and annotations work. Although they are similar, they serve different purposes. Labels help you organize and select resources. Annotations, on the other hand, provide extra metadata without affecting how Kubernetes handles the resources.

As you can see, the main difference is that you cannot use Annotations to query resources.