Labels, Selectors & Annotations

kubernetes kubernetes/kcna

‘Chapter 6. Labels and Annotations’
—Brendan Burns, “Kubernetes: Up & Running”

Core Idea

Labels are queryable key/value tags that group objects, selectors turn those tags into selections, and annotations hold non-identifying metadata meant for tools, not queries.

• Labels: apply, modify, and remove them; they are the foundation for grouping objects.
• Selectors: the types (equality and set-based) and the operators that drive them.
• Annotations: same shape as labels, but explicitly not for filtering or differentiating pods.

Labels are key/value pairs that can be attached to Kubernetes objects such as Pods and ReplicaSets. They can be arbitrary and are useful for attaching identifying information to Kubernetes objects. Labels provide the foundation for grouping objects.

Annotations, on the other hand, provide a storage mechanism that resembles labels: key/value pairs designed to hold non-identifying information that tools and libraries can leverage. Unlike labels, annotations are not meant for querying, filtering, or otherwise differentiating Pods from each other.

Labels

• Key-value pair
• Maximum length = 63 chars
• Must start and end with an alphanumeric¹ characters.
• permit to use -,_, and . between chars.

Applying labels

kubectl run alpaca-prod \ 
--image=gcr.io/kuar-demo/kuard-amd64:blue \ 
--replicas=2 \ 
--labels="ver=1,app=alpaca,env=prod"

Modifying Labels

kubectl label deployments alpaca-test "canary=true"

Warning

the kubectl label command will only change the label on the deployment itself; it won’t affect any objects that the deployment creates, such as ReplicaSets and Pods. To change those, you’ll need to change the template embedded in the deployment

Remove Labels

kubectl label deployments alpaca-test "canary-"

Selectors

Selectors in Kubernetes are used to identify and manage groups of resources by matching specific labels. They are essential for connecting components like Pods, Services, ReplicaSets, and Deployments.

kubectl get pods --selector="ver=2"

Types of Selectors:

1. Equality-Based Selectors:
   • Match resources with labels that are exactly equal to or not equal to specified values.
   • Example:

matchLabels:
    app: my-app

Matches all resources with the label app: my-app.

1. Set-Based Selectors:
   • Match resources whose labels satisfy a set condition (e.g., in, notIn, exists).
   • Example:

matchExpressions:
- key: environment
  operator: In
  values: 
  - production
  - staging

Matches resources where the environment label is either production or staging.

Selector Operators

Operator	Description
key=value	key is set to value
key!=value	key is not set to value
key in (value1, value2)	key is one of value1 or value2
key notin (value1, value2)	key is not one of value1 or value2
key	key is set
!key	key is not set

kubectl get pods -l 'ver=2,!canary'

Annotations

While labels are used to identify and group objects, annotations are used to provide extra information about where an object came from, how to use it, or policy around that object.

There is overlap, and it is a matter of taste as to when to use an annotation or a label. When in doubt, add information to an object as an annotation and promote it to a label if you find yourself wanting to use it in a selector.

Annotations are used in various places in Kubernetes, with the primary use case being rolling deployments. During rolling deployments, annotations are used to track rollout status and provide the necessary information required to roll back a deployment to a previous state.

...
metadata: 
	annotations: 
		example.com/icon-url: "https://example.com/icon.png" 
...

Footnotes

1. alphanumeric characters are the 26 letters from A to Z and the 10 Arabic numerals are from 0 to 9. ↩