API reference

Preview release v0.7.1

EDB Postgres Distributed for Kubernetes extends the Kubernetes API by defining the custom resources that follow.

All the resources are defined in the pgd.k8s.enterprisedb.io/v1beta1 API.

Backup

Backup configures the backup of cnp-pgd nodes

Name	Description	Type
`configuration`	The CNP configuration to be used for backup. ServerName value is reserved by the operator.	cnpv1.BackupConfiguration
`cron`	The scheduled backup for the data	cnpv1.ScheduledBackupSpec

BackupStatus

BackupStatus contains the current status of the pgd backup

Name	Description	Type
`clusterName`		string
`scheduledBackupName`		string

CNPStatus

CNPStatus contains any relevant status for the operator about CNP

Name	Description	Type
`dataInstances`		int32
`witnessInstances`		int32
`firstRecoverabilityPoints`	The recoverability points, keyed per CNP clusterName, as a date in RFC3339 format	map[string]string
`superUserSecretIsPresent`		bool
`applicationUserSecretIsPresent`		bool
`podDisruptionBudgetIsPresent`		bool

CertManagerTemplate

CertManagerTemplate contains the data to generate a certificate request

Name	Description	Type
`spec`	The Certificate object specification - mandatory	*certmanagerv1.CertificateSpec
`metadata`	The label and annotations metadata	Metadata

ClientCertConfiguration

ClientCertConfiguration contains the information to generate the certificate for the streaming_replica user

Name	Description	Type
`caCertSecret`	CACertSecret is the secret of the CA to be injected into the CloudNativePG configuration - mandatory	string
`certManager`	The cert-manager template used to generate the certificates	*CertManagerTemplate
`preProvisioned`	PreProvisioned contains how to fetch the pre-generated client certificates	*ClientPreProvisionedCertificates

ClientPreProvisionedCertificates

ClientPreProvisionedCertificates instruct how to fetch the pre-generated client certificates

Name	Description	Type
`streamingReplica`	StreamingReplica the pre-generated certificate for 'streaming_replica' user	*PreProvisionedCertificate

CnpBaseConfiguration

CnpBaseConfiguration contains the configuration parameters that can be applied to both CNP Witness and Data nodes

Name	Description	Type
`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
`storage`	Configuration of the storage of the instances - mandatory	cnpv1.StorageConfiguration
`walStorage`	Configuration of the WAL storage for the instances	*cnpv1.StorageConfiguration
`clusterMaxStartDelay`	The time in seconds that is allowed for a PostgreSQL instance to successfully start up (default 300)	int32
`affinity`	Affinity/Anti-affinity rules for Pods	cnpv1.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
`postgresql`	Configuration of the PostgreSQL server	cnpv1.PostgresConfiguration
`monitoring`	The configuration of the monitoring infrastructure of this cluster	*cnpv1.MonitoringConfiguration
`logLevel`	The instances' log level, one of the following values: error, warning, info (default), debug, trace	string
`serviceAccountTemplate`	The service account template to be passed to CNP	*cnpv1.ServiceAccountTemplate
`otel`	OpenTelemetry Configuration	OTELConfiguration
`postInitSQL`	List of SQL queries to be executed as a superuser immediately after a node has been created - to be used with extreme care (by default empty)	[]string
`postInitTemplateSQL`	List of SQL queries to be executed as a superuser in the `template1` after a node has been created - to be used with extreme care (by default empty)	[]string
`seccompProfile`	The SeccompProfile applied to every Pod and Container. Defaults to: `RuntimeDefault`	*corev1.SeccompProfile
`metadata`	Metadata applied exclusively to the generated Cluster resources. Useful for applying AppArmor profiles.	InheritedMetadata

CnpConfiguration

CnpConfiguration contains the configurations of the data nodes that will be injected into the resulting clusters composing the PGD group

Name	Description	Type
`enableSuperuserAccess`	When this option is enabled, the CNP operator will create or use the secret defined in the SuperuserSecret to allow superuser (postgres) access to the database. Disabled by default.	*bool
`superuserSecret`	The secret containing the superuser password. A new secret will be created with a randomly generated password if not defined. This field is only allowed in the CNP Instances configuration. A Witness Node will always use the same SuperuserSecret as the other instances.	*cnpv1.LocalObjectReference

ConnectivityConfiguration

ConnectivityConfiguration describes how to generate the services and certificates for the PGDGroup

Name	Description	Type
`dns`	Describes how the FQDN for the resources should be generated	RootDNSConfiguration
`tls`	The configuration of the TLS infrastructure - mandatory	TLSConfiguration
`nodeServiceTemplate`	Instructs how to generate the service for each node	*ServiceTemplate
`groupServiceTemplate`	Instructs how to generate the service for the PGDGroup	*ServiceTemplate
`proxyServiceTemplate`	Instructs how to generate the service pointing to the PGD Proxy	*ServiceTemplate

ConnectivityStatus

ConnectivityStatus contains any relevant status for the operator about Connectivity

Name	Description	Type
`replicationTLSCertificate`	ReplicationTLSCertificate is the name of the replication TLS certificate, if we have it	ReplicationCertificateStatus
`nodeTLSCertificates`	NodeTLSCertificates are the names of the certificates that have been created for the PGD nodes	[]NodeCertificateStatus
`unusedCertificates`	UnusedCertificates are the names of the certificates that we don't use anymore for the PGD nodes	[]string
`nodesWithoutCertificates`	NodesWithoutCertificates are the names of the nodes which have not a server certificate	[]string
`nodesNeedingServiceReconciliation`	NodesNeedingServiceReconciliation are the names of the nodes which have not a server certificate	[]string
`configurationHash`	ConfigurationHash is the hash code of the connectivity configuration, used to check if we had a change in the configuration or not	string

DNSConfiguration

DNSConfiguration describes how the FQDN for the resources should be generated

Name	Description	Type
`domain`	Contains the domain name of by all services in the PGDGroup. It is responsibility of the user to ensure that the value specified here matches with the rendered nodeServiceTemplate and groupServiceTemplate	string
`hostSuffix`	Contains an optional suffix to add to all the service names in the PGDGroup. The meaning of this setting it to allow the user to easily mark all the services created in a location for routing purpose (i.e., add a generic rule to CoreDNS to rewrite some service suffixes as local)	string

DiscoveryJobConfig

DiscoveryJobConfig contains a series of fields that configure the discovery job

Name	Description	Type
`delay`	Delay amount of time to sleep between retries, measured in seconds	int
`retries`	Retries how many times the operation should be retried	int
`timeout`	Timeout amount of time given to the operation to succeed, measured in seconds	int

InheritedMetadata

InheritedMetadata contains metadata to be inherited by all resources related to a Cluster

Name	Description	Type
`labels`		map[string]string
`annotations`		map[string]string

Metadata

Metadata is a structure similar to the metav1.ObjectMeta, but still parseable by controller-gen to create a suitable CRD for the user.

Name	Description	Type
`labels`	Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels	map[string]string
`annotations`	Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations	map[string]string

NameKindGroup

NameKindGroup a struct containing name kind and group

Name	Description	Type
`name`	- mandatory	string
`kind`	- mandatory	string
`group`	- mandatory	string

NodeCertificateStatus

NodeCertificateStatus encapsulate the status of the server certificate of a CNP node

Name	Description	Type
`nodeName`	NodeName is the name of the CNP cluster using this certificate - mandatory	string

NodeSummary

NodeSummary shows relevant info from bdr.node_summary

Name	Description	Type
`node_name`	Name of the node	string
`node_group_name`	NodeGroupName is the name of the joined group	string
`peer_state_name`	Consistent state of the node in human-readable form	string
`peer_target_state_name`	State which the node is trying to reach (during join or promotion)	string
`node_kind_name`	The kind of node: witness or data	NodeKindName

OTELConfiguration

OTELConfiguration is the configuration for external openTelemetry

Name	Description	Type
`metricsURL`	The OpenTelemetry HTTP endpoint URL to accept metrics data	string
`traceURL`	The OpenTelemetry HTTP endpoint URL to accept trace data	string
`traceEnable`	Whether to push trace data to OpenTelemetry traceUrl - mandatory	bool
`tls`	TLSConfiguration provides the TLS certificate configuration when MetricsURL and TraceURL are using HTTPS	OTELTLSConfiguration

OTELTLSConfiguration

OTELTLSConfiguration contains the certificate configuration for TLS connections to openTelemetry

Name	Description	Type
`caBundleSecretRef`	CABundleSecretRef is a reference to a secret field containing the CA bundle to verify the openTelemetry server certificate	*cnpv1.SecretKeySelector
`clientCertSecret`	ClientCertSecret is the name of the secret containing the client certificate used to connect to openTelemetry. It must contain both the standard "tls.crt" and "tls.key" files, encoded in PEM format.	*cnpv1.LocalObjectReference

PGDGroup

PGDGroup is the Schema for the pgdgroups API

Name	Description	Type
`metadata`		metav1.ObjectMeta
`spec`		PGDGroupSpec
`status`		PGDGroupStatus

PGDGroupCleanup

PGDGroupCleanup is the Schema for the pgdgroupcleanups API

Name	Description	Type
`metadata`		metav1.ObjectMeta
`spec`		PGDGroupCleanupSpec
`status`		PGDGroupCleanupStatus

PGDGroupCleanupList

PGDGroupCleanupList contains a list of PGDGroupCleanup

Name	Description	Type
`metadata`		metav1.ListMeta
`items`	- mandatory	[]PGDGroupCleanup

PGDGroupCleanupSpec

PGDGroupCleanupSpec defines the desired state of PGDGroupCleanup

Name	Description	Type
`executor`	- mandatory	string
`target`	- mandatory	string
`force`	Force will force the removal of the PGDGroup even if the target PGDGroup nodes are not parted	bool

PGDGroupCleanupStatus

PGDGroupCleanupStatus defines the observed state of PGDGroupCleanup

Name	Description	Type
`phase`		resources.OperatorPhaseCleanup

PGDGroupList

PGDGroupList contains a list of PGDGroup

Name	Description	Type
`metadata`		metav1.ListMeta
`items`	- mandatory	[]PGDGroup

PGDGroupSpec

PGDGroupSpec defines the desired state of PGDGroup

Name	Description	Type
`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-images	corev1.PullPolicy
`imagePullSecrets`	The list of pull secrets to be used to pull operator and or the operand images	[]corev1.LocalObjectReference
`inheritedMetadata`	Metadata that will be inherited by all objects related to the pgdGroup	*InheritedMetadata
`instances`	Number of instances required in the cluster - mandatory	int32
`proxyInstances`	Number of proxy instances required in the cluster	int32
`witnessInstances`	Number of witness instances required in the cluster	int32
`backup`	The configuration to be used for backups in the CNP instances.	*Backup
`restore`	The configuration to restore this PGD group from an Object Store service	*Restore
`cnp`	Instances configuration that will be injected into the CNP clusters that compose the PGD Group - mandatory	CnpConfiguration
`witness`	WitnessInstances configuration that will be injected into the WitnessInstances CNP clusters If not defined, it will default to the Instances configuration	*CnpBaseConfiguration
`pgd`	Pgd contains instructions to bootstrap this cluster - mandatory	PgdConfiguration
`pgdProxy`	PGDProxy contains instructions to configure PGD Proxy	PGDProxyConfiguration
`connectivity`	Configures the connectivity of the PGDGroup, like services and certificates that will be used. - mandatory	ConnectivityConfiguration
`failingFinalizerTimeLimitSeconds`	The amount of seconds that the operator will wait in case of a failing finalizer. A finalizer is considered failing when the operator cannot reach any nodes of the PGDGroup	int32

PGDGroupStatus

PGDGroupStatus defines the observed state of PGDGroup

Name	Description	Type
`latestGeneratedNode`	ID of the latest generated node (used to avoid node name clashing)	int32
`phase`	The initialization phase of this cluster	resources.OperatorPhase
`phaseDetails`	The details of the current phase	string
`phaseTroubleshootHints`	PhaseTroubleshootHints general troubleshooting indications for the given phase	string
`phaseType`	PhaseType describes the phase category.	resources.PhaseType
`nodes`	The list of summaries for the nodes in the group	[]NodeSummary
`backup`	The node that is taking backups of this PGDGroup	BackupStatus
`restore`	The status of the restore process	RestoreStatus
`PGD`	Last known status of PGD	PGDStatus
`CNP`	Last known status of CNP	CNPStatus
`PGDProxy`	Last known status of PGDProxy	PGDProxyStatus
`connectivity`	Last known status of Connectivity	ConnectivityStatus

PGDNodeGroupEntry

PGDNodeGroupEntry shows information about the node groups available in the PGD configuration

Name	Description	Type
`name`	Name is the name of the node group - mandatory	string
`enableProxyRouting`	EnableProxyRouting is true is the node group allows running PGD Proxies	bool
`enableRaft`	EnableRaft is true if the node group has a subgroup raft instance	bool
`routeWriterMaxLag`	RouteWriterMaxLag Maximum lag in bytes of the new write candidate to be

selected as write leader, if no candidate passes this, there will be no writer selected automatically | int64 routeReaderMaxLag | RouteReaderMaxLag Maximum lag in bytes for node to be considered viable read-only node | int64 routeWriterWaitFlush | RouteWriterWaitFlush Whether to wait for replication queue flush before switching to new leader when using bdr.routing_leadership_transfer() | bool

PGDNodeGroupSettings

PGDNodeGroupSettings contains the settings of the PGD Group

Name	Description	Type
`routeWriterMaxLag`	RouteWriterMaxLag Maximum lag in bytes of the new write candidate to be

selected as write leader, if no candidate passes this, there will be no writer selected automatically Defaults to -1 | int64 routeReaderMaxLag | RouteReaderMaxLag Maximum lag in bytes for node to be considered viable read-only node Defaults to -1 | int64 routeWriterWaitFlush | RouteWriterWaitFlush Whether to wait for replication queue flush before switching to new leader when using bdr.routing_leadership_transfer() Defaults to false | bool

PGDProxyConfiguration

PGDProxyConfiguration defines the configuration of PGD Proxy

Name	Description	Type
`imageName`	Name of the PGDProxy container image	string
`logLevel`	The PGD Proxy log level, one of the following values: error, warning, info (default), debug, trace	string
`logEncoder`	The format of the log output	string
`proxyAffinity`	ProxyAffinity/Anti-affinity rules for pods	*corev1.Affinity
`proxyNodeSelector`	ProxyNodeSelector rules for pods	map[string]string
`proxyTolerations`	ProxyTolerations rules for pods	[]corev1.Toleration
`proxyResources`	Defines the resources assigned to the proxy. If not defined uses defaults requests and limits values.	corev1.ResourceRequirements

PGDProxyEntry

PGDProxyEntry shows information about the proxies available in the PGD configuration

Name	Description	Type
`name`	Name is the name of the proxy - mandatory	string
`fallbackGroupNames`	FallbackGroupNames are the names of the fallback groups configured for this proxy	[]string
`parentGroupName`	ParentGroupName is the parent PGD group of this proxy	string
`maxClientConn`	MaxClientConn maximum number of connections the proxy will accept	int
`maxServerConn`	MaxServerConn maximum number of connections the proxy will make to the Postgres node	int
`serverConnTimeout`	ServerConnTimeout connection timeout for server connections in seconds	int64
`serverConnKeepalive`	ServerConnKeepalive keepalive interval for server connections in seconds	int64
`fallbackGroupTimeout`	FallbackGroupTimeout the interval after which the routing falls back to one of the fallback_groups	int64

PGDProxySettings

PGDProxySettings contains the settings of the proxy

Name	Description	Type
`fallbackGroups`	FallbackGroups is the list of groups the proxy should forward connection to when all the data nodes of this PGD group are not available	[]string
`maxClientConn`	MaxClientConn maximum number of connections the proxy will accept. Defaults to 32767	int
`maxServerConn`	MaxServerConn maximum number of connections the proxy will make to the Postgres node. Defaults to 32767	int
`serverConnTimeout`	ServerConnTimeout connection timeout for server connections in seconds. Defaults to 2	int64
`serverConnKeepalive`	ServerConnKeepalive keepalive interval for server connections in seconds. Defaults to 10	int64
`fallbackGroupTimeout`	FallbackGroupTimeout the interval after which the routing falls back to one of the fallback_groups. Defaults to 60	int64

PGDProxyStatus

PGDProxyStatus any relevant status for the operator about PGDProxy

Name	Description	Type
`proxyInstances`		int32
`writeLead`	WriteLead is a reserved field for the operator, is not intended for external usage. Will be removed in future versions	string
`proxyHash`	ProxyHash contains the hash we use to detect if we need to reconcile the proxies	string

PGDStatus

PGDStatus any relevant status for the operator about PGD

Name	Description	Type
`raftConsensusLastChangedStatus`	RaftConsensusLastChangedStatus indicates the latest reported status from bdr.monitor_group_raft	resources.PGDRaftStatus
`raftConsensusLastChangedMessage`	RaftConsensusLastChangedMessage indicates the latest reported message from bdr.monitor_group_raft	string
`raftConsensusLastChangedTimestamp`	RaftConsensusLastChangedTimestamp indicates when the status and message were first reported	string
`registeredProxies`	RegisteredProxies is the status of the registered proxies	[]PGDProxyEntry
`nodeGroup`	NodeGroup is the status of the node group associated with the PGDGroup	PGDNodeGroupEntry

ParentGroupConfiguration

ParentGroupConfiguration contains the topology configuration of PGD

Name	Description	Type
`name`	Name of the parent group - mandatory	string
`create`	Create is true when the operator should create the parent group if it doesn't exist	bool

PgdConfiguration

PgdConfiguration is the configuration of the PGD group structure

Name	Description	Type
`parentGroup`	ParentGroup configures the topology of the PGD group - mandatory	ParentGroupConfiguration
`discovery`	The parameters we will use to connect to a node belonging to the parent PGD group. Even if provided, the following parameters will be overridden with default values: `application_name`, `sslmode`, `dbname` and `user`. The following parameters should not be provided nor used, as they are not even overridden with defaults:`sslkey`, `sslcert`, `sslrootcert`	[]ConnectionString
`discoveryJob`	DiscoveryJob the configuration of the PGD Discovery job	DiscoveryJobConfig
`databaseName`	Name of the database used by the application. Default: `app`.	string
`ownerName`	Name of the owner of the database in the instance to be used by applications. Defaults to the value of the `database` key.	string
`ownerCredentialsSecret`	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	*cnpv1.LocalObjectReference
`proxySettings`	Configuration for the proxy	PGDProxySettings
`nodeGroupSettings`	Configuration for the PGD Group	*PGDNodeGroupSettings
`globalRouting`	GlobalRouting is true when global routing is enabled, and in this case the proxies will be created in the parent group	bool
`mutations`	List of SQL mutations to apply to the node group	SQLMutations

PreProvisionedCertificate

PreProvisionedCertificate contains the data needed to supply a pre-generated certificate

Name	Description	Type
`secretRef`	SecretRef a name pointing to a secret that contains a tls.crt and tls.key	string

ReplicationCertificateStatus

ReplicationCertificateStatus encapsulate the certificate status

Name	Description	Type
`name`	Name is the name of the certificate	string
`hash`	Hash is the hash of the configuration for which it has been generated	string
`isReady`	Ready is true when the certificate is ready	bool
`preProvisioned`	PreProvisioned is true if the certificate is preProvisioned	bool

Restore

Restore configures the restore of a PGD group from an object store

Name	Description	Type
`barmanObjectStore`	The configuration for the barman-cloud tool suite	*cnpv1.BarmanObjectStoreConfiguration
`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	*cnpv1.RecoveryTarget
`serverNames`	The list of server names to be used as a recovery origin. One of these servers will be elected as the seeding one when evaluating the recovery target - mandatory	[]string

RestoreStatus

RestoreStatus contains the current status of the restore process

Name	Description	Type
`serverName`	The name of the server to be restored - mandatory	string

RootDNSConfiguration

RootDNSConfiguration describes how the FQDN for the resources should be generated

Name	Description	Type
`additional`	AdditionalDNSConfigurations adds more possible FQDNs for the resources	[]DNSConfiguration

SQLMutation

SQLMutation is a series of SQL statements to apply atomically

Name	Description	Type
`isApplied`	List of boolean-returning SQL queries. If any of them returns false the mutation will be applied - mandatory	[]string
`exec`	List of SQL queries to be executed to apply this mutation - mandatory	[]string
`type`	Type determines when the SQLMutation occurs. 'always': reconcile the mutation at each reconciliation cycle 'beforeSubgroupRaft': are executed only before the subgroupRaft is enabled If not specified, the Type defaults to 'always'. - mandatory	SQLMutationType

ServerCertConfiguration

ServerCertConfiguration contains the information to generate the certificates for the nodes

Name	Description	Type
`caCertSecret`	CACertSecret is the secret of the CA to be injected into the CloudNativePG configuration - mandatory	string
`certManager`	The cert-manager template used to generate the certificates - mandatory	CertManagerTemplate

ServiceTemplate

ServiceTemplate is a structure that allows the user to set a template for the Service generation.

Name	Description	Type
`metadata`	Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata	Metadata
`spec`	Specification of the desired behavior of the service. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status	corev1.ServiceSpec
`updateStrategy`	UpdateStrategy indicates how to update the services generated by this template.	*ServiceUpdateStrategy

TLSConfiguration

TLSConfiguration is the configuration of the TLS infrastructure used by PGD to connect to the nodes

Name	Description	Type
`mode`	- mandatory	TLSMode
`serverCert`	The configuration for the server certificates - mandatory	ServerCertConfiguration
`clientCert`	The configuration for the client certificates - mandatory	ClientCertConfiguration