Labels and annotations¶

Labels and annotations are rather similar but differ in purpose.

Labels are used by Kubernetes to identify and select objects. They enable filtering and grouping, allowing users to apply selectors for operations like deployments or scaling.

Annotations are assigning additional non-identifying information that doesn’t affect how Kubernetes processes resources. They store descriptive information like deployment history, monitoring configurations or external integrations.

The following diagram illustrates this difference:

graph TD
    A[Custom Resource] --> B[Operator]
    B --> C[Kubernetes resources]
    C --> D[Labels]
    C --> E[Annotations]
    D --> F[Selection]
    D --> G[Grouping]
    E --> H[External tools]
    E --> I[Documentation]

Both Labels and Annotations are assigned to the following objects:

Custom Resource Definitions
Custom Resources
Deployments
Services
StatefulSets
PVCs
Pods
ConfigMaps and Secrets
Backup jobs for scheduled backups

When to use labels and annotations¶

Use Labels when:

The information is used for object selection
The data is used for grouping or filtering
The information is used by Kubernetes controllers
The data is used for operational purposes

Use Annotations when:

The information is for external tools
The information is used for debugging
The data is used for monitoring configuration

Labels and annotations used by Percona Operator for MongoDB¶

Labels¶

Name	Objects	Description	Example values
`app.kubernetes.io/name`	Services, StatefulSets, Deployments, etc.	Specifies the name of the application for selectors and grouping	percona-server-mongodb
`app.kubernetes.io/instance`	Pods, Services, StatefulSets, Deployments	Identifies a specific instance of the application	my-cluster-name
`app.kubernetes.io/managed-by`	Services, StatefulSets	Indicates the controller managing the object	percona-server-mongodb-operator
`app.kubernetes.io/component`	Pods, Services, StatefulSets	Specifies the component within the application	mongod, mongos, arbiter, external-service , crd
`app.kubernetes.io/part-of`	Services, StatefulSets	Indicates the higher-level application the object belongs to	percona-server-mongodb
`app.kubernetes.io/version`	CustomResourceDefinition	Specifies the version of the Percona Server for MongoDB Operator.	v1.21.0
`app.kubernetes.io/replset`	CustomResourceDefinition	Specifies replica set name in Percona Server for MongoDB Operator.	rs0
`percona.com/backup-ancestor`	Custom Resource	Specifies the name of the backup that was used as a base for the current backup	my-cluster-name-backup-2025-05-23
`percona.com/backup-type`	Custom Resource	Specifies the type of backup being performed (e.g. cron for scheduled backups)	cron
`percona.com/cluster`	Custom Resource	Identifies the MongoDB cluster instance	my-cluster-name
`rack`	Pods, Services, Deployments, StatefulSets	Identifies topology or rack awareness, often for scheduling or affinity	`rack-22`

Annotations¶

Name	Associated resources	Description	Example values
`iam.amazonaws.com/role`	Pod, PVC, Service	Assigns an AWS IAM role to the resource for permissions.	`role-arn`
`service.beta.kubernetes.io/aws-load-balancer-backend-protocol`	Service	Specifies protocol for AWS load balancer backend.	`http`
`percona.com/last-applied-tls`	Services	Stores the hash of the last applied TLS configuration for the service
`percona.com/last-applied-secret`	Secrets	Stores the hash of the last applied user Secret configuration
`percona.com/configuration-hash`	Services	Used to track and validate configuration changes in the MySQL cluster components	`percona.com/last-applied-secret: "hashvalue"`
`percona.com/last-config-hash`	Services	Stores the hash of the most recent configuration
`percona.com/ssl-hash`	Pods	Stores the hash of the most recent TLS configuration
`percona.com/ssl-internal-hash`	Pods	Stores the hash of the most recent TLS configuration for internal communication
`percona.com/passwords-updated`	Secrets	Indicates when passwords were last updated in the Secret

Setting labels and annotations in the Custom Resource¶

You can define both Labels and Annotations as key-value pairs in the metadata section of a YAML manifest for a specific resource.

Set labels and annotations for Pods¶

To specify labels and annotations for Percona Server for MongoDB Pods, use the replsets.<name>.annotations /replsets.<name>.labels, sharding.configsvrReplSet.annotations / sharding.configsvrReplSet.labels and sharding.mongos.annotations / sharding.mongos.labels options in the deploy/cr.yaml Custom Resource. The example configuration for Percona Server for MongoDB database instances looks as follows:

apiVersion: psmdb.percona.com/v1
kind: PerconaServerMongoDB
spec:
  replsets:
  - name: rs0
    annotations:
      iam.amazonaws.com/role: role-arn
    labels:
      rack: rack-22 
    ...

Set labels and annotations for Services¶

To annotate Services, use the replsets.<name>.expose.annotations / replsets.<name>.expose.labels, sharding.configsvrReplSet.expose.annotations / sharding.configsvrReplSet.expose.labels and sharding.mongos.expose.annotations / sharding.mongos.expose.labels options in the deploy/cr.yaml Custom Resource. The example configuration for mongos is:

spec:
  sharding:
    mongos:
      expose:
        annotations:
          service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http
        labels:
          rack: rack-22

Querying labels and annotations¶

To check which labels are attached to a specific object, use the additional --show-labels option of the kubectl get command.

For example, to see the Operator version associated with a Custom Resource Definition, use the following command:

$ kubectl get crd perconaservermongodbs.psmdb.percona.com --show-labels

Sample output

NAME                                      CREATED AT             LABELS
perconaservermongodbs.psmdb.percona.com   2025-09-18T08:27:53Z   app.kubernetes.io/component=crd,app.kubernetes.io/name=percona-server-mongodb,app.kubernetes.io/part-of=percona-server-mongodb-operator,app.kubernetes.io/version=v1.21.0

To check annotations associated with an object, use the following command:

$ kubectl get <resource> <resource-name> -o jsonpath='{.metadata.annotations}'

For example:

$ kubectl get pod my-cluster-name-rs0-0 -o jsonpath='{.metadata.annotations}'

Specifying labels and annotations ignored by the Operator¶

Sometimes various Kubernetes flavors can add their own annotations to the Services managed by the Operator.

The Operator keeps track of all changes to its objects and can remove annotations that it didn’t create.

If there are no annotations or labels in the Custom Resource expose.* subsections, the Operator does nothing if a new label or annotation is added to the Service object.

If the Service per Pod mode is not used, the Operator won’t remove any annotations and labels from any Services related to this expose subsection. Though, it is still possible to add annotations and labels via the Custom Resource in this case. Use the appropriate expose.serviceAnnotations and expose.serviceLabels fields.

Else, if the Service per Pod mode is active, the Operator removes unknown annotations and labels from Services created by the Operator for Pods.

Yet it is still possible to specify which annotations and labels the Operator should keep. It is useful if a cloud provider adds own labels and annotations. Or you may have custom automation tools that add own labels or annotations and you need to keep them.

List these labels and annotations in the spec.ignoreAnnotations or spec.ignoreLabels fields of the deploy/cr.yaml, as follows:

spec:
  ignoreAnnotations:
    - some.custom.cloud.annotation/smth
  ignoreLabels:
    - some.custom.cloud.label/smth
...

The label and annotation values must exactly match the ones defined for the Service to be kept.

Last update: 2025-10-25