This topic describes the available fields of the Postgres Custom Resource Definition.
apiVersion: sql.tanzu.vmware.com/v1 kind: Postgres metadata: name: postgres-sample spec:
pgConfig: dbname: postgres-sample username: pgadmin appUser: pgappuser postgresVersion: name: postgres-14 # View available versions with kubectl get postgresversion serviceType: ClusterIP
seccompProfile: type: RuntimeDefault imagePullSecret: name: regsecret
storageClassName: standard storageSize: 800M dataPodConfig:
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
monitorStorageClassName: standard monitorStorageSize: 1G monitorPodConfig:
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: 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
Applying this resource causes the Kubernetes Operator to create a StatefulSet with a single Pod and three containers. One container runs the MySQL database software, one runs the components to support backups, and the third runs the mysqld_exporter (for monitoring). The MySQL Pod mounts a persistent volume claim (PVC) which holds the MySQL data.
You specify Postgres instance configuration properties to the Postgres operator with a YAML-formatted manifest file. A sample manifest file is provided in postgres.yaml. The current version of the manifest supports configuring the Postgres instance name, default database name and user name, backup credentials, and memory, cpu, and storage settings for the instance. See also Deploying a New Postgres Instance for information about deploying a new Postgres instance using a manifest file.
The metadata follows standard Kubernetes conventions. See more at https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#metadata
The metadata sets the name, namespace, labels, annotations, and more for the Postgres object.
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.
The spec describes the desired state for the Postgres object.
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.
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 with read-write privileges. It will be used to bind your application with the Postgres instance. See Creating Service Bindings
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-14). For more information see Specifying the Tanzu Postgres Version.
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.
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"
For more information, see Internal Load Balancer, and Annotations in the Kubernetes documentation.
Type: corev1.SeccompProfile
Optional
Default: RuntimeDefault
Enables the use of Secure Compute Mode (seccomp) profiles for the instances. The default profile RuntimeDefault is the most restrictive, with a strong set of security defaults for container syscalls. Set to Unconfined to disable seccomp profiles. Set to Localhost to indicates the path of a pre-configured profile 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.
Type: Object
Optional
Default: enabled: false
Specifies whether the Postgres instance is created in a single or cluster mode configuration. The default, false, creates a single node cluster. See Configuring High Availability for more information about clustered Postgres deployments.
highAvailability:
enabled: true
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.
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"
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 Tanzu Postgres Instances.
Type: Object
Optional
Optional
This field describes the type of instance deployment.
continuousRestoreTarget
Type: Boolean
Optional
Default: false
For a Disaster Recover or mirror target instance, this field describes the role of the instance. If the field is true, the instance becomes a continuous restore target, but the Postgres server is not started. The instance's purpose is only to restore from the source instance backup; it does not accept any read/write 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
Type: string
Optional
Default: standard
The Storage Class name to use for dynamically provisioning Persistent Volumes (PVs) for a Postgres instance pod. If the PVs already exist, either from a previous deployment or because you manually provisioned the PVs, then the Operator uses the existing PVs. You can configure the Storage Class according to your performance needs. To understand the different configuration options see Storage Classes in the Kubernetes documentation.
IMPORTANT: Edit the default standard storage class with your storage class name.
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).
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"
.....
Type: string
Optional
Default: standard
The Storage Class name to use for dynamically provisioning Persistent Volumes (PVs) for the Postgres monitor pod. By default it is set to standard. The default value can be changed at the time of the Postgres instance initialization but the monitorStorageClassName must match the Postgres instance storageClassName.
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.
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.
Type: Object
Optional
Defaults: data.limits.cpu: 0.8, data.limits.memory: 800Mi
Defaults: monitor.limits.cpu: 0.8, monitor.limits.memory: 800Mi
Defaults: 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.
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
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.
Type: string
This field reflects the revision number of the associated Kubernetes secret holding pgbackrest configuration.
Type: string
This field shows the status of the Postgres object. Possible values are Created, Pending, and Running.
Type: Object
lastSuccessful
Type: object
Optional
Default: []
lastSuccessful describes the most recent successful backup that was performed for this Postgres instance.
- name</br>
**Type**: string</br>
The name of the PostgresBackup resource
- observedResourceVersion</br>
**Type**: string</br>
The resource version of the PostgresBackup resource that was last observed by the operator
- timeCompleted</br>
**Type**: string</br>
The time at which the PostgresBackup completed
<br/>**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</br>
**Type**: string</br>
The name of the PostgresBackup resource
- observedResourceVersion</br>
**Type**: string</br>
The resource version of the PostgresBackup resource that was last observed by the operator
- phase</br>
**Type**: string</br>
The status of the PostgresBackup resource
<br/>**Example**:
```
lastCreated:
name: new-postgres-backup
observedResourceVersion: "24328"
phase: Running
```
Type: LocalObjectReference
This field shows the name of the Secret for service bindings. For more information, see service binding spec.
Type: string
This field shows the major and minor version of the Postgres database used for this instance.
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.
