Labels and annotations

Labels and annotations are used to attach additional metadata information to Kubernetes resources.

Labels and annotations are rather similar. The difference between them is that labels are used by Kubernetes to identify and select objects, while annotations are assigning additional non-identifying information to resources. Therefore, typical role of Annotations is facilitating integration with some external tools.

Setting labels and annotations in the Custom Resource

You can set labels and/or annotations as key/value string pairs in the Custom Resource metadata section of the deploy/cr.yaml. For PostgreSQL, pgBouncer and pgBackRest Pods, use instances.metadata.annotations/instances.metadata.labels, proxy.pgbouncer.metadata.annotations/proxy.pgbouncer.metadata.labels, or backups.pgbackrest.metadata.annotations/backups.pgbackrest.metadata.labels keys as follows:

apiVersion: pgv2.percona.com/v2
kind: PerconaPGCluster
...
spec:
...
  instances:
   - name: instance1
     replicas: 3
     metadata:
      annotations:
        my-annotation: value1
      labels:
        my-label: value2
    ...

For PostgreSQL and pgBouncer Services, use expose.annotations/expose.labels or proxy.pgbouncer.expose.annotations/proxy.pgbouncer.expose.labels keys as follows:

apiVersion: pgv2.percona.com/v2
kind: PerconaPGCluster
...
spec:
  ...
  expose:
    annotations:
      my-annotation: value1
    labels:
      my-label: value2
    ...

You can also use the top-level spec metadata.annotations and metadata.labels options to set annotations and labels at a global level, for all resources created by the Operator:

apiVersion: pgv2.percona.com/v2
kind: PerconaPGCluster
...
spec:
  ...
  metadata:
    annotations:
      my-global-annotation: value1
    labels:
      my-global-label: value2
  ...

The easiest way to check which labels are attached to a specific object with is using the additional --show-labels option of the kubectl get command. Checking the annotations is not much more difficult: it can be done as in the following example:

$ kubectl get service cluster1-pgbouncer -o jsonpath='{.metadata.annotations}'

Settings labels and annotations to the Operator Pod

You can assign labels and/or annotations to the Pod of the Operator itself by editing the deploy/operator.yaml configuration file before applying it during the installation.

apiVersion: apps/v1
kind: Deployment
...
spec:
...
  template:
    metadata:
      labels:
        app.kubernetes.io/component: operator
        app.kubernetes.io/instance: percona-postgresql-operator
        app.kubernetes.io/name: percona-postgresql-operator
        app.kubernetes.io/part-of: percona-postgresql-operator
        pgv2.percona.com/control-plane: postgres-operator
        ...

Special annotations

Metadata can be used as an additional way to influence the Operator behavior by setting special annotations.

Customizing Patroni version

Starting from the Operator 2.6.0, Percona distribution for PostgreSQL comes with Patroni 4.x, which introduces breaking changes compared to previously used 3.x versions. To maintain backward compatibility, the Operator needs to detect the Patroni version used in the image. For this, it runs a temporary Pod named cluster_name-patroni-version-check with the following default resources:

Resources:
   Requests:
     memory: 32Mi
     cpu: 50m
   Limits:
     memory: 64Mi
     cpu: 100m

User can disable this auto-detection feature by manually setting the Patroni version via the following annotation in the metadata part of the Custom Resource (it should contain “4” for Patroni 4.x or “3” for Patroni 3.x):

apiVersion: pgv2.percona.com/v2
kind: PerconaPGCluster
metadata:
  name: cluster1
  annotations:
    pgv2.percona.com/custom-patroni-version: "4"
  ...

---

Last update: 2025-06-17