Labels and annotations v1
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.
Info
For more information, see the Kubernetes documentation on annotations and labels.
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 for Kubernetes 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).
Note
Label and annotation inheritance is the technique adopted by EDB Postgres for Kubernetes instead of alternative approaches such as pod templates.
Predefined labels
These predefined labels are managed by EDB Postgres for Kubernetes.
k8s.enterprisedb.io/backupDate
: The date of the backup in ISO 8601 format (YYYYMMDD
)
k8s.enterprisedb.io/backupName
: Backup identifier, available only on Backup
and VolumeSnapshot
resources
k8s.enterprisedb.io/backupMonth
: The year/month when a backup was taken
k8s.enterprisedb.io/backupTimeline
: The timeline of the instance when a backup was taken
k8s.enterprisedb.io/backupYear
: The year a backup was taken
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/onlineBackup
: Whether the backup is online (hot) or taken when Postgres is down (cold)
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.
role
- deprecated
: Whether the instance running in a pod is a primary
or a replica
.
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
: Whether the instance running in a pod is a primary
or a replica
.
Predefined annotations
These predefined annotations are managed by EDB Postgres for Kubernetes.
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.
k8s.enterprisedb.io/backupEndWAL
: The WAL at the conclusion of a backup.
k8s.enterprisedb.io/backupStartTime
: The time a backup started.
k8s.enterprisedb.io/backupStartWAL
: The WAL at the start of a backup.
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/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/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
: When set to disabled
on a Cluster
, the operator prevents instances
from being restarted in case of drift in the PodSpec.
PodSpec drift could be due, for example, to:
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 true
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/skipEmptyWalArchiveCheck
: When set to true
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.
kubectl.kubernetes.io/restartedAt
: When available, the time of last requested restart of a Postgres cluster.
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
, andworkload
Note
Feel free to select the names that most suit your context for both
annotations and labels. You can also use wildcards
in naming and adopt strategies like using mycompany/*
for all labels
or setting annotations starting with mycompany/
to be inherited.
Defining cluster's metadata
When defining the cluster, before any resource is deployed, you can set the metadata as follows:
Once the cluster is deployed, you can verify, for example, that the labels were correctly set in the pods:
Current limitations
Currently, EDB Postgres for Kubernetes 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.