API Reference

Feedback

Cloud Native PostgreSQL extends the Kubernetes API defining the following custom resources:

All the resources are defined in the postgresql.k8s.enterprisedb.io/v1 API.

Please refer to the "Configuration Samples" page" of the documentation for examples of usage.

Below you will find a description of the defined resources:

AffinityConfiguration

AffinityConfiguration contains the info we need to create the affinity rules for Pods

NameDescriptionType
enablePodAntiAffinity Activates anti-affinity for the pods. The operator will define pods anti-affinity unless this field is explicitly set to false*bool
topologyKey TopologyKey to use for anti-affinity configuration. See k8s documentation for more info on that - mandatorystring
nodeSelector NodeSelector is map of key-value pairs used to define the nodes on which the pods can run. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/map[string]string
tolerations Tolerations is a list of Tolerations that should be set for all the pods, in order to allow them to run on tainted nodes. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/[]corev1.Toleration
podAntiAffinityType PodAntiAffinityType allows the user to decide whether pod anti-affinity between cluster instance has to be considered a strong requirement during scheduling or not. Allowed values are: "preferred" (default if empty) or "required". Setting it to "required", could lead to instances remaining pending until new kubernetes nodes are added if all the existing nodes don't match the required pod anti-affinity rule. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinitystring
additionalPodAntiAffinityAdditionalPodAntiAffinity allows to specify pod anti-affinity terms to be added to the ones generated by the operator if EnablePodAntiAffinity is set to true (default) or to be used exclusively if set to false.*corev1.PodAntiAffinity
additionalPodAffinity AdditionalPodAffinity allows to specify pod affinity terms to be passed to all the cluster's pods.*corev1.PodAffinity

AzureCredentials

AzureCredentials is the type for the credentials to be used to upload files to Azure Blob Storage. The connection string contains every needed information. If the connection string is not specified, we'll need the storage account name and also one (and only one) of:

  • storageKey - storageSasToken
NameDescriptionType
connectionStringThe connection string to be used*SecretKeySelector
storageAccount The storage account where to upload data*SecretKeySelector
storageKey The storage account key to be used in conjunction with the storage account name*SecretKeySelector
storageSasToken A shared-access-signature to be used in conjunction with the storage account name*SecretKeySelector

Backup

Backup is the Schema for the backups API

NameDescriptionType
metadatametav1.ObjectMeta
spec Specification of the desired behavior of the backup. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-statusBackupSpec
status Most recently observed status of the backup. This data may not be up to date. Populated by the system. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-statusBackupStatus

BackupConfiguration

BackupConfiguration defines how the backup of the cluster are taken. Currently the only supported backup method is barmanObjectStore. For details and examples refer to the Backup and Recovery section of the documentation

NameDescriptionType
barmanObjectStoreThe configuration for the barman-cloud tool suite*BarmanObjectStoreConfiguration

BackupList

BackupList contains a list of Backup

NameDescriptionType
metadataStandard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kindsmetav1.ListMeta
items List of backups - mandatory[]Backup

BackupSpec

BackupSpec defines the desired state of Backup

NameDescriptionType
clusterThe cluster to backupLocalObjectReference

BackupStatus

BackupStatus defines the observed state of Backup

NameDescriptionType
s3Credentials The credentials to be used to upload data to S3*S3Credentials
azureCredentialsThe credentials to be used to upload data to Azure Blob Storage*AzureCredentials
endpointURL Endpoint to be used to upload data to the cloud, overriding the automatic endpoint discoverystring
destinationPath The path where to store the backup (i.e. s3://bucket/path/to/folder) this path, with different destination folders, will be used for WALs and for data - mandatorystring
serverName The server name on S3, the cluster name is used if this parameter is omittedstring
encryption Encryption method required to S3 APIstring
backupId The ID of the Barman backupstring
phase The last backup statusBackupPhase
startedAt When the backup was started*metav1.Time
stoppedAt When the backup was terminated*metav1.Time
beginWal The starting WALstring
endWal The ending WALstring
beginLSN The starting xlogstring
endLSN The ending xlogstring
error The detected errorstring
commandOutput Unused. Retained for compatibility with old versions.string
commandError The backup command output in case of errorstring

BarmanObjectStoreConfiguration

BarmanObjectStoreConfiguration contains the backup configuration using Barman against an S3-compatible object storage

NameDescriptionType
s3Credentials The credentials to use to upload data to S3*S3Credentials
azureCredentialsThe credentials to use to upload data in Azure Blob Storage*AzureCredentials
endpointURL Endpoint to be used to upload data to the cloud, overriding the automatic endpoint discoverystring
endpointCA EndpointCA store the CA bundle of the barman endpoint. Useful when using self-signed certificates to avoid errors with certificate issuer and barman-cloud-wal-archive*SecretKeySelector
destinationPath The path where to store the backup (i.e. s3://bucket/path/to/folder) this path, with different destination folders, will be used for WALs and for data - mandatorystring
serverName The server name on S3, the cluster name is used if this parameter is omittedstring
wal The configuration for the backup of the WAL stream. When not defined, WAL files will be stored uncompressed and may be unencrypted in the object store, according to the bucket default policy.*WalBackupConfiguration
data The configuration to be used to backup the data files When not defined, base backups files will be stored uncompressed and may be unencrypted in the object store, according to the bucket default policy.*DataBackupConfiguration

BootstrapConfiguration

BootstrapConfiguration contains information about how to create the PostgreSQL cluster. Only a single bootstrap method can be defined among the supported ones. initdb will be used as the bootstrap method if left unspecified. Refer to the Bootstrap page of the documentation for more information.

NameDescriptionType
initdb Bootstrap the cluster via initdb*BootstrapInitDB
recovery Bootstrap the cluster from a backup*BootstrapRecovery
pg_basebackupBootstrap the cluster taking a physical backup of another compatible PostgreSQL instance*BootstrapPgBaseBackup

BootstrapInitDB

BootstrapInitDB is the configuration of the bootstrap process when initdb is used Refer to the Bootstrap page of the documentation for more information.

NameDescriptionType
database Name of the database used by the application. Default: app. - mandatorystring
owner Name of the owner of the database in the instance to be used by applications. Defaults to the value of the database key. - mandatorystring
secret Name of the secret containing the initial credentials for the owner of the user database. If empty a new secret will be created from scratch*LocalObjectReference
redwood If we need to enable/disable Redwood compatibility. Requires EPAS and for EPAS defaults to true*bool
options The list of options that must be passed to initdb when creating the cluster[]string
postInitSQLList of SQL queries to be executed as a superuser immediately after the cluster has been created - to be used with extreme care (by default empty)[]string

BootstrapPgBaseBackup

BootstrapPgBaseBackup contains the configuration required to take a physical backup of an existing PostgreSQL cluster

NameDescriptionType
sourceThe name of the server of which we need to take a physical backup - mandatorystring

BootstrapRecovery

BootstrapRecovery contains the configuration required to restore the backup with the specified name and, after having changed the password with the one chosen for the superuser, will use it to bootstrap a full cluster cloning all the instances from the restored primary. Refer to the Bootstrap page of the documentation for more information.

NameDescriptionType
backup The backup we need to restore*LocalObjectReference
source The external cluster whose backup we will restore. This is also used as the name of the folder under which the backup is stored, so it must be set to the name of the source clusterstring
recoveryTargetBy default, the recovery process applies all the available WAL files in the archive (full recovery). However, you can also end the recovery as soon as a consistent state is reached or recover to a point-in-time (PITR) by specifying a RecoveryTarget object, as expected by PostgreSQL (i.e., timestamp, transaction Id, LSN, ...). More info: https://www.postgresql.org/docs/current/runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET*RecoveryTarget

CertificatesConfiguration

CertificatesConfiguration contains the needed configurations to handle server certificates.

NameDescriptionType
serverCASecret The secret containing the Server CA certificate. If not defined, a new secret will be created with a self-signed CA and will be used to generate the TLS certificate ServerTLSSecret.

Contains:

- ca.crt: CA that should be used to validate the server certificate, used as sslrootcert in client connection strings.
- ca.key: key used to generate Server SSL certs, if ServerTLSSecret is provided, this can be omitted.
string
serverTLSSecret The secret of type kubernetes.io/tls containing the server TLS certificate and key that will be set as ssl_cert_file and ssl_key_file so that clients can connect to postgres securely. If not defined, ServerCASecret must provide also ca.key and a new secret will be created using the provided CA.string
replicationTLSSecretThe secret of type kubernetes.io/tls containing the client certificate to authenticate as the streaming_replica user. If not defined, ClientCASecret must provide also ca.key, and a new secret will be created using the provided CA.string
clientCASecret The secret containing the Client CA certificate. If not defined, a new secret will be created with a self-signed CA and will be used to generate all the client certificates.

Contains:

- ca.crt: CA that should be used to validate the client certificates, used as ssl_ca_file of all the instances.
- ca.key: key used to generate client certificates, if ReplicationTLSSecret is provided, this can be omitted.
string
serverAltDNSNames The list of the server alternative DNS names to be added to the generated server TLS certificates, when required.[]string

CertificatesStatus

CertificatesStatus contains configuration certificates and related expiration dates.

NameDescriptionType
expirationsExpiration dates for all certificates.map[string]string

Cluster

Cluster is the Schema for the PostgreSQL API

NameDescriptionType
metadatametav1.ObjectMeta
spec Specification of the desired behavior of the cluster. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-statusClusterSpec
status Most recently observed status of the cluster. This data may not be up to date. Populated by the system. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-statusClusterStatus

ClusterList

ClusterList contains a list of Cluster

NameDescriptionType
metadataStandard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kindsmetav1.ListMeta
items List of clusters - mandatory[]Cluster

ClusterSpec

ClusterSpec defines the desired state of Cluster

NameDescriptionType
description Description of this PostgreSQL clusterstring
imageName Name of the container image, supporting both tags (<image>:<tag>) and digests for deterministic and repeatable deployments (<image>:<tag>@sha256:<digestValue>)string
imagePullPolicy Image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-imagescorev1.PullPolicy
postgresUID The UID of the postgres user inside the image, defaults to 26int64
postgresGID The GID of the postgres user inside the image, defaults to 26int64
instances Number of instances required in the cluster - mandatoryint32
minSyncReplicas Minimum number of instances required in synchronous replication with the primary. Undefined or 0 allow writes to complete when no standby is available.int32
maxSyncReplicas The target value for the synchronous replication quorum, that can be decreased if the number of ready standbys is lower than this. Undefined or 0 disable synchronous replication.int32
postgresql Configuration of the PostgreSQL serverPostgresConfiguration
bootstrap Instructions to bootstrap this cluster*BootstrapConfiguration
replica Replica cluster configuration*ReplicaClusterConfiguration
superuserSecret The secret containing the superuser password. If not defined a new secret will be created with a randomly generated password*LocalObjectReference
enableSuperuserAccessWhen this option is enabled, the operator will use the SuperuserSecret to update the postgres user password (if the secret is not present, the operator will automatically create one). When this option is disabled, the operator will ignore the SuperuserSecret content, delete it when automatically created, and then blank the password of the postgres user by setting it to NULL. Enabled by default.*bool
certificates The configuration for the CA and related certificates*CertificatesConfiguration
imagePullSecrets The list of pull secrets to be used to pull the images. If the license key contains a pull secret that secret will be automatically included.[]LocalObjectReference
storage Configuration of the storage of the instancesStorageConfiguration
startDelay The time in seconds that is allowed for a PostgreSQL instance to successfully start up (default 30)int32
stopDelay The time in seconds that is allowed for a PostgreSQL instance node to gracefully shutdown (default 30)int32
affinity Affinity/Anti-affinity rules for PodsAffinityConfiguration
resources Resources requirements of every generated Pod. Please refer to https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for more information.corev1.ResourceRequirements
primaryUpdateStrategyStrategy to follow to upgrade the primary server during a rolling update procedure, after all replicas have been successfully updated: it can be automated (unsupervised - default) or manual (supervised)PrimaryUpdateStrategy
backup The configuration to be used for backups*BackupConfiguration
nodeMaintenanceWindowDefine a maintenance window for the Kubernetes nodes*NodeMaintenanceWindow
licenseKey The license key of the cluster. When empty, the cluster operates in trial mode and after the expiry date (default 30 days) the operator will cease any reconciliation attempt. For details, please refer to the license agreement that comes with the operator.string
licenseKeySecret The reference to the license key. When this is set it take precedence over LicenseKey.*corev1.SecretKeySelector
monitoring The configuration of the monitoring infrastructure of this cluster*MonitoringConfiguration
externalClusters The list of external clusters which are used in the configuration[]ExternalCluster
logLevel The instances' log level, one of the following values: error, info (default), debug, tracestring

ClusterStatus

ClusterStatus defines the observed state of Cluster

NameDescriptionType
instances Total number of instances in the clusterint32
readyInstances Total number of ready instances in the clusterint32
instancesStatus Instances statusmap[utils.PodStatus][]string
latestGeneratedNode ID of the latest generated node (used to avoid node name clashing)int32
currentPrimary Current primary instancestring
targetPrimary Target primary instance, this is different from the previous one during a switchover or a failoverstring
pvcCount How many PVCs have been created by this clusterint32
jobCount How many Jobs have been created by this clusterint32
danglingPVC List of all the PVCs created by this cluster and still available which are not attached to a Pod[]string
initializingPVC List of all the PVCs that are being initialized by this cluster[]string
healthyPVC List of all the PVCs not dangling nor initializing[]string
licenseStatus Status of the licenselicensekey.Status
writeService Current write podstring
readService Current list of read podsstring
phase Current phase of the clusterstring
phaseReason Reason for the current phasestring
secretsResourceVersion The list of resource versions of the secrets managed by the operator. Every change here is done in the interest of the instance manager, which will refresh the secret dataSecretsResourceVersion
configMapResourceVersion The list of resource versions of the configmaps, managed by the operator. Every change here is done in the interest of the instance manager, which will refresh the configmap dataConfigMapResourceVersion
certificates The configuration for the CA and related certificates, initialized with defaults.CertificatesStatus
firstRecoverabilityPoint The first recoverability point, stored as a date in RFC3339 formatstring
cloudNativePostgresqlCommitHashThe commit hash number of which this operator runningstring
currentPrimaryTimestamp The timestamp when the last actual promotion to primary has occurredstring
targetPrimaryTimestamp The timestamp when the last request for a new primary has occurredstring

ConfigMapKeySelector

ConfigMapKeySelector contains enough information to let you locate the key of a ConfigMap

NameDescriptionType
keyThe key to select - mandatorystring

ConfigMapResourceVersion

ConfigMapResourceVersion is the resource versions of the secrets managed by the operator

NameDescriptionType
metricsA map with the versions of all the config maps used to pass metrics. Map keys are the config map names, map values are the versionsmap[string]string

DataBackupConfiguration

DataBackupConfiguration is the configuration of the backup of the data directory

NameDescriptionType
compression Compress a backup file (a tar file per tablespace) while streaming it to the object store. Available options are empty string (no compression, default), gzip or bzip2.CompressionType
encryption Whenever to force the encryption of files (if the bucket is not already configured for that). Allowed options are empty string (use the bucket policy, default), AES256 and aws:kmsEncryptionType
immediateCheckpointControl whether the I/O workload for the backup initial checkpoint will be limited, according to the checkpoint_completion_target setting on the PostgreSQL server. If set to true, an immediate checkpoint will be used, meaning PostgreSQL will complete the checkpoint as soon as possible. false by default.bool
jobs The number of parallel jobs to be used to upload the backup, defaults to 2*int32

EPASConfiguration

EPASConfiguration contains EDB Postgres Advanced Server specific configurations

NameDescriptionType
auditIf true enables edb_audit loggingbool

ExternalCluster

ExternalCluster represents the connection parameters to an external cluster which is used in the other sections of the configuration

NameDescriptionType
name The server name, required - mandatorystring
connectionParametersThe list of connection parameters, such as dbname, host, username, etcmap[string]string
sslCert The reference to an SSL certificate to be used to connect to this instance*corev1.SecretKeySelector
sslKey The reference to an SSL private key to be used to connect to this instance*corev1.SecretKeySelector
sslRootCert The reference to an SSL CA public key to be used to connect to this instance*corev1.SecretKeySelector
password The reference to the password to be used to connect to the server*corev1.SecretKeySelector
barmanObjectStore The configuration for the barman-cloud tool suite*BarmanObjectStoreConfiguration

LocalObjectReference

LocalObjectReference contains enough information to let you locate a local object with a known type inside the same namespace

NameDescriptionType
nameName of the referent. - mandatorystring

MonitoringConfiguration

MonitoringConfiguration is the type containing all the monitoring configuration for a certain cluster

NameDescriptionType
customQueriesConfigMapThe list of config maps containing the custom queries[]ConfigMapKeySelector
customQueriesSecret The list of secrets containing the custom queries[]SecretKeySelector

NodeMaintenanceWindow

NodeMaintenanceWindow contains information that the operator will use while upgrading the underlying node.

This option is only useful when the chosen storage prevents the Pods from being freely moved across nodes.

NameDescriptionType
inProgressIs there a node maintenance activity in progress? - mandatorybool
reusePVC Reuse the existing PVC (wait for the node to come up again) or not (recreate it elsewhere) - mandatory*bool

PostgresConfiguration

PostgresConfiguration defines the PostgreSQL configuration

NameDescriptionType
parameters PostgreSQL configuration options (postgresql.conf)map[string]string
pg_hba PostgreSQL Host Based Authentication rules (lines to be appended to the pg_hba.conf file)[]string
epas EDB Postgres Advanced Server specific configurations*EPASConfiguration
promotionTimeout Specifies the maximum number of seconds to wait when promoting an instance to primaryint32
shared_preload_librariesLists of shared preload libraries to add to the default ones[]string

RecoveryTarget

RecoveryTarget allows to configure the moment where the recovery process will stop. All the target options except TargetTLI are mutually exclusive.

NameDescriptionType
targetTLI The target timeline ("latest", "current" or a positive integer)string
targetXID The target transaction IDstring
targetName The target name (to be previously created with pg_create_restore_point)string
targetLSN The target LSN (Log Sequence Number)string
targetTime The target time, in any unambiguous representation allowed by PostgreSQLstring
targetImmediateEnd recovery as soon as a consistent state is reached*bool
exclusive Set the target to be exclusive (defaults to true)*bool

ReplicaClusterConfiguration

ReplicaClusterConfiguration encapsulates the configuration of a replica cluster

NameDescriptionType
enabledIf replica mode is enabled, this cluster will be a replica of an existing cluster. A cluster of such type can be created only using bootstrap via pg_basebackup - mandatorybool
source The name of the external cluster which is the replication origin - mandatorystring

RollingUpdateStatus

RollingUpdateStatus contains the information about an instance which is being updated

NameDescriptionType
imageNameThe image which we put into the Pod - mandatorystring
startedAtWhen the update has been startedmetav1.Time

S3Credentials

S3Credentials is the type for the credentials to be used to upload files to S3

NameDescriptionType
accessKeyId The reference to the access key id - mandatorySecretKeySelector
secretAccessKeyThe reference to the secret access key - mandatorySecretKeySelector

ScheduledBackup

ScheduledBackup is the Schema for the scheduledbackups API

NameDescriptionType
metadatametav1.ObjectMeta
spec Specification of the desired behavior of the ScheduledBackup. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-statusScheduledBackupSpec
status Most recently observed status of the ScheduledBackup. This data may not be up to date. Populated by the system. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-statusScheduledBackupStatus

ScheduledBackupList

ScheduledBackupList contains a list of ScheduledBackup

NameDescriptionType
metadataStandard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kindsmetav1.ListMeta
items List of clusters - mandatory[]ScheduledBackup

ScheduledBackupSpec

ScheduledBackupSpec defines the desired state of ScheduledBackup

NameDescriptionType
suspend If this backup is suspended or not*bool
immediateIf the first backup has to be immediately start after creation or not*bool
schedule The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron. - mandatorystring
cluster The cluster to backupLocalObjectReference

ScheduledBackupStatus

ScheduledBackupStatus defines the observed state of ScheduledBackup

NameDescriptionType
lastCheckTime The latest time the schedule*metav1.Time
lastScheduleTimeInformation when was the last time that backup was successfully scheduled.*metav1.Time
nextScheduleTimeNext time we will run a backup*metav1.Time

SecretKeySelector

SecretKeySelector contains enough information to let you locate the key of a Secret

NameDescriptionType
keyThe key to select - mandatorystring

SecretsResourceVersion

SecretsResourceVersion is the resource versions of the secrets managed by the operator

NameDescriptionType
superuserSecretVersion The resource version of the "postgres" user secretstring
replicationSecretVersionThe resource version of the "streaming_replica" user secretstring
applicationSecretVersionThe resource version of the "app" user secretstring
caSecretVersion Unused. Retained for compatibility with old versions.string
clientCaSecretVersion The resource version of the PostgreSQL client-side CA secret versionstring
serverCaSecretVersion The resource version of the PostgreSQL server-side CA secret versionstring
serverSecretVersion The resource version of the PostgreSQL server-side secret versionstring
barmanEndpointCA The resource version of the Barman Endpoint CA if providedstring
metrics A map with the versions of all the secrets used to pass metrics. Map keys are the secret names, map values are the versionsmap[string]string

StorageConfiguration

StorageConfiguration is the configuration of the storage of the PostgreSQL instances

NameDescriptionType
storageClass StorageClass to use for database data (PGDATA). Applied after evaluating the PVC template, if available. If not specified, generated PVCs will be satisfied by the default storage class*string
size Size of the storage. Required if not already specified in the PVC template. Changes to this field are automatically reapplied to the created PVCs. Size cannot be decreased. - mandatorystring
resizeInUseVolumesResize existent PVCs, defaults to true*bool
pvcTemplate Template to be used to generate the Persistent Volume Claim*corev1.PersistentVolumeClaimSpec

WalBackupConfiguration

WalBackupConfiguration is the configuration of the backup of the WAL stream

NameDescriptionType
compressionCompress a WAL file before sending it to the object store. Available options are empty string (no compression, default), gzip or bzip2.CompressionType
encryption Whenever to force the encryption of files (if the bucket is not already configured for that). Allowed options are empty string (use the bucket policy, default), AES256 and aws:kmsEncryptionType

Could this page could be better? Report a problem or suggest an addition!