PGO YAML

pgo.yaml Configuration

The pgo.yaml file contains many different configuration settings as described in this section of the documentation.

The pgo.yaml file is broken into major sections as described below:

Cluster

Setting Definition
BasicAuth If set to "true" will enable Basic Authentication. If set to "false", will allow a valid Operator user to successfully authenticate regardless of the value of the password provided for Basic Authentication. Defaults to "true".
CCPImagePrefix newly created containers will be based on this image prefix (e.g. crunchydata), update this if you require a custom image prefix
CCPImageTag newly created containers will be based on this image version (e.g. centos7-12.2-4.3.0), unless you override it using the –ccp-image-tag command line flag
Port the PostgreSQL port to use for new containers (e.g. 5432)
PGBadgerPort the port used to connect to pgbadger (e.g. 10000)
ExporterPort the port used to connect to postgres exporter (e.g. 9187)
User the PostgreSQL normal user name
Database the PostgreSQL normal user database
Replicas the number of cluster replicas to create for newly created clusters, typically users will scale up replicas on the pgo CLI command line but this global value can be set as well
PgmonitorPassword the password to use for pgmonitor metrics collection if you specify –metrics when creating a PG cluster
Metrics boolean, if set to true will cause each new cluster to include crunchy-collect as a sidecar container for metrics collection, if set to false (default), users can still add metrics on a cluster-by-cluster basis using the pgo command flag –metrics
Badger boolean, if set to true will cause each new cluster to include crunchy-pgbadger as a sidecar container for static log analysis, if set to false (default), users can still add pgbadger on a cluster-by-cluster basis using the pgo create cluster command flag –pgbadger
Policies optional, list of policies to apply to a newly created cluster, comma separated, must be valid policies in the catalog
PasswordAgeDays optional, if set, will set the VALID UNTIL date on passwords to this many days in the future when creating users or setting passwords, defaults to 60 days
PasswordLength optional, if set, will determine the password length used when creating passwords, defaults to 8
ServiceType optional, if set, will determine the service type used when creating primary or replica services, defaults to ClusterIP if not set, can be overridden by the user on the command line as well
Backrest optional, if set, will cause clusters to have the pgbackrest volume PVC provisioned during cluster creation
BackrestPort currently required to be port 2022
DisableAutofail optional, if set, will disable autofail capabilities by default in any newly created cluster
DisableReplicaStartFailReinit if set to true will disable the detection of a “start failed” states in PG replicas, which results in the re-initialization of the replica in an attempt to bring it back online
PodAntiAffinity either preferred, required or disabled to either specify the type of affinity that should be utilized for the default pod anti-affinity applied to PG clusters, or to disable default pod anti-affinity all together (default preferred)
SyncReplication boolean, if set to true will automatically enable synchronous replication in new PostgreSQL clusters (default false)
DefaultInstanceMemory string, matches a Kubernetes resource value. If set, it is used as the default value of the memory request for each instance in a PostgreSQL cluster. The example configuration uses 128Mi which is very low for a PostgreSQL cluster, as the default amount of shared memory PostgreSQL requests is 128Mi. However, for test clusters, this value is acceptable as the shared memory buffers won’t be stressed, but you should absolutely consider raising this in production. If the value is unset, it defaults to 512Mi, which is a much more appropriate minimum.
DefaultBackrestMemory string, matches a Kubernetes resource value. If set, it is used as the default value of the memory request for the pgBackRest repository (default 48Mi)
DefaultPgBouncerMemory string, matches a Kubernetes resource value. If set, it is used as the default value of the memory request for pgBouncer instances (default 24Mi)

Storage

Setting Definition
PrimaryStorage required, the value of the storage configuration to use for the primary PostgreSQL deployment
BackupStorage required, the value of the storage configuration to use for backups, including the storage for pgbackrest repo volumes
ReplicaStorage required, the value of the storage configuration to use for the replica PostgreSQL deployments
BackrestStorage required, the value of the storage configuration to use for the pgbackrest shared repository deployment created when a user specifies pgbackrest to be enabled on a cluster
WALStorage optional, the value of the storage configuration to use for PostgreSQL Write Ahead Log
StorageClass for a dynamic storage type, you can specify the storage class used for storage provisioning(e.g. standard, gold, fast)
AccessMode the access mode for new PVCs (e.g. ReadWriteMany, ReadWriteOnce, ReadOnlyMany). See below for descriptions of these.
Size the size to use when creating new PVCs (e.g. 100M, 1Gi)
Storage.storage1.StorageType supported values are either dynamic, create, if not supplied, create is used
SupplementalGroups optional, if set, will cause a SecurityContext to be added to generated Pod and Deployment definitions
MatchLabels optional, if set, will cause the PVC to add a matchlabels selector in order to match a PV, only useful when the StorageType is create, when specified a label of key=value is added to the PVC as a match criteria

Storage Configuration Examples

In pgo.yaml, you will need to configure your storage configurations depending on which storage you are wanting to use for Operator provisioning of Persistent Volume Claims. The examples below are provided as a sample. In all the examples you are free to change the Size to meet your requirements of Persistent Volume Claim size.

HostPath Example

HostPath is provided for simple testing and use cases where you only intend to run on a single Linux host for your Kubernetes cluster.

  hostpathstorage:
    AccessMode:  ReadWriteMany
    Size:  1G
    StorageType:  create

NFS Example

In the following NFS example, notice that the SupplementalGroups setting is set, this can be whatever GID you have your NFS mount set to, typically we set this nfsnobody as below. NFS file systems offer a ReadWriteMany access mode.

  nfsstorage:
    AccessMode:  ReadWriteMany
    Size:  1G
    StorageType:  create
    SupplementalGroups:  65534

Storage Class Example

Most Storage Class providers offer ReadWriteOnce access modes, but refer to your provider documentation for other access modes it might support.

  storageos:
    AccessMode:  ReadWriteOnce
    Size:  1G
    StorageType:  dynamic
    StorageClass:  fast

Miscellaneous (Pgo)

Setting Definition
Audit boolean, if set to true will cause each apiserver call to be logged with an audit marking
ConfigMapWorkerCount The number of workers created for the worker queue within the ConfigMap controller (defaults to 2)
ControllerGroupRefreshInterval The refresh interval for any per-namespace controller with a refresh interval (defaults to 60 seconds)
NamespaceRefreshInterval The refresh interval for the namespace controller (defaults to 60 seconds)
PgclusterWorkerCount The number of workers created for the worker queue within the PGCluster controller (defaults to 1)
PGOImagePrefix image tag prefix to use for the Operator containers
PGOImageTag image tag to use for the Operator containers
PGReplicaWorkerCount The number of workers created for the worker queue within the PGReplica controller (defaults to 1)
PGTaskWorkerCount The number of workers created for the worker queue within the PGTask controller (defaults to 1)

Storage Configuration Details

You can define n-number of Storage configurations within the pgo.yaml file. Those Storage configurations follow these conventions -

  • they must have lowercase name (e.g. storage1)
  • they must be unique names (e.g. mydrstorage, faststorage, slowstorage)

These Storage configurations are referenced in the BackupStorage, ReplicaStorage, and PrimaryStorage configuration values. However, there are command line options in the pgo client that will let a user override these default global values to offer you the user a way to specify very targeted storage configurations when needed (e.g. disaster recovery storage for certain backups).

You can set the storage AccessMode values to the following:

  • ReadWriteMany - mounts the volume as read-write by many nodes
  • ReadWriteOnce - mounts the PVC as read-write by a single node
  • ReadOnlyMany - mounts the PVC as read-only by many nodes

These Storage configurations are validated when the pgo-apiserver starts, if a non-valid configuration is found, the apiserver will abort. These Storage values are only read at apiserver start time.

The following StorageType values are possible -

  • dynamic - this will allow for dynamic provisioning of storage using a StorageClass.
  • create - This setting allows for the creation of a new PVC for each PostgreSQL cluster using a naming convention of clustername. When set, the Size, AccessMode settings are used in constructing the new PVC.

The operator will create new PVCs using this naming convention: dbname where dbname is the database name you have specified. For example, if you run:

pgo create cluster example1 -n pgouser1

It will result in a PVC being created named example1 and in the case of a backup job, the pvc is named example1-backup

Note, when Storage Type is create, you can specify a storage configuration setting of MatchLabels, when set, this will cause a selector of key=value to be added into the PVC, this will let you target specific PV(s) to be matched for this cluster. Note, if a PV does not match the claim request, then the cluster will not start. Users that want to use this feature have to place labels on their PV resources as part of PG cluster creation before creating the PG cluster. For example, users would add a label like this to their PV before they create the PG cluster:

kubectl label pv somepv myzone=somezone -n pgouser1

If you do not specify MatchLabels in the storage configuration, then no match filter is added and any available PV will be used to satisfy the PVC request. This option does not apply to dynamic storage types.

Example PV creation scripts are provided that add labels to a set of PVs and can be used for testing: $COROOT/pv/create-pv-nfs-labels.sh in that example, a label of crunchyzone=red is set on a set of PVs to test with.

The pgo.yaml includes a storage config named nfsstoragered that when used will demonstrate the label matching. This feature allows you to support n-number of NFS storage configurations and supports spreading a PG cluster across different NFS storage configurations.

Overriding Storage Configuration Defaults

pgo create cluster testcluster --storage-config=bigdisk -n pgouser1

That example will create a cluster and specify a storage configuration of bigdisk to be used for the primary database storage. The replica storage will default to the value of ReplicaStorage as specified in pgo.yaml.

pgo create cluster testcluster2 --storage-config=fastdisk --replica-storage-config=slowdisk -n pgouser1

That example will create a cluster and specify a storage configuration of fastdisk to be used for the primary database storage, while the replica storage will use the storage configuration slowdisk.

pgo backup testcluster --storage-config=offsitestorage -n pgouser1

That example will create a backup and use the offsitestorage storage configuration for persisting the backup.

Using Storage Configurations for Disaster Recovery

A simple mechanism for partial disaster recovery can be obtained by leveraging network storage, Kubernetes storage classes, and the storage configuration options within the Operator.

For example, if you define a Kubernetes storage class that refers to a storage backend that is running within your disaster recovery site, and then use that storage class as a storage configuration for your backups, you essentially have moved your backup files automatically to your disaster recovery site thanks to network storage.