This section describes how to deploy a Postgres instance to your Kubernetes system, using the Postgres operator. You can use these instructions either to deploy a brand new instance (provisioning new, empty Persistent Volume Claims in Kubernetes), or to update an earlier instance, re-using existing Persistent Volumes if available.

Prerequisites

  1. Ensure you have installed the Tanzu Postgres docker images and created the Postgres operator in your Kubernetes system. See Installing Tanzu Postgres and Creating a Postgres Operator Release for instructions.

    Verify that the Postgres operator is installed and running in your system:

    $ helm list
    
    NAME             	REVISION	UPDATED                 	STATUS  	CHART                  	APP VERSION	   NAMESPACE
    postgres-operator	1       	Mon Jul 20 16:03:19 2020	DEPLOYED	postgres-operator-1.0.0	v1.0.0    	   default
    
  2. Request an expandable storage volume for your Postgres instance, to be able to resize the volume online. For more information, see Allow Volume Expansion. To verify if your storage class allows expansion, check the ALLOWVOLUMEEXPANSION field using:

    $ kubectl get storageclasses
    

    The output would be similar to:

    NAME                 PROVISIONER                RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
    standard (default)   k8s.io/minikube-hostpath   Delete          Immediate           true                  4h25m
    

Configuring a Postgres Instance

  1. Go to the directory where you unpacked the Tanzu Postgres distribution.

    $ cd postgres-v*
    
  2. Create a Kubernetes manifest file using a filename of your choice, for example pg-instance-example.yaml, specifying your Postgres instance configuration values. For example:

    apiVersion: sql.tanzu.vmware.com/v1
    kind: Postgres
    metadata:
      name: pg-instance-example
    spec:
      memory: 800Mi
      cpu: "0.8"
      storageClassName: standard
      storageSize: 10G
      pgConfig:
         dbname: pg-instance-example
         username: pgadmin
      serviceType: LoadBalancer
      highAvailability:
         enabled: false
      backupLocationSecret:
         name:
    

    Where:

    • name (required) in the Metadata section, is the name of the created Postgres instance. The Postgres operator appends -0 to the end of the name when it creates the instance pod, for example pg-instance-example-0. The new Postgres instance includes a default database with the same name as the instance. To specify a different database name from the instance name, see Creating a Custom Database Name and User Account.
    • memory (required) is the amount of memory to allocate to the Postgres instance pod, in bytes. The default for the Postgres instance is 800 mebibytes, or about 800 megabytes. You can express memory as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. Ensure that you do not exceed your Kubernetes nodes' memory capacity. This field can be updated on a running instance by using the kubectl apply -f updated_manifest_yaml_file command.
    • cpu (required) is the amount of cpu the Postgres instance requires, in millicores. Ensure that you do not exceed your Kubernetes nodes' CPU capacity. This field can be updated on a running instance.
    • storageClassName (optional) specifies the Kubernetes StorageClass storage type. The standard StorageClass is the default Kubernetes storage class. This field cannot be updated on a running instance.
    • storageSize (required) is the size of the pgdata Persistent Volume Claim (PVCs) for the Postgres instance. Alter the default value from 100M to 10G.
    • dbname (optional) see Custom Database Name and User Account. This field can not be updated on a running instance.
    • username(optional) see Custom Database Name and User Account. This field can not be updated on a running instance.
    • serviceType:<LoadBalancer|ClusterIP> (optional) specifies the type of publishing service for your Postgres instance. If left empty, the default is LoadBalancer. For more information see Kubernetes Publishing Services. This field can be updated on a running instance by using the kubectl apply -f command.
    • highAvailability:<false|true> (optional) determines if the created instance will be in a single or cluster mode configuration. The default false is single node. See Configuring High Availability on how to create a clustered Postgres instance configuration. This field can be updated on a running instance by using the kubectl apply -f command.
    • name in the backupLocationSecret section defines the access secret for a S3 compatible backup storage location. To enable S3 storage backup at the time of the instance deployment, provide the required S3 secret file. For details on how to create the S3 secret, see Backing Up and Restoring Tanzu Postgres. Leave the field empty if you are not planning to enable backups at initialization time. You may edit and re-apply the instance manifest file at a later stage, when you have your S3 secret configured.

    The minimum entries for the configuration yaml file are:

    apiVersion: sql.tanzu.vmware.com/v1
    kind: Postgres
    metadata:
      name: pg-instance-example
    

    All unspecified yaml fields are set to the default values:

    Field Default Value DataType
    DefaultCPU 0.8 Float
    DefaultMemory 800Mi Int
    DefaultStorageClassName standard String
    DefaultStorageSize 100M Int
    DefaultDatabaseUsername pgadmin String
    DefaultServiceType LoadBalancer String

    IMPORTANT: The default values for spec.memory, spec.CPU, spec.storageClassName, and spec.storageSize specify a very small Postgres instance that may be too limited for your use case.

Specifying Namespaces

The example yaml configuration manifest uses the default namespace, therefore this field is not specifically set in the file. If you wish to create instances in a different namespace, ensure that you have created your registry secrets in the new namespace and defined the namespace field in the yaml. For example, to create a postgres instance pg-instance-example in the postgres-databases namespace, edit the file accordingly:

apiVersion: sql.tanzu.vmware.com/v1
kind: Postgres
metadata:
  name: pg-instance-example
  namespace: postgres-databases
spec:
  memory: 800Mi
  cpu: "0.8"
  storageClassName: standard
  storageSize: 10G
  pgConfig:
     dbname: pg-instance-example
     username: pgadmin
  serviceType: LoadBalancer
  highAvailability:
     enabled: false
  backupLocationSecret:
     name:

Specifying Multiple Instances

You may create multiple Postgres instances with the same yaml file, separating the configurations with three ---:

apiVersion: sql.tanzu.vmware.com/v1
kind: Postgres
metadata:
  name: pg-instance-example
  namespace: postgres-databases
spec:
  memory: 800Mi
  cpu: "0.8"
  storageClassName: standard
  storageSize: 10G
  pgConfig:
     dbname: pg-instance-example
     username: pgadmin
  serviceType: LoadBalancer
  highAvailability:
     enabled: false
  backupLocationSecret:
     name:
---
apiVersion: sql.tanzu.vmware.com/v1
kind: Postgres
metadata:
  name: pg-mypostgres
  namespace: postgres-databases
spec:
  memory: 800Mi
  cpu: "0.8"
  storageClassName: standard
  storageSize: 10G
  pgConfig:
      dbname: my-postgres
      username: pgadmin
  serviceType: LoadBalancer
  highAvailability:
      enabled: false
  backupLocationSecret:
      name:

Custom Database Name and User Account

When creating a Postgres instance, the default database name matches the instance name, as described in step 2 in Configuring the Postgres Instance Manifest file.

To create a custom database name and account username, configure the pgConfig field values in the manifest file. The following example creates a Postgres instance called pg-instance-example, with a database named pg-instance-example and a user called pgadmin.

apiVersion: sql.tanzu.vmware.com/v1
kind: Postgres
metadata:
  name: pg-instance-example
spec:
  memory: 800Mi
  cpu: "0.8"
  storageClassName: standard
  storageSize: 10G
  pgConfig:
     dbname: pg-instance-example
     username: pgadmin
  ....

Where:

  • dbname (optional) is the name of the default database created when the Postgres instance is initiated. The dbname string must be less than 63 characters, and can contain any characters and capitalization. If the dbanme field is left empty, the database name defaults to the instance name.
  • username (optional) is the database username account for the specified database. By default this user inherits all Read/Write permissions to all databases in the instance. If left empty, the default username is pgadmin.

Deploying a Postgres Instance

  1. Request a Postgres instance using your manifest file.

    $ kubectl apply -f pg-instance-example.yaml
    
    postgres.sql.tanzu.vmware.com/pg-instance-example created
    

    The Postgres operator deploys the resources according to your specification, and also initializes the Postgres instance. If there are no existing Persistent Volume Claims (PVC) for the instance, new PVCs are created and used for the deployment. If a PVC for the instance already exists, it is used as-is with the available data.

  2. Check the status of the instance to verify that it was created successfully:

    $ kubectl get postgres/pg-instance-example
    

    You should see output similar to:

    NAME                   STATUS    AGE
    pg-instance-example   Created    28s
    

Using the Postgres Instance

Use the locally installed kubectl tool (pre-authenticated to securely access the Kubernetes cluster) to run the psql utility on the pg-instance-example-0 pod:

$ kubectl exec -it pg-instance-example-0 -- bash -c "psql"
psql (11.5-3.ubuntu1804.pivotal)
Type "help" for help.

postgres=# \l
                                 List of databases
Name               |  Owner   | Encoding  | Collate | Ctype |   Access privileges
----------------------+----------+-----------+---------+-------+-----------------------
postgres             | postgres | SQL_ASCII | C       | C     |
template0            | postgres | SQL_ASCII | C       | C     | =c/postgres          +
                     |          |           |         |       | postgres=CTc/postgres
template1            | postgres | SQL_ASCII | C       | C     | =c/postgres          +
                     |          |           |         |       | postgres=CTc/postgres
pg-instance-example  | postgres | SQL_ASCII | C       | C     |
(4 rows)

(Enter \q to exit the `psql` utility.)

The newly created database uses UTF-8 encoding. To verify the encoding run:

postgres=# show server encoding;
server_encoding
-----------------
 UTF8
(1 row)

See also Accessing a Postgres Instance in Kubernetes.

check-circle-line exclamation-circle-line close-line
Scroll to top icon