Project: KubeDB by AppsCode (App Definition and Development / Database)
File: postgres.md

title: Postgres CRD menu: docs_{{ .version }}: identifier: pg-postgres-concepts name: Postgres parent: pg-concepts-postgres weight: 10 menuname: docs{{ .version }} sectionmenuid: guides New to KubeDB? Please start . `Postgres` is a Kubernetes `Custom Resource Definitions` (CRD). It provides declarative configuration for in a Kubernetes native way. You only need to describe the desired database configuration in a Postgres object, and the KubeDB operator will create Kubernetes objects in the desired state for you. As with all other Kubernetes objects, a Postgres needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section. Below is an example Postgres object. ```yaml apiVersion: kubedb.com/v1alpha2 kind: Postgres metadata: name: p1 namespace: demo spec: version: "13.13" replicas: 2 standbyMode: Hot streamingMode: Asynchronous leaderElection: leaseDurationSeconds: 15 renewDeadlineSeconds: 10 retryPeriodSeconds: 2 authSecret: name: p1-auth storageType: "Durable" storage: storageClassName: standard accessModes: ReadWriteOnce resources: requests: storage: 1Gi init: script: configMap: name: pg-init-script monitor: agent: prometheus.io/operator prometheus: serviceMonitor: labels: app: kubedb interval: 10s configSecret: name: pg-custom-config podTemplate: metadata: annotations: passMe: ToDatabasePod controller: annotations: passMe: ToStatefulSet spec: serviceAccountName: my-custom-sa schedulerName: my-scheduler nodeSelector: disktype: ssd imagePullSecrets: name: myregistrykey env: name: POSTGRES_DB value: pgdb resources: requests: memory: "64Mi" cpu: "250m" limits: memory: "128Mi" cpu: "500m" serviceTemplates: alias: primary metadata: annotations: passMe: ToService spec: type: NodePort ports: name: http port: 5432 alias: standby metadata: annotations: passMe: ToReplicaService spec: type: NodePort ports: name: http port: 5432 terminationPolicy: "Halt" ``` `spec.version` is a required field that specifies the name of the crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `PostgresVersion` resources, ```bash $ kubectl get pgversion NAME VERSION DB_IMAGE DEPRECATED AGE 10.2 10.2 kubedb/postgres:10.2 true 44m 10.2-v1 10.2 kubedb/postgres:10.2-v2 true 44m 10.2-v2 10.2 kubedb/postgres:10.2-v3 44m 10.2-v3 10.2 kubedb/postgres:10.2-v4 44m 10.2-v4 10.2 kubedb/postgres:10.2-v5 44m 10.2-v5 10.2 kubedb/postgres:10.2-v6 44m 10.6 10.6 kubedb/postgres:10.6 44m 10.6-v1 10.6 kubedb/postgres:10.6-v1 44m 10.6-v2 10.6 kubedb/postgres:10.6-v2 44m 10.6-v3 10.6 kubedb/postgres:10.6-v3 44m 11.1 11.1 kubedb/postgres:11.1 44m 11.1-v1 11.1 kubedb/postgres:11.1-v1 44m 11.1-v2 11.1 kubedb/postgres:11.1-v2 44m 11.1-v3 11.1 kubedb/postgres:11.1-v3 44m 11.2 11.2 kubedb/postgres:11.2 44m 11.2-v1 11.2 kubedb/postgres:11.2-v1 44m 9.6 9.6 kubedb/postgres:9.6 true 44m 9.6-v1 9.6 kubedb/postgres:9.6-v2 true 44m 9.6-v2 9.6 kubedb/postgres:9.6-v3 44m 9.6-v3 9.6 kubedb/postgres:9.6-v4 44m 9.6-v4 9.6 kubedb/postgres:9.6-v5 44m 9.6-v5 9.6 kubedb/postgres:9.6-v6 44m 9.6.7 9.6.7 kubedb/postgres:9.6.7 true 44m 9.6.7-v1 9.6.7 kubedb/postgres:9.6.7-v2 true 44m 9.6.7-v2 9.6.7 kubedb/postgres:9.6.7-v3 44m 9.6.7-v3 9.6.7 kubedb/postgres:9.6.7-v4 44m 9.6.7-v4 9.6.7 kubedb/postgres:9.6.7-v5 44m 9.6.7-v5 9.6.7 kubedb/postgres:9.6.7-v6 44m ``` `spec.replicas` specifies the total number of primary and standby nodes in Postgres database cluster configuration. One pod is selected as Primary and others act as standby replicas. KubeDB uses `PodDisruptionBudget` to ensure that majority of the replicas are available during . To learn more about how to setup a HA PostgreSQL cluster in KubeDB, please visit . `spec.standby` is an optional field that specifies the standby mode (Warm / Hot) to use for standby replicas. In hot standby mode, standby replicas can accept connection and run read-only queries. In warm standby mode, standby replicas can't accept connection and only used for replication purpose. `spec.streamingMode` is an optional field that specifies the streaming mode (Synchronous / Asynchronous) of the standby replicas. KubeDB currently supports only Asynchronous streaming mode. There are three fields under Postgres CRD's `spec.leaderElection`. These values defines how fast the leader election can

`leaseDurationSeconds`: This is the duration in seconds that non-leader candidates will wait to force acquire leadership. This is measured against time of last observed ack. Default 15 sec. `renewDeadlineSeconds`: This is the duration in seconds that the acting master will retry refreshing leadership before giving up. Normally, LeaseDuration \* 2 / 3. Default 10 sec. `retryPeriodSeconds`: This is the duration in seconds the LeaderElector clients should wait between tries of actions. Normally, LeaseDuration / 3. Default 2 sec. If the Cluster machine is powerful, user can reduce the times. But, Do not make it so little, in that case Postgres will restarts very often. `spec.authSecret` is an optional field that points to a Secret used to hold credentials for `postgres` database. If not set, KubeDB operator creates a new Secret with name `{postgres-name}-auth` that hold username and password for `postgres` database. If you want to use an existing or custom secret, please specify that when creating the Postgres object using `spec.authSecret.name`. This Secret should contain superuser username as `POSTGRESUSER` key and superuser password as `POSTGRESPASSWORD` key. Secrets provided by users are not managed by KubeDB, and therefore, won't be modified or garbage collected by the KubeDB operator (version >= 0.13.0). Example: ```bash $ kubectl create secret generic p1-auth -n demo \ --from-literal=POSTGRES_USER=not@user \ --from-literal=POSTGRES_PASSWORD=not@secret secret "p1-auth" created ``` ```bash $ kubectl get secret -n demo p1-auth -o yaml apiVersion: v1 data: POSTGRES_PASSWORD: bm90QHNlY3JldA== POSTGRES_USER: bm90QHVzZXI= kind: Secret metadata: creationTimestamp: 2018-09-03T11:25:39Z name: p1-auth namespace: demo resourceVersion: "1677" selfLink: /api/v1/namespaces/demo/secrets/p1-auth uid: 15b3e8a1-af6c-11e8-996d-0800270d7bae type: Opaque ``` `spec.storageType` is an optional field that specifies the type of storage to use for database. It can be either `Durable` or `Ephemeral`. The default value of this field is `Durable`. If `Ephemeral` is used then KubeDB will create Postgres database using volume. In this case, you don't have to specify `spec.storage` field. If you don't set `spec.storageType:` to `Ephemeral` then `spec.storage` field is required. This field specifies the StorageClass of PVCs dynamically allocated to store data for the database. This storage spec will be passed to the StatefulSet created by KubeDB operator to run database pods. You can specify any StorageClass available in your cluster with appropriate resource requests. `spec.storage.storageClassName` is the name of the StorageClass used to provision PVCs. PVCs dont necessarily have to request a class. A PVC with its storageClassName set equal to "" is always interpreted to be requesting a PV with no class, so it can only be bound to PVs with no class (no annotation or one set equal to ""). A PVC with no storageClassName is not quite the same and is treated differently by the cluster depending on whether the DefaultStorageClass admission plugin is turned on. `spec.storage.accessModes` uses the same conventions as Kubernetes PVCs when requesting storage with specific access modes. `spec.storage.resources` can be used to request specific quantities of storage. This follows the same resource model used by PVCs. To learn how to configure `spec.storage`, please visit the links below: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims `spec.init` is an optional section that can be used to initialize a newly created Postgres database. PostgreSQL databases can be initialized from these three ways: Initialize from Script Initialize from Snapshot To initialize a PostgreSQL database using a script (shell script, db migrator, etc.), set the `spec.init.script` section when creating a Postgres

`script` must have the following information: : Where your script is loaded from. Below is an example showing how a script from a configMap can be used to initialize a PostgreSQL database. ```yaml apiVersion: kubedb.com/v1alpha2 kind: Postgres metadata: name: postgres-db namespace: demo spec: version: "13.13" init: script: configMap: name: pg-init-script ``` In the above example, Postgres will execute provided script once the database is running. For more details tutorial on how to initialize from script, please visit . PostgreSQL managed by KubeDB can be monitored with builtin-Prometheus and Prometheus operator out-of-the-box. To learn more, `spec.configSecret` is an optional field that allows users to provide custom configuration for PostgreSQL. This field accepts a . You can use any Kubernetes supported volume source such as `configMap`, `secret`, `azureDisk` etc. To learn more about how to use a custom configuration file see . KubeDB allows providing a template for database pod through `spec.podTemplate`. KubeDB operator will pass the information provided in `spec.podTemplate` to the StatefulSet created for Postgres database. KubeDB accept following fields to set in `spec.podTemplate:` metadata annotations (pod's annotation) controller annotations (statefulset's annotation) spec: serviceAccountName env resources initContainers imagePullSecrets nodeSelector affinity schedulerName tolerations priorityClassName priority securityContext livenessProbe readinessProbe lifecycle Uses of some field of `spec.podTemplate` is described below, `serviceAccountName` is an optional field supported by KubeDB Operator (version 0.13.0 and higher) that can be used to specify a custom service account to fine tune role based access control. If this field is left empty, the KubeDB operator will create a service account name matching Postgres crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. Follow the guide to grant necessary permissions in this scenario. `spec.podTemplate.spec.env` is an optional field that specifies the environment variables to pass to the Postgres docker image. To know about supported environment variables, please visit . Note that, the KubeDB operator does not allow `POSTGRESUSER` and `POSTGRESPASSWORD` environment variable to set in `spec.podTemplate.spec.env`. If you want to set the superuser username and password, please use `spec.authSecret` instead described earlier. If you try to set `POSTGRESUSER` or `POSTGRESPASSWORD` environment variable in Postgres crd, KubeDB operator will reject the request with following error, ```ini Error from server (Forbidden): error when creating "./postgres.yaml": admission webhook "postgres.validators.kubedb.com" denied the request: environment variable POSTGRES_PASSWORD is forbidden to use in Postgres spec ``` Also, note that KubeDB does not allow to update the environment variables as updating them does not have any effect once the database is created. If you try to update environment variables, KubeDB operator will reject the request with following error, ```ini Error from server (BadRequest): error when applying patch: ... for: "./postgres.yaml": admission webhook "postgres.validators.kubedb.com" denied the request: precondition failed for: ... At least one of the following was changed: apiVersion kind name namespace spec.standby spec.streaming spec.authSecret

spec.storage spec.podTemplate.spec.nodeSelector spec.init ``` `spec.podTemplate.spec.imagePullSecrets` is an optional field that points to secrets to be used for pulling docker image if you are using a private docker registry. For more details on how to use private docker registry, please visit . `spec.podTemplate.spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see . `spec.podTemplate.spec.resources` is an optional field. This can be used to request compute resources required by the database pods. To learn more, visit . KubeDB creates two different services for each Postgres instance. One of them is a master service named `<postgres-name>` and points to the Postgres `Primary` pod/node. Another one is a replica service named `<postgres-name>-replicas` and points to Postgres `replica` pods/nodes. These `master` and `replica` services can be customized using and respectively. You can provide template for the `master` service using `spec.serviceTemplate`. This will allow you to set the type and other properties of the service. If `spec.serviceTemplate` is not provided, KubeDB will create a `master` service of type `ClusterIP` with minimal settings. KubeDB allows following fields to set in `spec.serviceTemplate`: metadata: annotations spec: type ports clusterIP externalIPs loadBalancerIP loadBalancerSourceRanges externalTrafficPolicy healthCheckNodePort sessionAffinityConfig See to understand these fields in detail. You can provide template for the `replica` service using `spec.replicaServiceTemplate`. If `spec.replicaServiceTemplate` is not provided, KubeDB will create a `replica` service of type `ClusterIP` with minimal settings. The fileds of `spec.replicaServiceTemplate` is similar to `spec.serviceTemplate`, that is: metadata: annotations spec: type ports clusterIP externalIPs loadBalancerIP loadBalancerSourceRanges externalTrafficPolicy healthCheckNodePort See to understand these fields in detail. `terminationPolicy` gives flexibility whether to `nullify`(reject) the delete operation of `Postgres` crd or which resources KubeDB should keep or delete when you delete `Postgres` crd. KubeDB provides following four termination policies: DoNotTerminate Halt Delete (`Default`) WipeOut When `terminationPolicy` is `DoNotTerminate`, KubeDB takes advantage of `ValidationWebhook` feature in Kubernetes 1.9.0 or later clusters to provide safety from accidental deletion of database. If admission webhook is enabled, KubeDB prevents users from deleting the database as long as the `spec.terminationPolicy` is set to `DoNotTerminate`. Following table show what KubeDB does when you delete Postgres crd for different termination policies, | Behavior | DoNotTerminate | Halt | Delete | WipeOut | | - | :: | :: | :: | :: | | 1. Block Delete operation | &#10003; | &#10007; | &#10007; | &#10007; | | 2. Create Dormant Database | &#10007; | &#10003; | &#10007; | &#10007; | | 3. Delete StatefulSet | &#10007; | &#10003; | &#10003; | &#10003; | | 4. Delete Services | &#10007; | &#10003; | &#10003; | &#10003; | | 5. Delete PVCs | &#10007; | &#10007; | &#10003; | &#10003; | | 6. Delete Secrets | &#10007; | &#10007; | &#10007; | &#10003; | | 7. Delete Snapshots | &#10007; | &#10007; | &#10007; | &#10003; | | 8. Delete Snapshot data from bucket | &#10007; | &#10007; | &#10007; | &#10003; | If you don't specify `spec.terminationPolicy` KubeDB uses `Halt` termination policy by default. Learn how to use KubeDB to run a PostgreSQL database . Want to hack on KubeDB? Check our .