Updated April 13, 2023
Kubernetes Annotations
Annotation is used to add additional metadata to Kubernetes objects that are non-identifying which means we cannot use the selector to query Kubernetes objects that have a specific annotation attach to it. In simple words, annotations are not used to identify and select Kubernetes objects. Annotation is not used by any Kubernetes component to perform any operation or any manipulation to the cluster. Annotation can be structured or unstructured and small or large. We can include metadata in annotation which has characters that are not allowed in labels. It provides additional information about the Kubernetes objects that can be used by tools and libraries. Annotations are not helpful for Kubernetes itself however it provides great help to users, people, or tools interacting with the Kubernetes objects as it holds useful information so that one can understand the objects properly and act it on wisely. For example, adding pager information of the responsible person, the link of a knowledge base article, etc.
How does Annotation Work in Kubernetes?
Annotations have key/value pairs same as labels. Annotation key consists of two parts, a prefix which is optional, and a name. These two parts are separated by a slash ‘/’. The name part is mandatory and it is not longer than 63 characters. It starts and ends with alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumeric in between. The prefix is optional however if specified it must be a DNS subdomain and length must be 253 characters or less and ends with a slash (/) If automated system components such as kube-controller-manager, kube-scheduler, kube-apiserver, kubectl or any other third party automation) add annotations to the end-user Kubernetes objects, it must specify a prefix. There are two reserved prefixes ‘kubernetes.io/’ and ‘k8s.io/’ for Kubernetes core components.
We use the “annotations” keyword to add an annotation to the object. Annotations are also key/value pairs like labels as shown below:
"metadata": {
"annotations": {
"key1" : "value1",
"key2" : "value2",
"key3" :"value3"
}
}Examples of Kubernetes Annotations
Let’s understand the examples of Kubernetes Annotations with Syntax.
Example 1
We have an nginx pod and we want to attach annotations like on-call person pager number, URL or name of the image registry and link of knowledge base article, etc. We can add these details under annotations under metadata primitives. There are default annotations attached by the ‘kubectl’ to every Kubernetes objects whether we attach annotations to the Kubernetes object or not. This annotation is the ‘kubectl.kubernetes.io/last-applied-configuration’. Let’s create a pod using below yaml file.
apiVersion: v1
kind: Pod
metadata:
name: nginx-web-server
labels:
env: prod
app: nginx-web
spec:
containers:
- name: nginx
image: nginx
ports:
- containerPort: 80After creating the pod, we use below two commands to check the attached annotation:
Syntax:
$kubectl describe <object_type> <object_name>$kubectl get <object_type> <object_name> -o custom-columns=<custom_column_name>:.metadata.annotationsExample 2
$kubectl describe pod nginx-web-server
$kubectl get pods nginx-web-server -o custom-columns=ANNOTATIONS:.metadata.annotations
Explanation: In the above example, there is no annotation attached to the pod however, there is an annotation attached to the pod and that is attached by Kubernetes core components as it has reserved prefix ‘kubernetes.io’ and name of the annotation is ‘last-applied-configuration’ which means it holds the last configuration applied to that object. The value of the annotation is truncated in the output we get from the first command. If we want to know or extract full value, we use the second command which output only key/value pairs of annotations.
Let’s create a pod and attach the annotations ‘oncallPager’, ‘imageregistry’, and ‘kbArticle’ as we discussed above. Below is the YAML configuration file for the same: –
apiVersion: v1
kind: Pod
metadata:
name: nginx-web-server
labels:
env: prod
app: nginx-web
annotations:
oncallPager: 111-222-3333
imageregistry: "https://hub.docker.com"
kbArticle: "https://kb.docs.example.com/KB34234"
spec:
containers:
- name: nginx
image: nginx
ports:
- containerPort: 80After deploying the above pod, we use the ‘kubectl describte’ command to see the attached annotations as shown in the below snapshot: –
Explanation: In the above snapshot, we can see the attached annotation as well as default annotation which is discussed earlier. Annotations are shown in alphabetic order and it does not matter how we have specified the annotations in the configuration file.
Let’s output only annotations and see how it looks like. Here is the output: –
Explanation: In the above snapshot, the key/value pairs are not that much clear as compare to earlier output and it will be difficult to find the key/value pairs if there are many annotations attached to a Kubernetes object.
Scenarios of Kubernetes Annotations
There are many scenarios where annotations are very useful. Some use cases are as below:
- We can add application build, release, or image information build number, release ID, git branch, registry address, image hashes, etc.
- We can attach name, version, and build information of client library or tool for debugging purposes.
- We can add user or tool/system information from where the objects originated. For example, objects can be created by automation tools like Jenkins in CI/CD model. It is very useful information who has created the Kubernetes object.
- Attaching fields managed by a declarative configuration layer as annotations help to differentiate them from default values set by clients or servers, and from auto-generated fields and fields set by auto-sizing or auto-scaling systems.
- We can also attach phone or pager numbers of the responsible person or directories or link where one can find that information if something bad happens.
- The link of the knowledge base article or article number can be also attached to troubleshoot known issues related to that object.
- We can add pointers to logging, monitoring, analytics, or audit repositories.
Conclusion
Kubernetes are similar to labels as it also has key/value pairs, however, it cannot be queried by Kubernetes itself but there are many tools that are configured to query objects based on their annotations, for example, Prometheus, third party tools, etc. Huge annotations do not the impact internal performance of Kubernetes so there are no keys and values constrained like labels.
Recommended Articles
We hope that this EDUCBA information on “Kubernetes Annotations” was beneficial to you. You can view EDUCBA’s recommended articles for more information.
