Kubernetes Labels and Annotations
Tags: kubernetes, devops, infrastructureascode
Published: 2023-09-02 18:53:26

## Labels

Label allows to add meaningful marking attributes to the system or users on the Kubernetes resources, so as to facilitate the group management of the Kubernetes resources. These attribute pairs do not directly have semantics for Kubernetes core components, but may be indirectly processed by Kubernetes core components to produce effects. For example: the user adds some labels to the pod or node, and then configures some scheduling policies, and the Kubernetes scheduler will perform scheduling based on these label information.

Label is convenient for selection and query by recording indicative attributes. Two options are supported:

- equality:
  - `=` : selected resources must have a label key, and the values must be equal.
  - `==` : selected resources must have a label key, and the values must be equal.
  - `!=` : selected resource does not have a label key, or has a label key, but the values are not equal.

- set:
  - `in` : selected resource must have a label key, and the value must be within the scope of the collection.
  - `notin` : selected resource does not have a label key, or has a label key, but the value is not within the collection range.
  - `exists` : The selected resource must have a label key, and the value is not checked. Adding before the Label key `!means` that it does not exist, and the selected resource must not have a label key.

Label selection supports multi-condition query, and multiple conditions are `,` separated by. For example: `partition,environment notin (qa)` Indicates that the query has `partition` a label, and has `environment` a label but `environment` is not `qa` a resource.

### The grammar

Label key consists of two parts: optional prefix and name, which are `/` connected by. Compare their grammatical rules below:

|   | Label Prefix  | Label Name  |
|---|---|---|
| Existence  | Optional  | required  |
| Max lenght  | 253  |  63 |
| Character  | DNS  | Alphanumeric  |
| Seperator  | `.`  | `-`, `_` , `.`   |
| Restriction  | End with `/`  | Begin and end with an alphanumeric character  |

> `kubernetes.io/`and `k8s.io/` are two prefixes reserved by Kubernetes for its own core components, which are not allowed to be used by users.

Label value has the same syntax rules as label name.

## Annotations

Annotations allow arbitrary non-identifying metadata to be attached to Kubernetes resources to record some attributes of the resources. These metadata are mainly for tools or libraries to extract information, and are generally not directly open to users. The vast majority of open source projects based on Kubernetes do not depend on DB, and can fully use the capabilities of Kubernetes to meet the demand for DB. For data that needs to be persisted, in addition to defining CRD, another common practice is to store data in annotation.

Since the positioning of the annotation is to attach any non-identifying metadata to the Kubernetes resource, there is no restriction on the value except that the key has the same restrictions as the label key: it can be long or short, structured or unstructured , which can contain any characters.

### Labels and Annotations Comparison

Through the introduction of labels and annotations above, let's make a comprehensive comparison of them:

|   | Labels | Annotations  |
|---|---|---|
| Usage | Identifying metadata for efficient queries and watches | Attach arbitrary non-identifying metadata to Kubernetes resources |
| Selectable| Yes | No |
| Keys  | Label key syntax | Label key syntax |
| Values  | Label value syntax	  | Arbitrary  |

## Best Practices

- The platform must use a label with a prefix, and the prefix is strictly defined according to information such as organization, product, and resource.
- Labels without a prefix are reserved for user use.
- Add appropriate labels to all resources, and eventually these labels will improve the efficiency of resource management.

## Reference

- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)
- [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
- [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)
- [Labels and Annotations Best Practices](https://helm.sh/docs/chart_best_practices/labels/)