Setting Kubernetes Labels and Annotations

Helm chart is a popular method of packaging applications to be installed on the Kubernetes cluster. As Helm chart developers, we have to decide what configurations need to be made available to the customer and how should they be offered. In this article, we look at configuring labels and annotations. All Kubernetes objects should have a set of labels for external tools to identify and use them in a consistent manner. Specifying labels and annotations involves solving some key challenges.

1. What are the labels that should be common to all Kubernetes objects?
2. How to expose labels and annotations configuration parameters in values.yaml?
3. We cannot say upfront what all the possible labels and annotation parameter names that a customer might want for application Pods.
4. Allow customers to expose the services externally in the various ways that they might want.

Required Labels

The first challenge is to come up with a list of required labels. The official documentation provides a list of recommended labels. These labels are recommended for every object that we create and have a shared prefix:  app.kubernetes.io . Prefixes ensure that recommended labels do not get mixed up with custom labels defined by the customers. 

xxxxxxxxxx

metadata:

  labels:

    app.kubernetes.io/name: {{ template "chart.fullname" .}}

    helm.sh/chart: {{ template "chart.fullnameandversion" .}}

    app.kubernetes.io/instance: {{ .Release.Name }}

    app.kubernetes.io/managed-by: {{ .Release.Service }}

    app.kubernetes.io/component: my-component

    app.kubernetes.io/version: {{ .Chart.AppVersion }}

In addition to these, we need to have an organization-wide consensus on the mandatory set of labels.

Exposing Labels and Annotations Configuration

Next, we need to let customers specify their custom labels and annotations. This can be supported with toYaml:

xxxxxxxxxx

labels:

  {{- with .Values.my-service.extraLabels }}

  {{ toYaml . | indent 4 }}

  {{- end }}

This allows the customer to set additional labels in the custom values file such as:

x

my-service:

  extraLabels:

    name: project-name

    env: lab

    version: 1.0.0

    component: api-gateway

    part-of: application

    managed-by: orchestrator

    location-name: branch

Exposing Services Externally

Customers need to expose some services externally to the cluster via a LoadBalancer. This requires the services to be annotated with annotations specific to that LoadBalancer. For example, a customer may require the following annotations to support the F5 Load Balancer and services that need to be exposed externally to the cluster.

xxxxxxxxxx

annotations:

  app: application-name

  cis.f5.com/as3-tenant: tenant

  cis.f5.com/as-app: ingress

  cis.f5.com/as-pool: ingress-pool

This can be supported in a similar way as labels:

xxxxxxxxxx

annotations:

  {{- with .Values.my-service.annotations }}

  {{ toYaml . | indent 4 }}

  {{- end }}

With this background, we can set the labels and annotations for different Kubernetes Objects.

Deployment YAML

Labels will have mandatory labels as decided by the organization and extra labels from the customers and the same for annotations. The deployment file for an application should have labels and annotations as illustrated below.

x

labels:

    app.kubernetes.io/name: {{ template "chart.fullname" .}}

    helm.sh/chart: {{ template "chart.fullnameandversion" .}}

    app.kubernetes.io/instance: {{ .Release.Name }}

    app.kubernetes.io/managed-by: {{ .Release.Service }}

    app.kubernetes.io/component: my-component

    app.kubernetes.io/version: {{ .Chart.AppVersion }}

  {{- with .Values.extraLabels }}

    {{- toYaml . | nindent 4 }}

  {{- end }}

annotations:

  prometheus.io/path: /actuator/prometheus

  prometheus.io/port: '9000'

  prometheus.io/scrape: 'true'

  {{- with .Values.deploymentAnnotations }}

    {{- toYaml . | nindent 4 }}

  {{- end }}

Service YAML

Service with mandatory labels required of all Kubernetes objects and customer provided annotations.

x

labels:

    app.kubernetes.io/name: {{ template "chart.fullname" .}}

    helm.sh/chart: {{ template "chart.fullnameandversion" .}}

    app.kubernetes.io/instance: {{ .Release.Name }}

    app.kubernetes.io/managed-by: {{ .Release.Service }}

    app.kubernetes.io/component: my-component

    app.kubernetes.io/version: {{ .Chart.AppVersion }}

    {{- with .Values.extraLabels }}

      {{- toYaml . | nindent 4 }}

    {{- end }}

{{- if .Values.serviceAnnotations }}

annotations:

  {{ toYaml .Values.serviceAnnotations | indent 4 }}

{{- end }}

Other Objects

The other common Kubernetes Objects, e.g., Horizontal Pod Autoscalar, ConfigMap, Secrets should have the mandatory labels common to all objects.

xxxxxxxxxx

labels:

    app.kubernetes.io/name: {{ template "chart.fullname" .}}

    helm.sh/chart: {{ template "chart.fullnameandversion" .}}

    app.kubernetes.io/instance: {{ .Release.Name }}

    app.kubernetes.io/managed-by: {{ .Release.Service }}

    app.kubernetes.io/component: my-component

    app.kubernetes.io/version: {{ .Chart.AppVersion }}

Conclusion

Labels and annotations are one of the main foundations for Kubernetes. They are both ways of adding metadata to Kubernetes objects. Kubernetes labels allow us to identify, select, and operate on Kubernetes objects, whereas annotations are non-identifying metadata.

They are used by external tools to help them to provide extra functionalities. However, there are no standard practices enforced. In this article, we attempted to provide a guideline that will serve as best practices when labeling and annotating Kubernetes objects.