API Reference v1

JKS configures options for storing a JKS keystore in thespec.secretName Secret resource.

PKCS12 configures options for storing a PKCS12 keystore in thespec.secretName Secret resource.

RotationPolicy controls how private keys should be regenerated when a re-issuance is being processed. If set to Never, a private key will only be generated if one does not already exist in the target spec.secretName. If one does exists but it does not have the correct algorithm or size, a warning will be raised to await user intervention. If set to Always, a private key matching the specified requirements will be generated whenever a re-issuance occurs. Default is 'Never' for backward compatibility.

The private key cryptography standards (PKCS) encoding for this certificate's private key to be encoded in. If provided, allowed values are PKCS1 and PKCS8 standing for PKCS#1 and PKCS#8, respectively. Defaults to PKCS1 if not specified.

Algorithm is the private key algorithm of the corresponding private key for this certificate. If provided, allowed values are either RSA,Ed25519 or ECDSAIf algorithm is specified and size is not provided, key size of 256 will be used for ECDSA key algorithm and key size of 2048 will be used for RSA key algorithm. key size is ignored when using the Ed25519 key algorithm.

Size is the key bit size of the corresponding private key for this certificate. If algorithm is set to RSA, valid values are 2048, 4096 or 8192, and will default to 2048 if not specified. If algorithm is set to ECDSA, valid values are 256, 384 or 521, and will default to 256 if not specified. If algorithm is set to Ed25519, Size is ignored. No other values are allowed.

Full X509 name specification (https://golang.org/pkg/crypto/x509/pkix/#Name).

CommonName is a common name to be used on the Certificate. The CommonName should have a length of 64 characters or fewer to avoid generating invalid CSRs. This value is ignored by TLS clients when any subject alt name is set. This is x509 behaviour: https://tools.ietf.org/html/rfc6125#section-6.4.4

The requested 'duration' (i.e. lifetime) of the Certificate. This option may be ignored/overridden by some issuer types. If unset this defaults to 90 days. Certificate will be renewed either 2/3 through its duration orrenewBefore period before its expiry, whichever is later. Minimum accepted duration is 1 hour. Value must be in units accepted by Go time.ParseDuration https://golang.org/pkg/time/#ParseDuration

How long before the currently issued certificate's expiry cert-manager should renew the certificate. The default is 2/3 of the issued certificate's duration. Minimum accepted value is 5 minutes. Value must be in units accepted by Go time.ParseDuration https://golang.org/pkg/time/#ParseDuration

DNSNames is a list of DNS subjectAltNames to be set on the Certificate.

IPAddresses is a list of IP address subjectAltNames to be set on the Certificate.

URIs is a list of URI subjectAltNames to be set on the Certificate.

EmailAddresses is a list of email subjectAltNames to be set on the Certificate.

SecretName is the name of the secret resource that will be automatically created and managed by this Certificate resource. It will be populated with a private key and certificate, signed by the denoted issuer. IMPORTANT: this field was required in the original cert-manager API declaration

Keystores configures additional keystore output formats stored in thesecretName Secret resource.

IssuerRef is a reference to the issuer for this certificate. If the kind field is not set, or set to Issuer, an Issuer resource with the given name in the same namespace as the Certificate will be used. If the kind field is set to ClusterIssuer, a ClusterIssuer with the provided name will be used. The name field in this stanza is required at all times.

IsCA will mark this Certificate as valid for certificate signing. This will automatically add the cert sign usage to the list of usages.

Usages is the set of x509 usages that are requested for the certificate. Defaults to digital signature and key encipherment if not specified.

Options to control private keys used for the Certificate.

EncodeUsagesInRequest controls whether key usages should be present in the CertificateRequest

revisionHistoryLimit is the maximum number of CertificateRequest revisions that are maintained in the Certificate's history. Each revision represents a single CertificateRequest created by this Certificate, either when it was created, renewed, or Spec was changed. Revisions will be removed by oldest first if the number of revisions exceeds this number. If set, revisionHistoryLimit must be a value of 1 or greater. If unset (nil), revisions will not be garbage collected. Default value is nil.

Create enables JKS keystore creation for the Certificate. If true, a file named keystore.jks will be created in the target Secret resource, encrypted using the password stored inpasswordSecretRef. The keystore file will only be updated upon re-issuance. A file named truststore.jks will also be created in the target Secret resource, encrypted using the password stored inpasswordSecretRef containing the issuing Certificate Authority

PasswordSecretRef is a reference to a key in a Secret resource containing the password used to encrypt the JKS keystore.

Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

Name of the resource being referred to.

Group of the resource being referred to.

Create enables PKCS12 keystore creation for the Certificate. If true, a file named keystore.p12 will be created in the target Secret resource, encrypted using the password stored inpasswordSecretRef. The keystore file will only be updated upon re-issuance. A file named truststore.p12 will also be created in the target Secret resource, encrypted using the password stored inpasswordSecretRef containing the issuing Certificate Authority

PasswordSecretRef is a reference to a key in a Secret resource containing the password used to encrypt the PKCS12 keystore.

The name of the Secret resource being referred to.

The key of the entry in the Secret resource's data field to be used. Some instances of this field may be defaulted, in others it may be required.

Organizations to be used on the Certificate.

Countries to be used on the Certificate.

Organizational Units to be used on the Certificate.

Cities to be used on the Certificate.

State/Provinces to be used on the Certificate.

Street addresses to be used on the Certificate.

Postal codes to be used on the Certificate.

Serial number to be used on the Certificate.

The CNP configuration to be used for backup. ServerName value is reserved by the operator.

The scheduled backup for the data. This field is deprecated and will be removed in future versions.

Define schedulers for the backup. Each scheduler has a different backup method. Only one of either backup.cron or backup.schedulers can be defined.

ClusterName the elected cluster to take the backup, the backup could be scheduled with different methods, but only one cluster will take the backup

ScheduledBackupName is the name of the scheduled backup. This field is deprecated, will be migrated to ScheduledBackupStatus

ScheduledBackupHash is the hash of the scheduled backup configuration. This field is deprecated, will be migrated to ScheduledBackupStatus

ScheduledBackupStatus contains the status of all scheduled backups

The recoverability points by method, keyed per CNP clusterName nolint: lll

The recoverability points, keyed per CNP clusterName, as a date in RFC3339 format

The Certificate object specification

The label and annotations metadata

CACertSecret is the secret of the CA to be injected into the CloudNativePG configuration

The cert-manager template used to generate the certificates

PreProvisioned contains how to fetch the pre-generated client certificates

StreamingReplica the pre-generated certificate for 'streaming_replica' user

The time in seconds that is allowed for a PostgreSQL instance to successfully start up (default 3600)

The time in seconds that is allowed for a PostgreSQL instance node to gracefully shutdown (default 180)

The time in seconds that controls the window of time reserved for the smart shutdown of Postgres to complete. Make sure you reserve enough time for the operator to request a fast shutdown of Postgres (that is: stopDelay - smartShutdownTimeout).

Configuration of the storage of the instances

Configuration of the WAL storage for the instances

The time in seconds that is allowed for a PostgreSQL instance to successfully start up (default 300)

Affinity/Anti-affinity rules for Pods

Resources requirements of every generated Pod. Please refer to https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for more information.

Configuration of the PostgreSQL server

The configuration of the monitoring infrastructure of this cluster

The instances' log level, one of the following values: error, warning, info (default), debug, trace

The service account template to be passed to CNP

OpenTelemetry Configuration

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)

List of SQL queries to be executed as a superuser in the template1after a node has been created - to be used with extreme care (by default empty)

List of SQL queries to be executed as a superuser in the application database right after the cluster has been created - to be used with extreme care as any data created in application database before logical join will cause the join to fail (by default empty)

List of references to ConfigMaps or Secrets containing SQL files to be executed as a superuser in the application database right after the cluster has been created. The references are processed in a specific order: first, all Secrets are processed, followed by all ConfigMaps. Within each group, the processing order follows the sequence specified in their respective arrays. - to be used with extreme care (by default empty)

The SeccompProfile applied to every Pod and Container. Defaults to: RuntimeDefault

Metadata applied exclusively to the generated Cluster resources. Useful for applying AppArmor profiles.

The configuration that is used by the portions of PostgreSQL that are managed by the CNP instance manager

Template to be used to define projected volumes, projected volumes will be mounted under /projected base folder

The tablespaces configuration

TopologySpreadConstraints specifies how to spread matching pods among the given topology. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/

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. When this option is disabled on a running Group, the operator will ignore the content of the secret and set the password of the postgres user to NULL. Enabled by default.

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.

Describes how the FQDN for the resources should be generated

The configuration of the TLS infrastructure

Instructs how to generate the service for each node

Instructs how to generate the service for the PGDGroup

Instructs how to generate the service pointing to the PGD Proxy for write leader node routing

Instructs how to generate the service pointing to the PGD Proxy for read nodes routing

ReplicationTLSCertificate is the name of the replication TLS certificate, if we have it

NodeTLSCertificates are the names of the certificates that have been created for the PGD nodes

UnusedCertificates are the names of the certificates that we don't use anymore for the PGD nodes

NodesWithoutCertificates are the names of the nodes which have not a server certificate

NodesNeedingServiceReconciliation are the names of the nodes which have not a server certificate

ConfigurationHash is the hash code of the connectivity configuration, used to check if we had a change in the configuration or not

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

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)

Delay amount of time to sleep between retries, measured in seconds

Retries how many times the operation should be retried

Timeout amount of time given to the operation to succeed, measured in seconds

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

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

NodeName is the name of the CNP cluster using this certificate

Name of the node

NodeGroupName is the name of the joined group

Consistent state of the node in human-readable form

State which the node is trying to reach (during join or promotion)

The kind of node: witness or data

The OpenTelemetry HTTP endpoint URL to accept metrics data

The OpenTelemetry HTTP endpoint URL to accept trace data

Whether to push trace data to OpenTelemetry traceUrl

TLSConfiguration provides the TLS certificate configuration when MetricsURL and TraceURL are using HTTPS

CABundleSecretRef is a reference to a secret field containing the CA bundle to verify the openTelemetry server certificate

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.

Force will force the removal of the PGDGroup even if the target PGDGroup nodes are not parted

Name of the container image, supporting both tags (<image>:<tag>) and digests for deterministic and repeatable deployments (<image>:<tag>@sha256:<digestValue>)

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

The list of pull secrets to be used to pull operator and or the operand images

Metadata that will be inherited by all objects related to the pgdGroup

Number of instances required in the cluster

Number of proxy instances required in the cluster

Number of witness instances required in the cluster

The configuration to be used for backups in the CNP instances.

The configuration to restore this PGD group from an Object Store service

Instances configuration that will be injected into the CNP clusters that compose the PGD Group

WitnessInstances configuration that will be injected into the WitnessInstances CNP clusters If not defined, it will default to the Instances configuration

Pgd contains instructions to bootstrap this cluster

PGDProxy contains instructions to configure PGD Proxy

Configures the connectivity of the PGDGroup, like services and certificates that will be used.

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

ID of the latest generated node (used to avoid node name clashing)

The initialization phase of this cluster

The details of the current phase

PhaseTroubleshootHints general troubleshooting indications for the given phase

PhaseType describes the phase category.

Conditions for PGDGroup object

The list of summaries for the nodes in the group

The node that is taking backups of this PGDGroup

The status of the restore process

Last known status of PGD

Last known status of CNP

Last known status of PGDProxy

Last known status of Connectivity

Last known status of Pause

Name is the name of the node group

EnableProxyRouting is true is the node group allows running PGD Proxies

EnableRaft is true if the node group has a subgroup raft instance

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

RouteReaderMaxLag Maximum lag in bytes for node to be considered viable read-only node

RouteWriterWaitFlush Whether to wait for replication queue flush before switching to new leader when using bdr.routing_leadership_transfer()

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

RouteReaderMaxLag Maximum lag in bytes for node to be considered viable read-only node Defaults to -1

RouteWriterWaitFlush Whether to wait for replication queue flush before switching to new leader when using bdr.routing_leadership_transfer()Defaults to false

Name of the PGDProxy container image

The PGD Proxy log level, one of the following values: error, warning, info (default), debug, trace

The format of the log output

ProxyAffinity/Anti-affinity rules for pods

ProxyNodeSelector rules for pods

ProxyTolerations rules for pods

Defines the resources assigned to the proxy. If not defined uses defaults requests and limits values.

Name is the name of the proxy

FallbackGroupNames are the names of the fallback groups configured for this proxy

ParentGroupName is the parent PGD group of this proxy

MaxClientConn maximum number of connections the proxy will accept

MaxServerConn maximum number of connections the proxy will make to the Postgres node

ServerConnTimeout connection timeout for server connections in seconds

ServerConnKeepalive keepalive interval for server connections in seconds

FallbackGroupTimeout the interval after which the routing falls back to one of the fallback_groups

ConsensusGracePeriod the duration in seconds for which proxy continues to route even upon loss of a Raft leader.

ReadListenPort is the port where the proxy will listen and route queries to read nodes

FallbackGroups is the list of groups the proxy should forward connection to when all the data nodes of this PGD group are not available

MaxClientConn maximum number of connections the proxy will accept. Defaults to 32767

MaxServerConn maximum number of connections the proxy will make to the Postgres node. Defaults to 32767

ServerConnTimeout connection timeout for server connections in seconds. Defaults to 2

ServerConnKeepalive keepalive interval for server connections in seconds. Defaults to 10

FallbackGroupTimeout the interval after which the routing falls back to one of the fallback_groups. Defaults to 60

ConsensusGracePeriod the duration in seconds for which proxy continues to route even upon loss of a Raft leader. If set to 0s, proxy stops routing immediately. Defaults to 6

EnableReadNodeRouting is the switch to control whether the proxy will route queries to read nodes through read_listen_port or not. By default it is false

WriteLead is a reserved field for the operator, is not intended for external usage. Will be removed in future versions

ProxyHash contains the hash we use to detect if we need to reconcile the proxies

RaftConsensusLastChangedStatus indicates the latest reported status from bdr.monitor_group_raft

RaftConsensusLastChangedMessage indicates the latest reported message from bdr.monitor_group_raft

RaftConsensusLastChangedTimestamp indicates when the status and message were first reported

RegisteredProxies is the status of the registered proxies

NodeGroup is the status of the node group associated with the PGDGroup

Name of the parent group

Create is true when the operator should create the parent group if it doesn't exist

Active indicates the PGDGroup is either:

• in process of pausing
• already paused
• in process of resuming

Instances is the number of paused PGD instances

LastStartedTime is the last time the PGDGroup started pausing

LastCompletedTime is last time the PGDGroup completed pausing

LastResumeStartedTime is the last time the PGDGroup started resuming

LastCompletedTime is last time the PGDGroup completed resuming

ParentGroup configures the topology of the PGD group

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

DiscoveryJob the configuration of the PGD Discovery job

Name of the database used by the application. Default: app.

Name of the owner of the database in the instance to be used by applications. Defaults to the value of the database key.

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

Configuration for the proxy

Configuration for the PGD Group

GlobalRouting is true when global routing is enabled, and in this case the proxies will be created in the parent group

List of SQL mutations to apply to the node group

SecretRef a name pointing to a secret that contains a tls.crt and tls.key

Name is the name of the certificate

Hash is the hash of the configuration for which it has been generated

Ready is true when the certificate is ready

PreProvisioned is true if the certificate is preProvisioned

The configuration for volumeSnapshot restore

The configuration for the barman-cloud tool suite

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

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, this option is only used when restore from barmanObjectStore.

The name of the server to be restored

selected volumeSnapshots to restore

AdditionalDNSConfigurations adds more possible FQDNs for the resources

List of boolean-returning SQL queries. If any of them returns false the mutation will be applied

List of SQL queries to be executed to apply this mutation

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'.

If this backup is suspended or not

If the first backup has to be immediately start after creation or not

The schedule does not follow the same format used in Kubernetes CronJobs as it includes an additional second specifier, see https://pkg.go.dev/github.com/robfig/cron#hdr-CRON_Expression_Format

Indicates which ownerReference should be put inside the created backup resources.

• none: no owner reference for created backup objects (same behavior as before the field was introduced)
• self: sets the Scheduled backup object as owner of the backup
• cluster: set the cluster as owner of the backup

The policy to decide which instance should perform this backup. If empty, it defaults to cluster.spec.backup.target. Available options are empty string, primary and prefer-standby.primary to have backups run always on primary instances,prefer-standby to have backups run preferably on the most updated standby, if available.

The backup method to be used, possible options are barmanObjectStoreand volumeSnapshot. Defaults to: barmanObjectStore.

Whether the default type of backup with volume snapshots is online/hot (true, default) or offline/cold (false) Overrides the default setting specified in the cluster field '.spec.backup.volumeSnapshot.online'

Configuration parameters to control the online/hot backup with volume snapshots Overrides the default settings specified in the cluster '.backup.volumeSnapshot.onlineConfiguration' stanza

Method is the backup method used to take the backup

Name is the name of the scheduled backup

Hash is the hash of the scheduled backup configuration

CACertSecret is the secret of the CA to be injected into the CloudNativePG configuration

The cert-manager template used to generate the certificates

Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

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

UpdateStrategy indicates how to update the services generated by this template.

The configuration for the server certificates

The configuration for the client certificates

SnapshotName is the snapshot name to restore

PVCRole is the pvcRole snapshot to restore

TablespaceName is the tablespace name the snapshot belongs to, if the pvcRole is PG_TABLESPACE

Label selector used to select the volumeSnapshot to restore