This topic describes the available fields of the Postgres Custom Resource Definition.

Synopsis

apiVersion: sql.tanzu.vmware.com/v1
kind: Postgres
metadata:
  name: postgres-sample
spec:
  #
  # Global features
  #
  pgConfig:
    dbname: postgres-sample
    username: pgadmin
    appUser: pgappuser
    readOnlyUser: pgrouser
    readWriteUser: pgrwuser
#  customConfig:
#    initDb:
#      checksum: false
#    postgresql:
#      name:
  postgresVersion:
    name: postgres-15 # View available versions with `kubectl get postgresversion`
  serviceType: ClusterIP
#  serviceAnnotations:
  readOnlyServiceType: ClusterIP
#  readOnlyServiceAnnotations:
  seccompProfile:
    type: RuntimeDefault
  imagePullSecret:
    name: regsecret
  persistentVolumeClaimPolicy: delete
#  highAvailability:
#    enabled: true
#    readReplicas: 1
#    podDisruptionBudget:
#        enabled: false
#  logLevel: Debug
#  backupLocation:
#    name: backuplocation-sample
#  certificateSecretName:
#  deploymentOptions:
#    continuousRestoreTarget: true
#    sourceStanzaName: <sample-stanza-from-prod-instance>

  #
  # Data Pod features
  #
#  storageClassName: 
  storageSize: 800M
  sharedMemorySize: 64Mi
  dataPodConfig:
#    tolerations:
#      - key:
#        operator:
#        value:
#        effect:
    affinity:
      podAntiAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
          - podAffinityTerm:
              labelSelector:
                matchExpressions:
                  - key: type
                    operator: In
                    values:
                      - data
                      - monitor
                  - key: postgres-instance
                    operator: In
                    values:
                      - postgres-sample
              topologyKey: kubernetes.io/hostname
            weight: 100
  #
  # Monitor Pod features
  #
#  monitorStorageClassName: 
  monitorStorageSize: 1G
  monitorPodConfig:
#    tolerations:
#      - key:
#        operator:
#        value:
#        effect:
    affinity:
      podAntiAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
          - podAffinityTerm:
              labelSelector:
                matchExpressions:
                  - key: type
                    operator: In
                    values:
                      - data
                      - monitor
                  - key: postgres-instance
                    operator: In
                    values:
                      - postgres-sample
              topologyKey: kubernetes.io/hostname
            weight: 100

  #
  # Resources
  #
  resources:
    data:
      limits:
        cpu: 800m
        memory: 800Mi
      requests:
        cpu: 800m
        memory: 800Mi
    monitor:
      limits:
        cpu: 800m
        memory: 800Mi
      requests:
        cpu: 800m
        memory: 800Mi
    metrics:
      limits:
        cpu: 100m
        memory: 100Mi
      requests:
        cpu: 100m
        memory: 100Mi

Description

Applying this resource causes the Kubernetes Operator to create two StatefulSets, one for monitor and one for data. Both the pods mount respective persistent volume claims (PVC). The monitor PVC holds the monitor data (state of the postgres cluster, events, etc.) and the data PVC holds the user data.

You specify Postgres instance configuration properties to the Postgres operator with a YAML-formatted manifest file. A sample manifest file is provided with the release, in postgres.yaml. See also Deploying a New Postgres Instance for information about deploying a new Postgres instance using a manifest file.

Metadata

The metadata follows standard Kubernetes conventions. For more details, refer to Metadata in the Kubernetes documentation.

The metadata sets the name, namespace, labels, annotations, and more for the Postgres object.

name

Type: string
Required
Default: n/a
Sets the name of the Postgres instance. The Kubernetes operator will append an index like -0 or -1 to the end of the name when it creates the pods, for example postgres-sample-0. By default, a newly created Postgres object will include a default database with the same name as the object unless you change the default database name with pgConfig.dbname.

Spec

The spec describes the desired state for the Postgres object.

imagePullSecret

Type: Object
Optional
Default: name: regsecret
The secret value defaults to the dockerRegistrySecretName in the Operator's values.yaml. If your namespace's docker-registry secret uses a different secret than the Operator's helm chart secret, alter the secret name accordingly.
Note: Recreate the secret within your pod's namespace in order to be accessed by the pod.
An existing Kubernetes docker-registry secret that can access the registry containing the Postgres image.

persistentVolumeClaimPolicy

Type: string
Optional
Default: delete
This field specifies if the PVC is deleted or retained when the instance is deleted. It supports two values: delete and retain. If set to retain, the PVCs will be retained even when the instance is deleted. These PVCs can then be reclaimed once the instance is back up.

pgConfig

Type: Object
Optional
This collection of fields describes the Postgres database table and user that is created at database initialization. See Custom Database Name and User Account for more information.

  • dbname
    Type: string
    Optional
    Default: Postgres metadata name
    The name of the default Postgres database. By default, the Postgres instance name is used as the default database name. See Custom Database Name and User Account.

  • username
    Type: string
    Optional
    Default: pgadmin
    The name of the default Postgres user. See Custom Database Name and User Account.

  • appUser
    Type: string
    Optional
    Default: pgappuser
    Specifies the name of the Postgres user that is used to bind an application with the Postgres instance. The default pgappuser can be altered to a custom value before instance deployment, but cannot be altered after.
    The appUser has data definition (CREATE, DROP, ALTER, TRUNCATE, COMMENT, RENAME), and data manipulation (SELECT, INSERT, UPDATE, DELETE) privileges. You may change the value during instance deployment, For more information, refer to Creating Service Bindings.

  • readOnlyUser
    Type: string
    Optional
    Default: pgrouser
    Specifies the name of the Postgres user with read-only privileges. If not specified, it is set to pgrouser. The field can be altered to a custom value before instance deployment, but cannot be altered after.

  • readWriteUser
    Type: string
    Optional
    Default: pgrwuser
    Specifies the name of the Postgres user with read-write privileges but only data manipulation privileges (SELECT, INSERT, UPDATE, DELETE). If not specified, it is set to pgrwuser. The field can be altered to a custom value before instance deployment, but cannot be altered after.

customConfig

Type: Object
Optional
Enables users to set custom PostgreSQL parameters. For the procedure details refer to Customizing PostgreSQL Server.

  • initDb
    Type: Object
    Optional
    Enables users to set custom initdb parameters.
    • checksum
      Type: bool
      Optional
      This field gives you the opportunity to enable or disable the checksums on the newly-created instances.
  • postgresql
    Type: string
    Optional
    Default: n/a
    References the name of the ConfigMap that contains the PostgreSQL configuration settings that will be applied to the PostgreSQL server.
  • pghba
    Type: string
    Optional
    Default: n/a
    References the name of the ConfigMap that contains the pg_hba entries that will be appended to the PostgreSQL pg_hba.conf file.

trustedCaCertificates

Type: Object
Optional
Enables you to inject custom LDAP TLS certificate. For the procedure details, refer to Configuring LDAP authentication with Postgres for Kubernetes.

  • ldap
    Type: string
    Optional
    Default: n/a
    References the name of the Secret that contains the custom ca.crt LDAP certificate.

postgresVersion

Type: string
Optional
Default: <latest_version>
This string must be a reference to an existing PostgresVersion object. If omitted, the most up-to-date PostgresVersion is chosen (e.g. postgres-15). For more information see Specifying the VMware Postgres Operator Version.

serviceType

Type: string
Optional
Default: ClusterIP
The Kubernetes publishing service used for the Postgres instance. Options are LoadBalancer or ClusterIP. The default ClusterIP exposes the Postgres service internally and uses cluster-internal IP address instead of a load balancer. See Publishing Services (ServiceTypes) in the Kubernetes documentation for more information.

serviceAnnotations

Type: (map[string]string)
Optional
Default: n/a
Used mostly for instances with serviceType set to LoadBalancer, where the instances are deployed in public clouds, and require cloud-specific behavior. Can also be used to set custom annotations.
Example:

spec:
  serviceType: LoadBalancer
  serviceAnnotations:
    service.beta.kubernetes.io/azure-load-balancer-internal: "true",
    service.beta.kubernetes.io/azure-load-balancer-internal-subnet: "apps-subnet"
    cloud.google.com/load-balancer-type: "Internal"
    service.beta.kubernetes.io/aws-load-balancer-internal: "true"

readOnlyServiceType

Type: string
Optional
Default: ClusterIP
The Kubernetes publishing service used for the read-replicas of a High-Availability Postgres instance. You can set this field on a single instance in order to scale up to high availability at a later time. Options are LoadBalancer or ClusterIP. The default ClusterIP exposes the Postgres service internally and uses the cluster-internal IP address instead of a load balancer. See Publishing Services (ServiceTypes) in the Kubernetes documentation for more information.

readOnlyServiceAnnotations

Type: (map[string]string)
Optional
Default: n/a
Used mostly for instances with readOnlyServiceType set to LoadBalancer, where the instances are deployed in public clouds, and require cloud-specific behavior. Can also be used to set custom annotations.
Example:

spec:
  readOnlyServiceType: LoadBalancer
  readOnlyServiceAnnotations:
    service.beta.kubernetes.io/azure-load-balancer-internal: "true",
    service.beta.kubernetes.io/azure-load-balancer-internal-subnet: "apps-subnet"
    cloud.google.com/load-balancer-type: "Internal"
    service.beta.kubernetes.io/aws-load-balancer-internal: "true"

For more information, see Internal Load Balancer, and Annotations in the Kubernetes documentation.

seccompProfile

Type: corev1.SeccompProfile
Optional
Default: RuntimeDefault
Enables the use of Secure Compute Mode (seccomp) profiles for the Postgres instances. The default profile RuntimeDefault is the most restrictive, with a strong set of security defaults for container syscalls.
Set to Unconfined to deactivate seccomp profiles.
Set to Localhost to indicate the path of a pre-configured profile file on the node.
For more details, see Restrict a Container's Syscalls with seccomp in the Kubernetes documentation. For further information on the corev1.SeccompProfile type, see SeccompProfile v1 core.

highAvailability

Type: Object
Optional

  • enabled
    Type: bool
    Optional
    Default: false
    Specifies whether the Postgres instance is created as a single node (default), or in a High Availability (HA) configuration. See Configuring High Availability for more information about VMware Postgres Operator HA deployments.
  • readReplicas
    Type: int
    Optional
    Default: 0
    Specifies the number of read replicas (or mirrors) that will be deployed when HA mode is enabled. For details on scaling up, or down refer to Configuring High Availability.
  • podDisruptionBudget
    Type: Object
    Optional
    Default: n/a
    Holds the Pod Disruption Budget (PDB) related fields for the HA instance. For details on VMware Postgres Operator, refer to Configuring High Availability.
    • enabled
      Type: bool
      Optional
      Default: false
      Specifies whether Pod Disruption Budget should be enabled for the HA instance. For details on Pod Disruption Budget in VMware Postgres Operator, refer to Configuring High Availability. 
highAvailability:
  enabled: true
  readReplicas: 1
  podDisruptionBudget:
    enabled: false

loglevel

Type: string
Optional
Default: n/a
Sets the level of information detail displayed in the logs. By default this field is not in the instance yaml, and the log level is non-verbose. Set to Debug for verbose logs.

backupLocation

Type: LocalObjectReference
Optional
Default: n/a
When using a S3-compatible storage location for backups, this value specifies the PostgresBackupLocation CRD holding the configuration for the S3 backup location. For more details on configurating backup and restore, see Backing Up and Restoring.

backupLocation:
  name: "custom-s3-location"

certificateSecretName

Type: string
Optional
Optional
When using TLS security, this value specifies the name of a secret created to enable TLS connections in the Postgres cluster. See Configuring TLS for VMware Postgres Operator Instances.

deploymentOptions

Type: Object
Optional
Optional

This field describes the type of instance deployment.

  • continuousRestoreTarget
    Type: Boolean
    Optional
    Default: false
    This field describes if an instance is a mirror instance in Disaster Recovery setup. If the field is true, the instance becomes a continuous restore target. This instance follows the backup and WAL files from the prod instance shipped to the S3 location. It only serves read requests.
    Example:

    deploymentOptions:
  continuousRestoreTarget: true
  sourceStanzaName: <sample-stanza-from-prod-instance>

  • sourceStanzaName
    Type: String
    Optional
    Default: n/a
    This field describes the BACKUP_STANZA_NAME of the source instance. The target instance uses this stanza for the continuous restore. This field is Required for an instance where the spec.deployOptions.continuousRestoreTarget is set to true. For more details on how to get the sourceStanzaName see Configuring Disaster Recovery.
    Example:

    deploymentOptions:
  continuousRestoreTarget: true
  sourceStanzaName: default-postgres-sample-7d4e2f84-f521-43c2-b3c9-73c3fde3dc8e

storageClassName

Type: string
Optional
Default: storage class with the annotation storageclass.kubernetes.io/is-default-class
The field describes the StorageClass name of the Postgres instance Persistent Volumes (PVs), which are assigned during instance provisioning. The Operator will use existing PVs if they are present from a previous deployment, or they've been manually provisioned.
If you leave the storageClassName field empty, Kubernetes will use the default storage class identified by the storageclass.kubernetes.io/is-default-class annotation.
Providing an empty string to storageClassName will prevent dynamic provisioning, and you would need to provide your own persistent volumes for the workloads. For more details, see Class in the PersistentVolumeClaims Kubernetes documentation.
You can configure the StorageClass according to your performance needs. To understand the different configuration options see Storage Classes in the Kubernetes documentation.

Review also monitorStorageClassName.

storageSize

Type: Quantity
Optional
Default: 800M
The storage size of the Persistent Volume Claim (PVC) for a Postgres instance pod. Specify a suffix for the units (for example: 100G, 1T).

Review also monitorStorageSize.

sharedMemorySize

Type: Quantity
Optional
Default: 64Mi
The shared memory size of the /dev/shm volume used to share data across parallel workers on the Postgres instance pod. Specify a suffix for the units, for example: 100Gi, 1Ti.
The limit of the shared memory size is the data pod memory limit. This memory limit is the sum of the data memory limit and the metrics memory limit in Resources, i.e. resources.data.limit.memory + resources.metrics.limit.memory.
Note that this field is only supported on Kubernetes version 1.22 and higher. This field will be ignored if it is set for a cluster running Kubernetes version 1.21.

dataPodConfig

Type: Object
Optional

  • tolerations
    Type: array of corev1.Toleration
    Optional
    Default: []
    Defines the data pod tolerations that match specific node taints, using corev1.Toleration notation. The default is no tolerations. For details on the Toleration values, see Toleration v1 core in the Kubernetes API documentation.

    Example:
    To ensure data pods are scheduled on less optimized "admin" nodes, first create the taint on a node. This command adds the label nodetype=admin and the effect NoSchedule to the my-admin-node:

    kubectl taint nodes my-admin-node nodetype=admin:NoSchedule

    node/my-admin-node tainted

    Node my-admin-node now repels all pods that do not have the toleration nodetype=admin. Now add the toleration of the taint to the data pod by editing the instance CRD:

    ......
dataPodConfig:
  tolerations:
    - key: nodetype
      operator: Equal
      value: admin
      effect: NoSchedule
.....

    Note that a matching toleration gives permission for the scheduling of pod to tainted nodes, but does not guarantee it. Kubernetes uses node affinity to actually determine where to schedule the Pods.

    For further details, see Taints and Tolerations in the Kubernetes documenation.

  • affinity
    Type: corev1.Affinity
    Optional
    Default: podAntiAffinity object with preferred scheduling. See above sample YAML
    Defines the data pod anti-affinity rules, using corev1.Affinity notation. By default the pods of a single Postgres instance prefer to be scheduled on separate Kubernetes nodes. For details on the affinity values, see Affinity v1 core in the Kubernetes API documentation.

    Example:
    To ensure data pods are schedule on separate zones, we can set podAntiAffinity and require that the Kubernetes scheduler follow the configuration as specified below.

    ......
dataPodConfig:
  podAntiAffinity:
     requiredDuringSchedulingIgnoredDuringExecution:
     - labelSelector:
         matchExpressions:
         - key: type
           operator: In
           values:
           - data
       topologyKey: "failure-domain.beta.kubernetes.io/zone"
.....

monitorStorageClassName

Type: string
Optional
Default: storage class with the annotation storageclass.kubernetes.io/is-default-class
The field describes the StorageClass name of the Postgres instance monitor pod PVs, that are assigned during instance provisioning. The Operator will use existing PVs if they are present from a previous deployment, or use any manually provisioned PVs.
If you leave the monitorStorageClassName field empty, Kubernetes will use the default storage class identified by the storageclass.kubernetes.io/is-default-class annotation. Providing an empty string to monitorStorageClassName will prevent dynamic provisioning, and you would need to provide your own persistent volumes for the workloads.

You can configure the StorageClass according to your performance needs. To understand the different configuration options see Storage Classes in the Kubernetes documentation.

monitorStorageSize

Type: Quantity
Optional
Default: 1G
The storage size of the Persistent Volume Claim (PVC) for a Postgres instance monitor pod. Specify a suffix for the units (for example: 100G, 1T). The default value is 1G.

monitorPodConfig

Type: Object
Optional

  • tolerations
    Type: array of corev1.Toleration
    Optional
    Default: []
    Defines the monitor pod tolerations that match specific node taints, using corev1.Toleration notation. The default is no tolerations. For details on the Toleration values, see Toleration v1 core in the Kubernetes API documentation.

    Example:
    To ensure monitor pods are scheduled on less optimized "admin" nodes, first create the taint on a node. This command adds the label nodetype=admin and the effect NoSchedule to the my-admin-node:

    kubectl taint nodes my-admin-node nodetype=admin:NoSchedule

    node/my-admin-node tainted

    Node my-admin-node now repels all pods that do not have the toleration nodetype=admin. Now add the toleration of the taint to the monitor pod by editing the instance CRD:

    ......
monitorPodConfig:
  tolerations:
    - key: nodetype
      operator: Equal
      value: admin
      effect: NoSchedule
.....

    Note that a matching toleration gives permission for the scheduling of pod to tainted nodes, but does not guarantee it. Kubernetes uses node affinity to actually determine where to schedule the Pods.

    For further details, see Taints and Tolerations in the Kubernetes documenation.

  • affinity
    Type: corev1.Affinity
    Optional
    Default: podAntiAffinity object with preferred scheduling. See above sample YAML
    Defines the monitor pod anti-affinity rules, using corev1.Affinity notation. By default the pods of a single Postgres instance will prefer to be scheduled on separate Kubernetes nodes. For details on the affinity values, see Affinity v1 core in the Kubernetes API documentation.

resources

Type: Object
Optional
Defaults:
data.limits.cpu: 0.8, data.limits.memory: 800Mi
monitor.limits.cpu: 0.8, monitor.limits.memory: 800Mi
metrics.limits.cpu: 0.1, metrics.limits.memory: 100Mi
This object is a mapping of strings to ResourceRequirements that describes the compute resource requirements (requests and limits of cpu and memory).
The supported keys are data, monitor, and metrics. The data resources apply to a container in the data pod. The monitor and metrics resources apply to containers in the monitor pod.
For guidance on minimum resource requirements, refer to Minimum resource requirements.

Memory specifies the amount of memory allocated to a pod, and defines a memory limit; if a pod tries to exceed the limit, the pod is removed and replaced by a new pod. Memory units may use a suffix, for example, 4.5Gi. If left empty, the default for the Postgres instance is 800 mebibytes, or about 800 megabytes. For more details on resource allocation in Kubernetes, see Assign Memory Resources to Containers and Pods in the Kubernetes documentation.

CPU is the amount of CPU resources allocated to a pod, specified as a Kubernetes CPU unit, for example cpu: "1.2". If left empty, it inherits the default limit of its namespace (if a limit exists), or has no limit on CPU consumed. For more details on resource allocation in Kubernetes, see Assign CPU Resources to Containers and Pods in the Kubernetes documentation.

data:
  limits:
    cpu: 1
    memory: 800Mi
  requests:
    cpu: 0.8
    memory: 400Mi
monitor:
  limits:
    cpu: 1
    memory: 800Mi
  requests:
    cpu: 0.8
    memory: 400Mi
metrics:
  limits:
    cpu: 0.8
    memory: 500Mi
  requests:
    cpu: 0.2
    memory: 100Mi

Status

The status fields show the most recently observed status of the Postgres object. This information is generated by the Kubernetes operator as it reconciles the object in the cluster.

currentPgbackrestConfigResourceVersion

Type: string
This field reflects the revision number of the associated Kubernetes secret holding pgbackrest configuration.

currentState

Type: string
This field shows the status of the Postgres object. Possible values are Created, Pending, Unavailable, and Running.

backups

Type: Object

  • lastSuccessful
    Type: object
    Optional
    Default: []
    lastSuccessful describes the most recent successful backup that was performed for this Postgres instance.

    • name
      Type: string
      The name of the PostgresBackup resource.
    • observedResourceVersion
      Type: string
      The last PostgresBackup resource version that was observed by the Operator.
    • timeCompleted
      Type: string
      The time at which the PostgresBackup completed.
      Example: 
      lastSuccessful:
  name: my-postgres-backup
  observedResourceVersion: "24326"
  timeCompleted: "2022-06-29T18:01:23Z"

  • lastCreated
    Type: object
    Optional
    Default: []
    lastCreated describes the most recently created backup for this Postgres instance.

    • name
      Type: string
      The name of the PostgresBackup resource.
    • observedResourceVersion
      Type: string
      The last PostgresBackup resource version that was observed by the Operator.
    • phase
      Type: string
      The status of the PostgresBackup resource.
      Example: 
      lastCreated:
  name: new-postgres-backup
  observedResourceVersion: "24328"
  phase: Running

binding

Type: LocalObjectReference
This field shows the name of the Secret for service bindings. For more information, see service binding spec.

dbVersion

Type: string
This field shows the major and minor version of the Postgres database used for this instance.

lastRestoreTime

Type: time
This field indicates the timeCompleted value of the last backup that was restored. Use this field to check the status of the continuous restore.

conditions

Type: object
This field contains details about the state of the Postgres instance. All possible conditions are listed below:

  • CustomConfigStatus
    Type: object
    Optional
    CustomConfigStatus provides the status of applying custom configuration (including custom Pghba config). The possible reasons include:
    • Pending indicating that a custom configuration is currently being applied
    • InvalidConfigSettings indicating that there is an error with the custom configuration
    • ConfigApplied indicating success. In case of an error, additional information can be accessed via the condition's message property.
check-circle-line exclamation-circle-line close-line
Scroll to top icon