Annotations in Kubernetes

In this blog post we’ll explore Annotations in general and how K8s uses it !

Introduction

We recently got a query from a course subscriber about “Annotations” and its need in Kubernetes.

Its seems a very genuine query from first time user. In his own words “Annotation is the concept , not able to understand, can you elaborate the concept?”

This query led me to write an elaborative blogpost about concept & origin of Annotations in Kubernetes and in general programming.

Annotation in Java

I won’t shy away in saying that Annotations of K8s are kinda borrowed from Java. One word to explain annotation is metadata. Metadata is data which describes other data. So annotations are metadata for code.But why we need Annotations?

In the words of Java programmers, Annotation is a special kind of Java construct used as metadata to decorate a class, method, field, parameter, variable, constructor, or package.

Annotations provide a standard way of defining metadata in code. Prior to annotations marker interfaces, transient keywords, document comments, etc were used to explain or provide identifiers for the code. But the introduction of annotations standardized this requirement.

As explained in the discussion here https://stackoverflow.com/questions/2036980/annotation-comment

Annotation is not a comment. An annotation is added to a field, class or method, using the syntax @Annotation. One of the best known annotations is @Override, used to signal a method is overriding one from a super class. For example:

public class MyClass {
  @Override
  public boolean equals(Object other) {
    //...
  }
}

Digging deep in search for content of Annotation in Java I find a very interesting piece of an article discussing Annotation vs Comments in Java.

A typical documentation comment is what normally appears in the beginning of any class definition. It's contains author name, version, date, last modified date, etc. So, a sample comment would be something like:-

/**Author: Geek
*Version: 1.0
*Date: 6/16/2008
*Last Modified Date: 6/16/2008
*...
*...
*/
class ClassName{
...
}

For the same purpose, we can define an annotation type as:-

@interface ClassHeaderAnnotation{
String author();
double version() default 1.0;
String date();
String lastModifiedDate();
......
}

Once, an annotation type has been defined, it can used as:-

@Documented // to include this info in the Javadoc
@ClassHeaderAnnotation(
author = "Geek",
version = "1.1", // or just leave this to have the default value
date = "6/16/2008",
lastModifiedDate = "6/16/2008",
......
)
class ClassName{
...
}

Annotations in Kubernetes

Enough of origin of the concept of annotation now we should see how & why the need for annotations arise in Kubernetes. As we all know Kubernetes also have labels which are also used to identify metadata.

Kubernetes labels and annotations are both ways of adding metadata to Kubernetes objects. The similarities end there, however. Kubernetes labels allow you to identify, select and operate on Kubernetes objects, whereas Annotations are non-identifying metadata and do none of these things.

If someone needs to have a deeper understanding of the project, reading threads of project-related GitHub issues is the best way to understand the thought process of a developer mindset. One 5-year-old Sept 2014 GitHub issue thread has details of the origin of annotations in K8s.

In a comment of this thread, why we need annotation is clearly explained.

It would be useful to be able to attach arbitrary non-identifying metadata. The API server would just hold on to the information for retrieval by tools, libraries, etc. — that is, by other API clients rather than the managed application’s containers themselves.

In the words of the author,

The immediate use case I have in mind is to store the configured desired state of each object, but other use cases include:

• build/release/image information (timestamps, release ids, git branch, PR numbers, image hashes, registry address, etc.)
• pointers to logging/monitoring/analytics/audit repos
• client library/tool information (e.g. for debugging purposes — name, version, build info)
• other user and/or tool/system provenance info, such as URLs of related objects from other ecosystem components
• lightweight rollout tool metadata (config and/or checkpoints)
• phone/pager number(s) of person(s) responsible, or directory entry where that info could be found, such as a team website

A better analogy of annotation in the real-world is when you see some doctor’s display board where they mention their educational qualifications like MBBS & MD. But generally, they don’t stop here & also include information like MBBS(IMS, BHU) & MD(General Medicine, AIIMS). The extra information provided in the above example about the institutes(IMS BHU, AIIMS, etc.) from where that doctor has done his courses is annotations.

So, explained further Labels are used to query & identify Kubernetes objects whereas annotations are used to provide non-idetifying extra information.

Following are some of the use-cases of Annotations in Kubernetes:-
– If there are multiple Ingress Controllers installed on your K8s cluster, then we choose the right one by putting our preference in ingress objects.
– They are used in helm deployments for providing rolling updates when ConfigMaps or Secrets change. For further understanding, you can refer to Helm tricks & tip docs.

Conclusion

Hence we can safely conclude that Kubernetes annotations serve the purpose of providing non-identifying metadata which can be used to get more elaborate context for an object.