Labels and Annotations v1.30.1

Resources in Kubernetes are organized in a flat structure, with no hierarchical information or relationship between them. However, such resources and objects can be linked together and put in relationship through labels and annotations.

In brief:

• An annotation is used to assign additional non-identifying information to resources with the goal of facilitating integration with external tools.
• A label is used to group objects and query them through the Kubernetes native selector capability.

You can select one or more labels or annotations to use in your EDB Postgres® AI for CloudNativePG™ Cluster deployments. Then you need to configure the operator so that when you define these labels or annotations in a cluster's metadata, they're inherited by all resources created by it (including pods).

Predefined labels

EDB Postgres® AI for CloudNativePG™ Cluster manages the following predefined labels:

• k8s.enterprisedb.io/backupDate

  The date of the backup in ISO 8601 format (YYYYMMDD). This label is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/backupName

  Backup identifier. This label is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/backupMonth

  The year/month when a backup was taken. This label is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/backupTimeline

  The timeline of the instance when a backup was taken. This label is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/backupYear

  The year a backup was taken. This label is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/cluster

  Name of the cluster.

• k8s.enterprisedb.io/immediateBackup

  Applied to a Backup resource if the backup is the first one created from a ScheduledBackup object having immediate set to true.

• k8s.enterprisedb.io/instanceName

  Name of the PostgreSQL instance (replaces the old and deprecated postgresql label).

• k8s.enterprisedb.io/jobRole

  Role of the job (that is, import, initdb, join, ...)

• k8s.enterprisedb.io/majorVersion

  Integer PostgreSQL major version of the backup's data directory (for example, 17). This label is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/onlineBackup

  Whether the backup is online (hot) or taken when Postgres is down (cold). This label is available only on VolumeSnapshot resources.

• postgresql

  deprecated, Name of the PostgreSQL instance. Use k8s.enterprisedb.io/instanceName instead

• k8s.enterprisedb.io/podRole

  Distinguishes pods dedicated to pooler deployment from those used for database instances.

• k8s.enterprisedb.io/poolerName

  Name of the PgBouncer pooler.

• k8s.enterprisedb.io/pvcRole

  Purpose of the PVC, such as PG_DATA or PG_WAL.

• k8s.enterprisedb.io/reload

  Available on ConfigMap and Secret resources. When set to true, a change in the resource is automatically reloaded by the operator.

• k8s.enterprisedb.io/userType

  Specifies the type of PostgreSQL user associated with the Secret, either superuser (Postgres superuser access) or app (application-level user in EDB Postgres® AI for CloudNativePG™ Cluster terminology), and is limited to the default users created by EDB Postgres® AI for CloudNativePG™ Cluster (typically postgres and app).

• role - deprecated****

  Role of the instance running in a pod: primary, replica, or unhealthy. The unhealthy value is transient: the operator sets it on the old primary during a failover or switchover and clears it automatically once the transition completes. This label is deprecated, you should use k8s.enterprisedb.io/instanceRole instead.

• k8s.enterprisedb.io/scheduled-backup

  When available, name of the ScheduledBackup resource that created a given Backup object.

• k8s.enterprisedb.io/instanceRole

  Role of the instance running in a pod: primary, replica, or unhealthy. The unhealthy value is transient: the operator sets it on the old primary during a failover or switchover and clears it automatically once the transition completes.

• app.kubernetes.io/managed-by

  Name of the manager. It will always be cloudnative-pg. Available across all EDB Postgres® AI for CloudNativePG™ Cluster managed resources.

• app.kubernetes.io/name

  Name of the application. It will always be postgresql. Available on pods, jobs, deployments, services, persistentVolumeClaims, volumeSnapshots, podDisruptionBudgets, podMonitors.

• app.kubernetes.io/component

  Name of the component (database, pooler, ...). Available on pods, jobs, deployments, services, persistentVolumeClaims, volumeSnapshots, podDisruptionBudgets, podMonitors.

• app.kubernetes.io/instance

  Name of the owning Cluster resource. Available on pods, jobs, deployments, services, volumeSnapshots, podDisruptionBudgets, podMonitors.

• app.kubernetes.io/version

  Major version of PostgreSQL. Available on pods, jobs, services, volumeSnapshots, podDisruptionBudgets, podMonitors.

Predefined annotations

EDB Postgres® AI for CloudNativePG™ Cluster manages the following predefined annotations:

• container.apparmor.security.beta.kubernetes.io/*

  Name of the AppArmor profile to apply to the named container. See AppArmor for details.

• k8s.enterprisedb.io/backupEndTime

  The time a backup ended. This annotation is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/backupEndWAL

  The WAL at the conclusion of a backup. This annotation is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/backupStartTime

  The time a backup started.

• k8s.enterprisedb.io/backupStartWAL

  The WAL at the start of a backup. This annotation is available only on VolumeSnapshot resources.

• k8s.enterprisedb.io/coredumpFilter

  Filter to control the coredump of Postgres processes, expressed with a bitmask. By default it's set to 0x31 to exclude shared memory segments from the dump. See PostgreSQL core dumps for more information.

• k8s.enterprisedb.io/clusterManifest

  Manifest of the Cluster owning this resource (such as a PVC). This label replaces the old, deprecated k8s.enterprisedb.io/hibernateClusterManifest label.

• k8s.enterprisedb.io/fencedInstances

  List of the instances that need to be fenced, expressed in JSON format. The whole cluster is fenced if the list contains the * element.

• k8s.enterprisedb.io/forceLegacyBackup

  Applied to a Cluster resource for testing purposes only, to simulate the behavior of barman-cloud-backup prior to version 3.4 (Jan 2023) when the --name option wasn't available.

• k8s.enterprisedb.io/hash

  The hash value of the resource.

• k8s.enterprisedb.io/hibernation

  Applied to a Cluster resource to control the declarative hibernation feature. Allowed values are on and off.

• k8s.enterprisedb.io/managedSecrets

  Pull secrets managed by the operator and automatically set in the ServiceAccount resources for each Postgres cluster.

• k8s.enterprisedb.io/nodeSerial

  On a pod resource, identifies the serial number of the instance within the Postgres cluster.

• k8s.enterprisedb.io/operatorVersion

  Version of the operator.

• k8s.enterprisedb.io/passwordPassthrough

  When set to enabled on a basic-auth Secret consumed by the operator (superuser, application user, or a managed-role password secret), the operator forwards the password value verbatim in the CREATE/ALTER ROLE statement instead of SCRAM-SHA-256 encoding it operator-side. PostgreSQL then encodes the value according to its own password_encryption setting. See Opting out of operator-side encoding.

• k8s.enterprisedb.io/pgControldata

  Output of the pg_controldata command. This annotation replaces the old, deprecated k8s.enterprisedb.io/hibernatePgControlData annotation.

• k8s.enterprisedb.io/podEnvHash

  Deprecated, as the k8s.enterprisedb.io/podSpec annotation now also contains the pod environment.

• k8s.enterprisedb.io/podPatch

  Annotation can be applied on a Cluster resource.

  When set to a JSON-patch formatted patch, the patch will be applied to the instance Pods. The patch can modify any field of the Pod specification, including security-sensitive fields. The operator validates only that the patch is syntactically correct and applicable.

  As with all Cluster fields that affect Pod specifications, enforcement of security constraints is delegated to the Kubernetes admission control chain. See the Trust Model and Security Boundaries section for details.

  ⚠️ WARNING: This feature may introduce discrepancies between the operator's expectations and Kubernetes behavior. Use with caution and only as a last resort.

  IMPORTANT: adding or changing this annotation won't trigger a rolling deployment of the generated Pods. The latter can be triggered manually by the user with kubectl cnp restart.

• k8s.enterprisedb.io/podSpec

  Snapshot of the spec of the pod generated by the operator. This annotation replaces the old, deprecated k8s.enterprisedb.io/podEnvHash annotation.

• k8s.enterprisedb.io/poolerSpecHash

  Hash of the pooler resource.

• k8s.enterprisedb.io/pvcStatus

  Current status of the PVC: initializing, ready, or detached.

• k8s.enterprisedb.io/reconcilePodSpec

  Annotation can be applied to a Cluster or Pooler to prevent restarts.

  When set to disabled on a Cluster, the operator prevents instances from restarting due to changes in the PodSpec. This includes changes to:

  • Topology or affinity
  • Scheduler
  • Volumes or containers

  When set to disabled on a Pooler, the operator restricts any modifications to the deployment specification, except for changes to spec.instances.

• k8s.enterprisedb.io/reconciliationLoop

  When set to disabled on a Cluster, the operator prevents the reconciliation loop from running.

• k8s.enterprisedb.io/reloadedAt

  Contains the latest cluster reload time. reload is triggered by the user through a plugin.

• k8s.enterprisedb.io/skipEmptyWalArchiveCheck

  When set to enabled on a Cluster resource, the operator disables the check that ensures that the WAL archive is empty before writing data. Use at your own risk.

• k8s.enterprisedb.io/skipWalArchiving

  When set to enabled on a Cluster resource, the operator disables WAL archiving. This will set archive_mode to off and require a restart of all PostgreSQL instances. Use at your own risk.

• k8s.enterprisedb.io/snapshotStartTime

  The time a snapshot started.

• k8s.enterprisedb.io/snapshotEndTime

  The time a snapshot was marked as ready to use.

• k8s.enterprisedb.io/validation

  When set to disabled on a EDB Postgres® AI for CloudNativePG™ Cluster-managed custom resource, the validation webhook allows all changes without restriction.

  ⚠️ WARNING: Disabling validation may permit unsafe or destructive operations. Use this setting with caution and at your own risk.

• k8s.enterprisedb.io/volumeSnapshotDeadline

  Applied to Backup and ScheduledBackup resources, allows you to control how long the operator should retry recoverable errors before considering the volume snapshot backup failed. In minutes, defaulting to 10.

• kubectl.kubernetes.io/restartedAt

  When available, the time of last requested restart of a Postgres cluster.

• alpha.k8s.enterprisedb.io/unrecoverable

  Experimental annotation applied to a Pod running a PostgreSQL instance. It instructs the operator to delete the Pod and all its associated PVCs. The instance will then be recreated according to the configured join strategy. The annotation is honored regardless of the instance's state, so it also takes effect on a Pod that is Pending, Running but not ready, or Terminating. When a Terminating Pod has passed its deletion deadline (the deletion request time plus its termination grace period), the operator force removes it so that its PVCs can be deleted and the instance recreated. This annotation can only be used on instances that are neither the current primary nor the designated target primary, which stay excluded even when marked unrecoverable.

  ⚠️ WARNING: Force removing a Pod on an unreachable node does not stop any process that might still be running there, and whether the underlying volumes are detached depends on the storage driver. This is acceptable for this annotation, whose contract already forfeits the instance's data.

Prerequisites

By default, no label or annotation defined in the cluster's metadata is inherited by the associated resources. To enable label/annotation inheritance, follow the instructions provided in Operator configuration.

The following continues from that example and limits it to the following:

• Annotations: categories
• Labels: app, environment, and workload

Defining cluster's metadata

When defining the cluster, before any resource is deployed, you can set the metadata as follows:

apiVersion: postgresql.k8s.enterprisedb.io/v1
kind: Cluster
metadata:
  name: cluster-example
  annotations:
    categories: database
  labels:
    environment: production
    workload: database
    app: sso
spec:
     # ... <snip>

Once the cluster is deployed, you can verify, for example, that the labels were correctly set in the pods:

kubectl get pods --show-labels

Current limitations

Currently, EDB Postgres® AI for CloudNativePG™ Cluster doesn't automatically propagate labels or annotations deletions. Therefore, when an annotation or label is removed from a cluster that was previously propagated to the underlying pods, the operator doesn't remove it on the associated resources.