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.
- What are the labels that should be common to all Kubernetes objects?
- How to expose labels and annotations configuration parameters in values.yaml?
- We cannot say upfront what all the possible labels and annotation parameter names that a customer might want for application Pods.
- 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
version1.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.