API Reference - v1.5.0 v1

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

Name	Description	Type
`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 - mandatory	string
`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

Backup

Backup is the Schema for the backups API

Name	Description	Type
`metadata`		metav1.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-status	BackupSpec
`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-status	BackupStatus

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

Name	Description	Type
`barmanObjectStore`	The configuration for the barman-cloud tool suite	*BarmanObjectStoreConfiguration

BackupList

BackupList contains a list of Backup

Name	Description	Type
`metadata`	Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	metav1.ListMeta
`items`	List of backups - mandatory	[]Backup

BackupSpec

BackupSpec defines the desired state of Backup

Name	Description	Type
`cluster`	The cluster to backup	LocalObjectReference

BackupStatus

BackupStatus defines the observed state of Backup

Name	Description	Type
`s3Credentials`	The credentials to use to upload data to S3 - mandatory	S3Credentials
`endpointURL`	Endpoint to be used to upload data to the cloud, overriding the automatic endpoint discovery	string
`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 - mandatory	string
`serverName`	The server name on S3, the cluster name is used if this parameter is omitted	string
`encryption`	Encryption method required to S3 API	string
`backupId`	The ID of the Barman backup	string
`phase`	The last backup status	BackupPhase
`startedAt`	When the backup was started	*metav1.Time
`stoppedAt`	When the backup was terminated	*metav1.Time
`beginWal`	The starting WAL	string
`endWal`	The ending WAL	string
`beginLSN`	The starting xlog	string
`endLSN`	The ending xlog	string
`error`	The detected error	string
`commandOutput`	Unused. Retained for compatibility with old versions.	string
`commandError`	The backup command output in case of error	string

BarmanObjectStoreConfiguration

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

Name	Description	Type
`s3Credentials`	The credentials to use to upload data to S3 - mandatory	S3Credentials
`endpointURL`	Endpoint to be used to upload data to the cloud, overriding the automatic endpoint discovery	string
`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 - mandatory	string
`serverName`	The server name on S3, the cluster name is used if this parameter is omitted	string
`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.

Name	Description	Type
`initdb`	Bootstrap the cluster via initdb	*BootstrapInitDB
`recovery`	Bootstrap the cluster from a backup	*BootstrapRecovery
`pg_basebackup`	Bootstrap 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.

Name	Description	Type
`database`	Name of the database used by the application. Default: `app`. - mandatory	string
`owner`	Name of the owner of the database in the instance to be used by applications. Defaults to the value of the `database` key. - mandatory	string
`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

BootstrapPgBaseBackup

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

Name	Description	Type
`source`	The name of the server of which we need to take a physical backup - mandatory	string

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.

Name	Description	Type
`backup`	The backup we need to restore - mandatory	LocalObjectReference
`recoveryTarget`	By 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.

Name	Description	Type
`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
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.

Name	Description	Type
`clientCASecret`	The secret containing the Client CA certificate. This secret contains a self-signed CA and is used to sign TLS certificates used for client authentication.

Contains:

ca.crt: CA that should be used to validate the client certificate, used as ssl_ca_file. - ca.key: key used to sign client SSL certs. | string
replicationTLSSecret | The secret of type kubernetes.io/tls containing the TLS client certificate to authenticate as streaming_replica user. | string
expirations | Expiration dates for all certificates. | map[string]string

Cluster

Cluster is the Schema for the PostgreSQL API

Name	Description	Type
`metadata`		metav1.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-status	ClusterSpec
`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-status	ClusterStatus

ClusterList

ClusterList contains a list of Cluster

Name	Description	Type
`metadata`	Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	metav1.ListMeta
`items`	List of clusters - mandatory	[]Cluster

ClusterSpec

ClusterSpec defines the desired state of Cluster

Name	Description	Type
`description`	Description of this PostgreSQL cluster	string
`imageName`	Name of the container image, supporting both tags (`<image>:<tag>`) and digests for deterministic and repeatable deployments (`<image>:<tag>@sha256:<digestValue>`)	string
`postgresUID`	The UID of the `postgres` user inside the image, defaults to `26`	int64
`postgresGID`	The GID of the `postgres` user inside the image, defaults to `26`	int64
`instances`	Number of instances required in the cluster - mandatory	int32
`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 server	PostgresConfiguration
`bootstrap`	Instructions to bootstrap this cluster	*BootstrapConfiguration
`superuserSecret`	The secret containing the superuser password. If not defined a new secret will be created with a randomly generated password	*LocalObjectReference
`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 instances	StorageConfiguration
`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 Pods	AffinityConfiguration
`resources`	Resources requirements of every generated Pod. Please refer to https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for more information.	corev1.ResourceRequirements
`primaryUpdateStrategy`	Strategy 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
`nodeMaintenanceWindow`	Define 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
`monitoring`	The configuration of the monitoring infrastructure of this cluster	*MonitoringConfiguration
`externalClusters`	The list of external clusters which are used in the configuration	[]ExternalCluster

ClusterStatus

ClusterStatus defines the observed state of Cluster

Name	Description	Type
`instances`	Total number of instances in the cluster	int32
`readyInstances`	Total number of ready instances in the cluster	int32
`instancesStatus`	Instances status	map[utils.PodStatus][]string
`latestGeneratedNode`	ID of the latest generated node (used to avoid node name clashing)	int32
`currentPrimary`	Current primary instance	string
`targetPrimary`	Target primary instance, this is different from the previous one during a switchover or a failover	string
`pvcCount`	How many PVCs have been created by this cluster	int32
`jobCount`	How many Jobs have been created by this cluster	int32
`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
`licenseStatus`	Status of the license	licensekey.Status
`writeService`	Current write pod	string
`readService`	Current list of read pods	string
`phase`	Current phase of the cluster	string
`phaseReason`	Reason for the current phase	string
`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 data	SecretsResourceVersion
`certificates`	The configuration for the CA and related certificates, initialized with defaults.	CertificatesStatus

ConfigMapKeySelector

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

Name	Description	Type
`key`	The key to select - mandatory	string

DataBackupConfiguration

DataBackupConfiguration is the configuration of the backup of the data directory

Name	Description	Type
`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:kms`	EncryptionType
`immediateCheckpoint`	Control 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

ExternalCluster

ExternalCluster represents the connection parameters of an external server which is used in the cluster configuration

Name	Description	Type
`name`	The server name, required - mandatory	string
`connectionParameters`	The list of connection parameters, such as dbname, host, username, etc	map[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

LocalObjectReference

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

Name	Description	Type
`name`	Name of the referent. - mandatory	string

MonitoringConfiguration

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

Name	Description	Type
`customQueriesConfigMap`	The 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.

Name	Description	Type
`inProgress`	Is there a node maintenance activity in progress? - mandatory	bool
`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

Name	Description	Type
`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

RecoveryTarget

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

Name	Description	Type
`targetTLI`	The target timeline ("latest", "current" or a positive integer)	string
`targetXID`	The target transaction ID	string
`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 PostgreSQL	string
`targetImmediate`	End recovery as soon as a consistent state is reached	*bool
`exclusive`	Set the target to be exclusive (defaults to true)	*bool

RollingUpdateStatus

RollingUpdateStatus contains the information about an instance which is being updated

Name	Description	Type
`imageName`	The image which we put into the Pod - mandatory	string
`startedAt`	When the update has been started	metav1.Time

S3Credentials

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

Name	Description	Type
`accessKeyId`	The reference to the access key id - mandatory	SecretKeySelector
`secretAccessKey`	The reference to the secret access key - mandatory	SecretKeySelector

ScheduledBackup

ScheduledBackup is the Schema for the scheduledbackups API

Name	Description	Type
`metadata`		metav1.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-status	ScheduledBackupSpec
`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-status	ScheduledBackupStatus

ScheduledBackupList

ScheduledBackupList contains a list of ScheduledBackup

Name	Description	Type
`metadata`	Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	metav1.ListMeta
`items`	List of clusters - mandatory	[]ScheduledBackup

ScheduledBackupSpec

ScheduledBackupSpec defines the desired state of ScheduledBackup

Name	Description	Type
`suspend`	If this backup is suspended of not	*bool
`schedule`	The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron. - mandatory	string
`cluster`	The cluster to backup	LocalObjectReference

ScheduledBackupStatus

ScheduledBackupStatus defines the observed state of ScheduledBackup

Name	Description	Type
`lastCheckTime`	The latest time the schedule	*metav1.Time
`lastScheduleTime`	Information when was the last time that backup was successfully scheduled.	*metav1.Time
`nextScheduleTime`	Next time we will run a backup	*metav1.Time

SecretKeySelector

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

Name	Description	Type
`key`	The key to select - mandatory	string

SecretsResourceVersion

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

Name	Description	Type
`superuserSecretVersion`	The resource version of the "postgres" user secret - mandatory	string
`replicationSecretVersion`	The resource version of the "streaming_replication" user secret - mandatory	string
`applicationSecretVersion`	The resource version of the "app" user secret - mandatory	string
`caSecretVersion`	Unused. Retained for compatibility with old versions.	string
`clientCaSecretVersion`	The resource version of the PostgreSQL client-side CA secret version - mandatory	string
`serverCaSecretVersion`	The resource version of the PostgreSQL server-side CA secret version - mandatory	string
`serverSecretVersion`	The resource version of the PostgreSQL server-side secret version - mandatory	string

StorageConfiguration

StorageConfiguration is the configuration of the storage of the PostgreSQL instances

Name	Description	Type
`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. - mandatory	string
`resizeInUseVolumes`	Resize 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

Name	Description	Type
`compression`	Compress 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:kms`	EncryptionType

← Prev

API Reference - v1.5.1

↑ Up

API Reference - v1.24.1

API Reference - v1.4.0