Labels and Annotations

Working with Labels and Annotations

A common set of labels can be applied to all Resources in a project by adding a labels or commonLabels entry to the kustomization.yaml file. Similarly, a common set of annotations can be applied to Resources with the commonAnnotations field.

Working with Labels

Add Labels

labels can be used to add labels to the metadata field of all Resources in a project. This will override values for label keys that already exist.

Here is an example of how to add labels to the metadata field.

Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

labels:
- pairs:
    someName: someValue
    owner: alice
    app: bingo

resources:
- deploy.yaml
- service.yaml

Create Deployment and Service manifests.

# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: example

Add labels with kustomize build.

kustomize build .

The output shows that the labels field is used to add labels to the metadata field of the Service and Deployment Resources.

apiVersion: v1
kind: Service
metadata:
  labels:
    app: bingo
    owner: alice
    someName: someValue
  name: example
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: bingo
    owner: alice
    someName: someValue
  name: example

Add Template Labels

labels.includeTemplates can be used to add labels to the template field of all applicable Resources in a project.

Here is an example of how to add labels to the template field of a Deployment.

Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

labels:
- pairs:
    someName: someValue
    owner: alice
    app: bingo
  includeTemplates: true

resources:
- deploy.yaml
- service.yaml

Create Deployment and Service manifests.

# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: example

Add labels with kustomize build.

kustomize build .

The output shows that labels are added to the metadata field and the labels.includeTemplates field is used to add labels to the template field of the Deployment. However, the Service Resource does not have a template field, and Kustomize does not add this field.

apiVersion: v1
kind: Service
metadata:
  labels:
    app: bingo
    owner: alice
    someName: someValue
  name: example
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: bingo
    owner: alice
    someName: someValue
  name: example
spec:
  template:
    metadata:
      labels:
        app: bingo
        owner: alice
        someName: someValue

Add Selector Labels

labels.includeSelectors can be used to add labels to the selector field of applicable Resources in a project. Note that this also adds labels to the template field for applicable Resources.

Labels added to the selector field should not be changed after Workload and Service Resources have been created in a cluster.

Here is an example of how to add labels to the selector field.

Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

labels:
- pairs:
    someName: someValue
    owner: alice
    app: bingo
  includeSelectors: true

resources:
- deploy.yaml
- service.yaml

Create Deployment and Service manifests.

# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: example

Add labels with kustomize build.

kustomize build .

The output shows that labels are added to the metadata field and the labels.includeSelectors field is used to add labels to the selector and template fields for applicable Resources. However, the Service Resource does not have a template field, and Kustomize does not add this field.

apiVersion: v1
kind: Service
metadata:
  labels:
    app: bingo
    owner: alice
    someName: someValue
  name: example
spec:
  selector:
    app: bingo
    owner: alice
    someName: someValue
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: bingo
    owner: alice
    someName: someValue
  name: example
spec:
  selector:
    matchLabels:
      app: bingo
      owner: alice
      someName: someValue
  template:
    metadata:
      labels:
        app: bingo
        owner: alice
        someName: someValue

The following example produces the same result. The commonLabels field is equivalent to using labels.includeSelectors.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

commonLabels:
  someName: someValue
  owner: alice
  app: bingo

resources:
- deploy.yaml
- service.yaml

Working with Annotations

Add Annotations

commonAnnotations can be used to add annotations to all Resources in a project. This will override values for annotations keys that already exist. Annotations are propagated to the Deployment Pod template.

Here is an example of how to add annotations to a Deployment.

Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

commonAnnotations:
  oncallPager: 800-867-5309

resources:
- deploy.yaml

Create a Deployment manifest.

# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example

Add annotations with kustomize build.

kustomize build .

The output shows that the commonAnnotations field is used to add annotations to a Deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example
  annotations:
    oncallPager: 800-867-5309
spec:
  template:
    metadata:
      annotations:
        oncallPager: 800-867-5309

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified November 25, 2023: Add common Tasks to documentation (#5383) (bfb00ecb)