Skip to main content

API Reference

Package v1 contains API Schema definitions for the postgresql v1 API group.

Resource Types

Backup

A Backup resource is a request for a PostgreSQL backup by the user.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringBackup
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]BackupSpecSpecification of the desired behavior of the backup. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.mdx#spec-and-status
statusBackupStatusMost 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.mdx#spec-and-status

Cluster

Cluster is the Schema for the PostgreSQL API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringCluster
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]ClusterSpecSpecification of the desired behavior of the cluster. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.mdx#spec-and-status
statusClusterStatusMost 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.mdx#spec-and-status

ClusterImageCatalog

ClusterImageCatalog is the Schema for the clusterimagecatalogs API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringClusterImageCatalog
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]ImageCatalogSpecSpecification of the desired behavior of the ClusterImageCatalog. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.mdx#spec-and-status

Database

Database is the Schema for the databases API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringDatabase
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]DatabaseSpecSpecification of the desired Database. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.mdx#spec-and-status
statusDatabaseStatusMost recently observed status of the Database. 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.mdx#spec-and-status

ImageCatalog

ImageCatalog is the Schema for the imagecatalogs API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringImageCatalog
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]ImageCatalogSpecSpecification of the desired behavior of the ImageCatalog. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.mdx#spec-and-status

Pooler

Pooler is the Schema for the poolers API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringPooler
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]PoolerSpecSpecification of the desired behavior of the Pooler. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.mdx#spec-and-status
statusPoolerStatusMost recently observed status of the Pooler. 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.mdx#spec-and-status

Publication

Publication is the Schema for the publications API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringPublication
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]PublicationSpecNo description provided.
status [Required]PublicationStatusNo description provided.

ScheduledBackup

ScheduledBackup is the Schema for the scheduledbackups API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringScheduledBackup
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]ScheduledBackupSpecSpecification of the desired behavior of the ScheduledBackup. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.mdx#spec-and-status
statusScheduledBackupStatusMost 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.mdx#spec-and-status

Subscription

Subscription is the Schema for the subscriptions API.

FieldDescription
apiVersion [Required]stringpostgresql.cnpg.io/v1
kind [Required]stringSubscription
metadata [Required]meta/v1.ObjectMetaRefer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]SubscriptionSpecNo description provided.
status [Required]SubscriptionStatusNo description provided.

AffinityConfiguration Appears in:

ClusterSpec

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

FieldDescription
enablePodAntiAffinity [Required]boolActivates anti-affinity for the pods. The operator will define pods anti-affinity unless this field is explicitly set to false.
topologyKeystringTopologyKey to use for anti-affinity configuration. See k8s documentation for more info on that.
nodeSelectormap[string]stringNodeSelector 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/
nodeAffinitycore/v1.NodeAffinityNodeAffinity describes node affinity scheduling rules for the pod. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
tolerations[]core/v1.TolerationTolerations 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/
podAntiAffinityTypestringPodAntiAffinityType 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-affinity
additionalPodAntiAffinitycore/v1.PodAntiAffinityAdditionalPodAntiAffinity 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.
additionalPodAffinitycore/v1.PodAffinityAdditionalPodAffinity allows to specify pod affinity terms to be passed to all the cluster's pods.

BootstrapRecovery Appears in:

BootstrapConfiguration

BootstrapRecovery contains the configuration required to restore from an existing cluster using 3 methodologies: external cluster, volume snapshots or backup objects. Full recovery and Point-In-Time Recovery are supported. The method can be also be used to create clusters in continuous recovery (replica clusters), also supporting cascading replication when instances > 1.

Once the cluster exits recovery, the password for the superuser will be changed through the provided secret. Refer to the Bootstrap page of the documentation for more information.

FieldDescription
backup [Required]BackupSourceThe backup object containing the physical base backup from which to initiate the recovery procedure. Mutually exclusive with source and volumeSnapshots.
sourcestringThe 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 cluster. Mutually exclusive with backup.
volumeSnapshotsDataSourceThe static PVC data source(s) from which to initiate the recovery procedure. Currently supporting VolumeSnapshot and PersistentVolumeClaim resources that map an existing PVC group, compatible with CloudNativePG, and taken with a cold backup copy on a fenced Postgres instance.
recoveryTargetRecoveryTargetBy 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. More info: https://www.postgresql.org/docs/current/runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET
databasestringName of the database used by the application. Default: app.
ownerstringName of the owner of the database in the instance to be used by applications. Defaults to the value of the database key.
secretgithub.com/cloudnative-pg/machinery/pkg/api.LocalObjectReferenceName of the secret containing the initial credentials for the owner of the user database. If empty a new secret will be created from scratch.

CertificatesConfiguration Appears in:

CertificatesStatus

ClusterSpec

CertificatesConfiguration contains the needed configurations to handle server certificates.

FieldDescription
serverCASecret [Required]stringThe 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.
serverTLSSecretstringThe 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.
replicationTLSSecretstringThe 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.
clientCASecretstringThe 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.
serverAltDNSNames[]stringThe list of the server alternative DNS names to be added to the generated server TLS certificates, when required.

CertificatesStatus

Appears in:

CertificatesStatus contains configuration certificates and related expiration dates.

FieldDescription
CertificatesConfiguration(Members of CertificatesConfiguration are embedded into this type.) Needed configurations to handle server certificates, initialized with default values, if needed.
expirations map[string]stringExpiration dates for all certificates.

ClusterMonitoringTLSConfiguration

Appears in:

ClusterMonitoringTLSConfiguration is the type containing the TLS configuration for the cluster's monitoring

FieldDescription
enabled boolEnable TLS for the monitoring endpoint. Changing this option will force a rollout of all instances.

ClusterSpec

Appears in:

ClusterSpec defines the desired state of Cluster

FieldDescription

ClusterStatus

Appears in:

ClusterStatus defines the observed state of Cluster

FieldDescription

ConfigMapResourceVersion

Appears in:

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

FieldDescription

DataDurabilityLevel

(Alias of string)

Appears in:

  • SynchronousReplicaConfiguration

    DataDurabilityLevel specifies how strictly to enforce synchronous replication when cluster instances are unavailable. Options are required or preferred.

DataSource

Appears in:

DataSource contains the configuration required to bootstrap a PostgreSQL cluster from an existing storage

FieldDescription

DatabaseObjectSpec

Appears in:

DatabaseObjectSpec contains the fields which are common to every database object

FieldDescription

DatabaseObjectStatus

Appears in:

DatabaseObjectStatus is the status of the managed database objects

FieldDescription

DatabaseReclaimPolicy

(Alias of string)

Appears in:

DatabaseReclaimPolicy describes a policy for end-of-life maintenance of databases.

DatabaseRoleRef

Appears in:

DatabaseRoleRef is a reference an a role available inside PostgreSQL

FieldDescription

DatabaseSpec

Appears in:

  • Database

    DatabaseSpec is the specification of a Postgresql Database, built around the CREATE DATABASE, ALTER DATABASE, and DROP DATABASE SQL commands of PostgreSQL.

FieldDescription

DatabaseStatus

Appears in:

DatabaseStatus defines the observed state of Database

FieldDescription

EmbeddedObjectMetadata

Appears in:

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

FieldDescription

EnsureOption

(Alias of string)

Appears in:

EnsureOption represents whether we should enforce the presence or absence of a Role in a PostgreSQL instance

EphemeralVolumesSizeLimitConfiguration

Appears in:

EphemeralVolumesSizeLimitConfiguration contains the configuration of the ephemeral storage

FieldDescription

ExtensionSpec

Appears in:

ExtensionSpec configures an extension in a database

FieldDescription

ExternalCluster

Appears in:

  • ClusterSpec

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

FieldDescription

ImageCatalogRef

Appears in:

ImageCatalogRef defines the reference to a major version in an ImageCatalog

FieldDescription

ImageCatalogSpec

Appears in:

ImageCatalogSpec defines the desired ImageCatalog

FieldDescription

ImageInfo

Appears in:

ImageInfo contains the information about a PostgreSQL image

FieldDescription

Import

Appears in:

Import contains the configuration to init a database from a logic snapshot of an externalCluster

FieldDescription

ImportSource

Appears in:

ImportSource describes the source for the logical snapshot

FieldDescription

InstanceID

Appears in:

InstanceID contains the information to identify an instance

FieldDescription

InstanceReportedState

Appears in:

InstanceReportedState describes the last reported state of an instance during a reconciliation loop

FieldDescription

LDAPBindAsAuth

Appears in:

LDAPBindAsAuth provides the required fields to use the bind authentication for LDAP

FieldDescription

LDAPBindSearchAuth

Appears in:

LDAPBindSearchAuth provides the required fields to use the bind+search LDAP authentication process

FieldDescription

LDAPConfig

Appears in:

LDAPConfig contains the parameters needed for LDAP authentication

FieldDescription

LDAPScheme

(Alias of string)

Appears in:

LDAPScheme defines the possible schemes for LDAP

ManagedConfiguration

Appears in:

ManagedConfiguration represents the portions of PostgreSQL that are managed by the instance manager

FieldDescription

ManagedRoles

Appears in:

ManagedRoles tracks the status of a cluster's managed roles

FieldDescription

ManagedService

Appears in:

  • ManagedServices

    ManagedService represents a specific service managed by the cluster. It includes the type of service and its associated template specification.

FieldDescription

ManagedServices

Appears in:

ManagedServices represents the services managed by the cluster.

FieldDescription

Metadata

Appears in:

  • PodTemplateSpec

  • ServiceAccountTemplate

  • ServiceTemplateSpec

    Metadata is a structure similar to the metav1.ObjectMeta, but still parseable by controller-gen to create a suitable CRD for the user. The comment of PodTemplateSpec has an explanation of why we are not using the core data types.

FieldDescription

MonitoringConfiguration

Appears in:

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

FieldDescription

NodeMaintenanceWindow

Appears in:

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.

FieldDescription

OnlineConfiguration

Appears in:

OnlineConfiguration contains the configuration parameters for the online volume snapshot

FieldDescription

PasswordState

Appears in:

PasswordState represents the state of the password of a managed RoleConfiguration

FieldDescription

PgBouncerIntegrationStatus

Appears in:

PgBouncerIntegrationStatus encapsulates the needed integration for the pgbouncer poolers referencing the cluster

FieldDescription

PgBouncerPoolMode

(Alias of string)

Appears in:

PgBouncerPoolMode is the mode of PgBouncer

PgBouncerSecrets

Appears in:

PgBouncerSecrets contains the versions of the secrets used by pgbouncer

FieldDescription

PgBouncerSpec

Appears in:

PgBouncerSpec defines how to configure PgBouncer

FieldDescription

PluginConfiguration

Appears in:

PluginConfiguration specifies a plugin that need to be loaded for this cluster to be reconciled

FieldDescription

PluginStatus

Appears in:

PluginStatus is the status of a loaded plugin

FieldDescription

PodTemplateSpec

Appears in:

PodTemplateSpec is a structure allowing the user to set a template for Pod generation.

Unfortunately we can't use the corev1.PodTemplateSpec type because the generated CRD won't have the field for the metadata section.

References: https://github.com/kubernetes-sigs/controller-tools/issues/385 https://github.com/kubernetes-sigs/controller-tools/issues/448 https://github.com/prometheus-operator/prometheus-operator/issues/3041

FieldDescription

PodTopologyLabels

(Alias of map[string]string)

Appears in:

PodTopologyLabels represent the topology of a Pod. map[labelName]labelValue

PoolerIntegrations

Appears in:

PoolerIntegrations encapsulates the needed integration for the poolers referencing the cluster

FieldDescription

PoolerMonitoringConfiguration

Appears in:

PoolerMonitoringConfiguration is the type containing all the monitoring configuration for a certain Pooler. Mirrors the Cluster's MonitoringConfiguration but without the custom queries part for now.

FieldDescription

PoolerSecrets

Appears in:

PoolerSecrets contains the versions of all the secrets used

FieldDescription

PoolerSpec

Appears in:

PoolerSpec defines the desired state of Pooler

FieldDescription

PoolerStatus

Appears in:

PoolerStatus defines the observed state of Pooler

FieldDescription

PoolerType

(Alias of string)

Appears in:

  • PoolerSpec

    PoolerType is the type of the connection pool, meaning the service we are targeting. Allowed values are rw and ro.

PostgresConfiguration

Appears in:

PostgresConfiguration defines the PostgreSQL configuration

FieldDescription

PrimaryUpdateMethod

(Alias of string)

Appears in:

  • ClusterSpec

    PrimaryUpdateMethod contains the method to use when upgrading the primary server of the cluster as part of rolling updates

PrimaryUpdateStrategy

(Alias of string)

Appears in:

  • ClusterSpec

    PrimaryUpdateStrategy contains the strategy to follow when upgrading the primary server of the cluster as part of rolling updates

Probe

Appears in:

FieldDescription

ProbeStrategyType

(Alias of string)

Appears in:

ProbeStrategyType is the type of the strategy used to declare a PostgreSQL instance ready

ProbeWithStrategy

Appears in:

ProbeWithStrategy is the configuration of the startup probe

FieldDescription

ProbesConfiguration

Appears in:

ProbesConfiguration represent the configuration for the probes to be injected in the PostgreSQL Pods

FieldDescription

PublicationReclaimPolicy

(Alias of string)

Appears in:

PublicationReclaimPolicy defines a policy for end-of-life maintenance of Publications.

PublicationSpec

Appears in:

PublicationSpec defines the desired state of Publication

FieldDescription

PublicationStatus

Appears in:

PublicationStatus defines the observed state of Publication

FieldDescription

PublicationTarget

Appears in:

PublicationTarget is what this publication should publish

FieldDescription

PublicationTargetObject

Appears in:

PublicationTargetObject is an object to publish

FieldDescription

PublicationTargetTable

Appears in:

PublicationTargetTable is a table to publish

FieldDescription

RecoveryTarget

Appears in:

  • BootstrapRecovery

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

FieldDescription

ReplicaClusterConfiguration

Appears in:

ReplicaClusterConfiguration encapsulates the configuration of a replica cluster

FieldDescription

ReplicationSlotsConfiguration

Appears in:

ReplicationSlotsConfiguration encapsulates the configuration of replication slots

FieldDescription

ReplicationSlotsHAConfiguration

Appears in:

  • ReplicationSlotsConfiguration

    ReplicationSlotsHAConfiguration encapsulates the configuration of the replication slots that are automatically managed by the operator to control the streaming replication connections with the standby instances for high availability (HA) purposes. Replication slots are a PostgreSQL feature that makes sure that PostgreSQL automatically keeps WAL files in the primary when a streaming client (in this specific case a replica that is part of the HA cluster) gets disconnected.

FieldDescription

RoleConfiguration

Appears in:

FieldDescription

SQLRefs

Appears in:

  • BootstrapInitDB

    SQLRefs holds references to ConfigMaps or Secrets containing SQL files. 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.

FieldDescription

ScheduledBackupSpec

Appears in:

ScheduledBackupSpec defines the desired state of ScheduledBackup

FieldDescription

ScheduledBackupStatus

Appears in:

ScheduledBackupStatus defines the observed state of ScheduledBackup

FieldDescription

SchemaSpec

Appears in:

SchemaSpec configures a schema in a database

FieldDescription

SecretVersion

Appears in:

SecretVersion contains a secret name and its ResourceVersion

FieldDescription

SecretsResourceVersion

Appears in:

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

FieldDescription

ServiceAccountTemplate

Appears in:

ServiceAccountTemplate contains the template needed to generate the service accounts

FieldDescription

ServiceSelectorType

(Alias of string)

Appears in:

  • ManagedService

  • ManagedServices

    ServiceSelectorType describes a valid value for generating the service selectors. It indicates which type of service the selector applies to, such as read-write, read, or read-only

ServiceTemplateSpec

Appears in:

ServiceTemplateSpec is a structure allowing the user to set a template for Service generation.

FieldDescription

ServiceUpdateStrategy

(Alias of string)

Appears in:

ServiceUpdateStrategy describes how the changes to the managed service should be handled

SnapshotOwnerReference

(Alias of string)

Appears in:

  • VolumeSnapshotConfiguration

    SnapshotOwnerReference defines the reference type for the owner of the snapshot. This specifies which owner the processed resources should relate to.

SnapshotType

(Alias of string)

Appears in:

SnapshotType is a type of allowed import

StorageConfiguration

Appears in:

FieldDescription

SubscriptionReclaimPolicy

(Alias of string)

Appears in:

SubscriptionReclaimPolicy describes a policy for end-of-life maintenance of Subscriptions.

SubscriptionSpec

Appears in:

SubscriptionSpec defines the desired state of Subscription

FieldDescription

SubscriptionStatus

Appears in:

SubscriptionStatus defines the observed state of Subscription

FieldDescription

SwitchReplicaClusterStatus

Appears in:

SwitchReplicaClusterStatus contains all the statuses regarding the switch of a cluster to a replica cluster

FieldDescription

SyncReplicaElectionConstraints

Appears in:

SyncReplicaElectionConstraints contains the constraints for sync replicas election.

For anti-affinity parameters two instances are considered in the same location if all the labels values match. In future synchronous replica election restriction by name will be supported.

FieldDescription

SynchronizeReplicasConfiguration

Appears in:

  • ReplicationSlotsConfiguration

    SynchronizeReplicasConfiguration contains the configuration for the synchronization of user defined physical replication slots

FieldDescription

SynchronousReplicaConfiguration

Appears in:

  • PostgresConfiguration

    SynchronousReplicaConfiguration contains the configuration of the PostgreSQL synchronous replication feature. Important: at this moment, also .spec.minSyncReplicas and .spec.maxSyncReplicas need to be considered.

FieldDescription

SynchronousReplicaConfigurationMethod

(Alias of string)

Appears in:

SynchronousReplicaConfigurationMethod configures whether to use quorum based replication or a priority list

TablespaceConfiguration

Appears in:

  • ClusterSpec

    TablespaceConfiguration is the configuration of a tablespace, and includes the storage specification for the tablespace

FieldDescription

TablespaceState

Appears in:

TablespaceState represents the state of a tablespace in a cluster

FieldDescription

TablespaceStatus

(Alias of string)

Appears in:

TablespaceStatus represents the status of a tablespace in the cluster

Topology

Appears in:

Topology contains the cluster topology

FieldDescription

VolumeSnapshotConfiguration

Appears in:

VolumeSnapshotConfiguration represents the configuration for the execution of snapshot backups.

FieldDescription