Installing a VMware Postgres Operator

This topic describes how to install VMware Postgres Operator.

The primary method for installing VMware Postgres Operator Operator is via Helm. See Installing using Helm for install instructions using the Tanzu Network Registry, or a downloadable file.

For Tanzu Application Platform (TAP) customers, the VMware Postgres Operator can be installed using the Tanzu CLI. For more details, see Installing using the Tanzu CLI.

Installing using Helm

Prerequisites

To run VMware Postgres Operator you need:

Access to Tanzu Network. A Tanzu Network account provides access to the Tanzu Network Registry as well.
A running Kubernetes cluster (check supported providers in Platform Requirements) - and the kubectl command-line tool, configured and authenticated to communicate with your Kubernetes cluster.
- If you are using GKE, install the gcloud command-line tool.
- If you are using TKG, install the tanzu command-line tool.
- If you are using TKGI, install the tkgi command-line tool.
Docker running and configured on your local machine, to access the Kubernetes cluster, and the Docker registry.
The Helm v3 command-line tool installed, v3.8.0 and later. For more information, see Installing Helm in the Helm documentation.
cluster-admin ClusterRole access to the Kubernetes cluster. For more information, see the Kubernetes documentation.
review the Network Policies Configuration topic if you have any network plugins (for example Network Plugin) in your Kubernetes cluster.
The latest Cert Manager installed on the Kubernetes cluster. See Installing with Helm in the cert-manager documentation.

Note: TKG users need to upgrade the TKG packaged cert-manager to the latest available version.

Review Configuring TLS for VMware Postgres Operator Instances if you wish to install the Operator using a custom or coorporate TLS Secret.
Adequate CPU and memory resources. For guidance on minimum resource requirements, review Minimum resource requirements.

Accessing the Resources

You can setup VMware Postgres Operator using two different methods:

Use Setup VMware Postgres Operator via Tanzu Network Registry for a faster installation process, and if your server hosts have access to the internet.
Use Setup VMware Postgres Operator via Downloadable Archive File if your server hosts do not have access to the internet, or if you want to install from a private registry.

Setup via the Tanzu Network Registry

Use Helm to log in to the Tanzu Network Registry, using your credentials:
```
helm registry login registry.tanzu.vmware.com \
       --username=<USERNAME> \
       --password=<PASSWORD>
```
Follow the prompts to enter the email address and password for your Tanzu Network account.

Download the Helm chart from the Tanzu distribution registry, and export it into a local /tmp/ directory:

helm pull oci://registry.tanzu.vmware.com/tanzu-sql-postgres/vmware-sql-postgres-operator --version v2.3.0 --untar --untardir /tmp

Follow the steps in Installing the Operator.

Setup via a Downloaded Archive File

Choose this method if the installation destination (for example an air-gapped network) cannot access the VMware Tanzu Network, or you wish to load the Operator and instance images to private Docker registry.

Download the VMware Postgres Operator distribution from the VMware Tanzu Network. The VMware Postgres Operator downloaded filename has the following format:
```
postgres-for-kubernetes-v<version>.tar.gz`.
```
Unpack the downloaded software:
```
cd ~/Downloads
tar xzf postgres-for-kubernetes-v<version>.tar.gz
```
The distribution is unpacked into a new directory named postgres-for-kubernetes-v<version>, for example, postgres-for-kubernetes-v2.3.0.
Change to the new postgres-for-kubernetes-v<version> directory.
```
cd ./postgres-for-kubernetes-v*
```

Load the Postgres instance image.

docker load -i ./images/postgres-instance

cc967c529ced: Loading layer [==================================================>]  65.57MB/65.57MB
2c6ac8e5063e: Loading layer [==================================================>]  991.2kB/991.2kB
6c01b5a53aac: Loading layer [==================================================>]  15.87kB/15.87kB
e0b3afb09dc3: Loading layer [==================================================>]  3.072kB/3.072kB
faee4b69eae8: Loading layer [==================================================>]  29.74MB/29.74MB
6bc08b5f8a06: Loading layer [==================================================>]  4.096kB/4.096kB
3bfb028071fa: Loading layer [==================================================>]  331.4MB/331.4MB
6ef1a056590e: Loading layer [==================================================>]  57.86kB/57.86kB
Loaded image: postgres-instance:v2.3.0

Load the Postgres operator image.

docker load -i ./images/postgres-operator

0d1435bd79e4: Loading layer [==================================================>]  3.062MB/3.062MB
b50265a0f809: Loading layer [==================================================>]  40.87MB/40.87MB
Loaded image: postgres-operator:v2.3.0

Verify that the two Docker images are now available.

docker images "postgres-*"

REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
postgres-operator   v2.3.0    063a6186109b   10 days ago    111MB
postgres-instance   v2.3.0    cc6ca2396fda   10 days ago    1.72GB

Push the VMware Postgres Operator Docker images to the container registry of your choice. Set each image's project and image repo name, tag the images, and then push them using the Docker command docker push.

Using the default (core) project name for a Google Cloud account (for example), the following example tags and pushes the images to the Google Cloud Registry:

gcloud auth configure-docker

PROJECT=$(gcloud config list core/project --format='value(core.project)')
REGISTRY="gcr.io/${PROJECT}"

INSTANCE_IMAGE_NAME="${REGISTRY}/postgres-instance:$(cat ./images/postgres-instance-tag)"
docker tag $(cat ./images/postgres-instance-id) ${INSTANCE_IMAGE_NAME}
docker push ${INSTANCE_IMAGE_NAME}

OPERATOR_IMAGE_NAME="${REGISTRY}/postgres-operator:$(cat ./images/postgres-operator-tag)"
docker tag $(cat ./images/postgres-operator-id) ${OPERATOR_IMAGE_NAME}
docker push ${OPERATOR_IMAGE_NAME}

Follow the steps in Installing the Operator.

Installing the Operator

Create a Kubernetes Access Secret

Create a docker-registry type secret to allow the Kubernetes cluster to authenticate with the private container registry, or the Tanzu Registry, so it can pull images. These examples create a secret named regsecret, in the current namespace (in this example it's the default), using VMware Tanzu Network, or Harbor.

IMPORTANT: Only pods created in the current default namespace can reference this secret. To create the instance in a different namespace, use the --namespace flag.

VMware Tanzu Network

kubectl create secret docker-registry regsecret \
    --docker-server=https://registry.tanzu.vmware.com/ \
    --docker-username='USERNAME' \
    --docker-password='PASSWD'

where USERNAME and password PASSWD are your access credentials to the VMware Tanzu Network. Surround both the USERNAME and the PASSWD by single quote marks to handle any special characters within those values.

Harbor

kubectl create secret docker-registry regsecret \
    --docker-server=${HARBOR_URL} \
    --docker-username=${HARBOR_USER} \
    --docker-password="${HARBOR_PASSWORD}"

The Postgres Operator will use this secret to allow the Kubernetes cluster to authenticate with the container registry to pull images.

Customize the Operator Values

Note: When installing the Operator on Openshift, set the enableSecurityContext to false.

This step is optional for customers not using Openshift.

Go to the directory where you unpacked the VMware Postgres Operator distribution, and view the defaults in the file operator/values.yaml:

cat /tmp/vmware-sql-postgres-operator/values.yaml

---
# specify the url for the docker image for the operator, e.g. gcr.io/<my_project>/postgres-operator
operatorImage: registry.tanzu.vmware.com/tanzu-sql-postgres/postgres-operator:v2.3.0

# specify the docker image for postgres instance, e.g. gcr.io/<my_project>/postgres-instance
postgresImage: registry.tanzu.vmware.com/tanzu-sql-postgres/postgres-instance:v2.3.0

# specify the name of the docker-registry secret to allow the cluster to authenticate with the container registry for pulling images
dockerRegistrySecretName: regsecret

# override the default self-signed cert-manager cluster issuer
certManagerClusterIssuerName: postgres-operator-ca-certificate-cluster-issuer

# set the resources for the postgres operator deployment
resources: {}
#  limits:
#    cpu: 100m
#    memory: 128Mi
#  requests:
#    cpu: 100m
#    memory: 128Mi

# enable security context for the postgres-operator deployment and the managed instances, typically deactivated on OpenShift clusters
enableSecurityContext: true

Use the table below as a guide for details on the fields.

Key	Value Type	Description
`operatorImage`	URI	Reference to the VMware Postgres Operator Operator image. Change this reference to show the URI of your private registry where you uploaded the Operator image.
`instanceImage`	URI	Reference to the VMware Postgres Operator image. Change this reference to show the URI of your private registry where you uploaded the instance image.
`dockerRegistrySecretName`	String	Name of image secret. This value must match the name of the Kubernetes secret you created in Create a Kubernetes Access Secret above.
`certManagerClusterIssuerName`	String	Name of TLS issuer. Change this field to match your custom CA issuer if you're using TLS. See Configuring TLS for VMware Postgres Operator Instances.
`resources`	Object	Limits and requests for CPU and memory for the Operator. You can change these values to scale your resources.
`enableSecurityContext`	Boolean	Sets the default security context for the operator and its managed instances; this should be deactivated on OpenShift clusters.

Determine which values in the values.yaml file need to be changed for your environment, and create a operator-values-overrides.yaml (choose your own name) configuration file under the same location. Specify any custom values, for example a custom container registry, and a secret. See Helm Values Files in the Helm documentation for more information.

An example values-overrides.yaml file could contain the following lines, replacing ${REGISTRY} with your private container registry name:

operatorImage: ${REGISTRY}/postgres-operator:v2.3.0
postgresImage: ${REGISTRY}/postgres-instance:v2.3.0

For manual changes, without using an Operator values file, you may also set individual parameters using the --set flag on the command line.

Deploy the Operator

Verify you don't have previously installed instance CRDs in your cluster:
```
kubectl get crd postgres.sql.tanzu.vmware.com
```
If this is a brand new Operator installation, the result should be similar to:
```
Error from server (NotFound): customresourcedefinitions.apiextensions.k8s.io "postgres.sql.tanzu.vmware.com" not found
```
If the result is similar to:
```
NAME                            CREATED AT
postgres.sql.tanzu.vmware.com   2021-06-09T06:04:45Z
```
there are older instances running in the cluster, from a previous Operator deployment. When deploying the Operator, you need to refresh this CRD in order to apply the new updated Operator version, as described further below.
Install VMware Postgres Operator by running one of the following commands:

If you have created a custom operator-values-overrides.yaml configuration file, run the following helm command:
```
helm install <OPERATOR_NAME> <PATH_TO_CHART> \
    --values=<PATH_TO_HELM_OVERRIDES_FILE> \
    --namespace=<OPERATOR_NAMESPACE> \
    --wait 
```
where
- OPERATOR_NAME is a custom name for the helm release
- PATH_TO_CHART is where you downloaded the helm chart based on the setup procedure
- --values (optional) specifies the path to the file that overrides the varibles.yaml file; if you don't specify the path, values of the variable.yaml file are the default values
- --namespace (optional) specifies the namespace where you want to deploy the Operator, which must match the namespace for the secret created in Create a Kubernetes Access Secret
- --wait flag waits for the Operator deployment to complete before any image installation starts
If you have not created a custom operator-values-overrides.yaml configuration file, run the following command:
```
helm install my-postgres-operator /tmp/vmware-sql-postgres-operator/  --wait 
```
```
NAME: my-postgres-operator
LAST DEPLOYED: Wed Jun 16 13:28:05 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
```
```
helm install my-postgres-operator /tmp/vmware-sql-postgres-operator/ \
  --namespace=${OPERATOR_NAMESPACE} \
  --create-namespace \
  --wait    
```
Note: The secret namespace in step Create a Kubernetes Access Secret must match the Operator namespace.

Installing the Operator creates a new service account named postgres-operator-service-account. It is for internal use, but it is visible if you use the kubectl get serviceaccount command:
```
kubectl get serviceaccount
```
```
NAME                                 SECRETS   AGE
default                              1         12m
postgres-operator-service-account    1         8m56s
```

Use watch kubectl get all to monitor the progress of the deployment. The deployment is complete when the Postgres Operator pod status changes to Running. Use the label app=postgres-operator to search across resources created by the Postgres Operator Helm chart.

watch kubectl get all --selector app=postgres-operator

If your namespace is different from the default, use the -n <your-namespace> parameter to specify your namespace.

Every 2.0s: kubectl get all

NAME                                     READY   STATUS    RESTARTS   AGE
pod/postgres-operator-6754b58976-24zwx   1/1     Running   0          5m15s

NAME                                        TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)   AGE
service/postgres-operator-webhook-service   ClusterIP   10.101.230.150   <none>        443/TCP   5m15s

NAME                                READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/postgres-operator   1/1     1            1           5m15s

NAME                                           DESIRED   CURRENT   READY   AGE
replicaset.apps/postgres-operator-6754b58976   1         1         1       5m15s

You may check the logs to confirm that the Operator is running properly by using the -n option if namespace is not default:

kubectl logs -l app=postgres-operator

To view all the Operator resources run:

kubectl api-resources --api-group=sql.tanzu.vmware.com

NAME                      SHORTNAMES   APIVERSION                NAMESPACED   KIND
postgres                  pg           sql.tanzu.vmware.com/v1   true         Postgres
postgresbackuplocations                sql.tanzu.vmware.com/v1   true         PostgresBackupLocation
postgresbackups                        sql.tanzu.vmware.com/v1   true         PostgresBackup
postgresbackupschedules                sql.tanzu.vmware.com/v1   true         PostgresBackupSchedule
postgresrestores                       sql.tanzu.vmware.com/v1   true         PostgresRestore
postgresversions                       sql.tanzu.vmware.com/v1   false        PostgresVersion

If you have existing Postgres instances running from a previous Operator deployment, go to the location you setup your Operator:
```
cd /<your-path>/postgres-for-kubernetes-v<your-version>/
```
and re-apply the instance CRD, using a command similar to:
```
kubectl apply -f operator/crds/
```

Installing using the Tanzu CLI

Prerequisites

A Tanzu Network account to access images from the VMware Tanzu Network registry.
The TAP requirements under Accepting Tanzu Application Platform EULAs and installing Tanzu CLI in the TAP documentation.
Installed Cluster Essentials for VMware Tanzu.
Cert Manager installed on the Kubernetes cluster.

Relocate Images to a Private Registry

Relocate the images from VMware Tanzu Network registry to a private registry before attempting installation. The VMware Tanzu Network registry does not offer uptime guarantees for installations. Skipping image relocation should only occur when configuring an evaluation, testing, or proof-of-concept environment.

To relocate images from the VMware Tanzu Network registry to a private registry:

Log in to your image registry by running:
```
docker login <MY-REGISTRY>
```
where:
- MY-REGISTRY is your own image registry
Log in to the VMware Tanzu Network registry with your VMware Tanzu Network credentials by running:
```
docker login registry.tanzu.vmware.com
```
Relocate the images with the Carvel tool imgpkg by running:
```
imgpkg copy -b registry.tanzu.vmware.com/packages-for-vmware-tanzu-data-services/tds-packages:<TDS-VERSION> \
     --to-repo <MY-REGISTRY>/<TARGET-REPOSITORY>/tds-packages
```
where:
- MY-REGISTRY is your own image registry
- TARGET-REPOSITORY is your target repository
- TDS-VERSION is the tag for the Tanzu Data Services image bundle that each VMware Postgres Operator release corresponds to. Insert the right version for your VMware Postgres Operator release. For a mapping table, refer to Tanzu Data Services packages.

Create a Kubernetes Secret

Verify the existing secrets in your environment:

tanzu secret registry list -n <namespace>

The output would be similar to:

NAME                   REGISTRY                       EXPORTED           AGE
test-registry          my-registry                    to all namespaces  47h
tanzu-registry         registry.tanzu.vmware.com      to all namespaces  47h

Verify there is an exported secret for your custom image registry. If there is no associated secret, create a secret and export the secret to all namespaces:

tanzu secret registry add <SECRET-NAME> \
    --username <MY-REGISTRY-USERNAME> \
    --password <MY-REGISTRY-PASSWORD> \
    --server <MY-REGISTRY> \
    --export-to-all-namespaces --yes

where:

SECRET-NAME: is the name of the Kubernetes secret that will be created
MY-REGISTRY is your own image registry
MY-REGISTRY-USERNAME is the username for your own container registry
MY-REGISTRY-PASSWORD is the password for your own container registry

Add the Package Repository

Add the VMware Data Services package repository to the namespace you plan to install the Operator:

tanzu package repository add tanzu-data-services-repository \
    --url <MY-REGISTRY>/packages-for-vmware-tanzu-data-services/tds-packages:<TDS-VERSION> \
    --namespace <NAMESPACE> \
    --create-namespace

where:

MY-REGISTRY is your own image registry
TARGET-REPOSITORY is your target repository
TDS-VERSION is the tag for the image bundle (e.g. 1.1.0)
NAMESPACE is the namespace where the repository will be added to, for example postgres-tanzu-operator. Omitting NAMESPACE will install the package to the default namespace, and cannot be altered later.

List the available packages to confirm the addition:

tanzu package available list --namespace <NAMESPACE>

- Retrieving available packages...
  NAME                                      DISPLAY-NAME                                   SHORT-DESCRIPTION                   LATEST-VERSION
  postgres-operator.sql.tanzu.vmware.com    VMware SQL with Postgres for Kubernetes        Kubernetes Operator for PostgreSQL  2.0.2

Check the values for the Postgres Operator package:

tanzu package available get postgres-operator.sql.tanzu.vmware.com/2.0.2 \
    --values-schema \
    --namespace <NAMESPACE>

- Retrieving package details for postgres-operator.sql.tanzu.vmware.com/2.0.2...
  KEY                           DEFAULT                                          TYPE    DESCRIPTION
  certManagerClusterIssuerName  postgres-operator-ca-certificate-cluster-issuer  string  A cert-manager based clusterissuer used to sign postgres certificates using a custom certificate authority
  dockerRegistrySecretName      regsecret                                        string  The name of the docker-registry secret to allow the cluster to authenticate with the container registry for pulling images
  resources                     map[]                                            object  Resources describes the CPU and Memory compute resource requirements for Postgres operator pod
  enableSecurityContext         true                                             boolean EnableSecurityContext sets the security context for the operator and its managed instances, typically deactivated on OpenShift

Consider overriding the Operator values in a separate YAML file, if the defaults do not suit your deployment environment. A sample overrides YAML could be:

Note: enableSecurityContext must be set to false when installing the Operator on Openshift clusters.

certManagerClusterIssuerName: custom-issuer
dockerRegistrySecretName: custom-secret
resources:
  limits:
    cpu: 500m
    memory: 300Mi
  requests:
    cpu: 500m
    memory: 300Mi
enableSecurityContext: true

Installing the Operator

Install the operator package

Install the Postgres operator package, using the overrides file you created:

tanzu package install <PACKAGE-NAME> \
    --package-name postgres-operator.sql.tanzu.vmware.com \
    --version 2.0.2 \
    --namespace <NAMESPACE> \
    -f <YOUR-OVERRIDES-FILE-PATH>

where:

PACKAGE-NAME is the name you choose for the package installation
YOUR-OVERRIDES-FILE-PATH is your custom overrides path and file, for example overrides.yaml
NAMESPACE is the namespace that the package repository was added to

The output is similar to:

/ Installing package 'postgres-operator.sql.tanzu.vmware.com'
| Getting package metadata for 'my-postgres-operator.sql.tanzu.vmware.com'
| Creating service account 'my-postgres-operator-default-sa'
| Creating cluster admin role 'my-postgres-operator-default-cluster-role'
| Creating cluster role binding 'my-postgres-operator-default-cluster-rolebinding'
| Creating secret 'my-postgres-operator-default-values'
| Creating package resource
- Waiting for 'PackageInstall' reconciliation for 'my-postgres-operator'
\ 'PackageInstall' resource install status: Reconciling


Added installed package 'my-postgres-operator'

Verify PackageInstall has been created

tanzu package installed list --namespace <NAMESPACE>

- Retrieving installed packages...
  NAME                  PACKAGE-NAME                            PACKAGE-VERSION  STATUS
  my-postgres-operator  postgres-operator.sql.tanzu.vmware.com  2.0.2            Reconcile succeeded

A service account is created so that the kapp-controller can create cluster-scope objects such as CustomResourceDefinitions, and so it will have permissions to create objects on any namespace. This service account is different than the service account for the Postgres operator to manage other Kubernetes resources (statefulsets, secrets, etc...)

To check the service accounts run:

kubectl get serviceaccount --namespace <NAMESPACE>

NAME                                    SECRETS   AGE
default                                 1         4d4h
my-postgress-operator-default-sa        1         12m
my-postgres-operator-service-account    1         12m

Verify the Operator Deployment

watch kubectl get all -n <NAMESPACE> --selector app=postgres-operator

Every 2.0s: kubectl get all

NAME                                        READY   STATUS    RESTARTS   AGE
pod/postgres-operator-6754b58976-24zwx      1/1     Running   0          5m15s

NAME                                        TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)   AGE
service/postgres-operator-webhook-service   ClusterIP   10.101.230.150   <none>        443/TCP   5m15s

NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/postgres-operator           1/1     1            1           5m15s

NAME                                           DESIRED   CURRENT   READY   AGE
replicaset.apps/postgres-operator-6754b58976   1         1         1       5m15s

You may also check the logs to confirm the Operator is running properly:

kubectl logs -l app=postgres-operator

To view all the Operator resources run:

kubectl api-resources --api-group=sql.tanzu.vmware.com

NAME                      SHORTNAMES   APIVERSION                NAMESPACED   KIND
postgres                  pg           sql.tanzu.vmware.com/v1   true         Postgres
postgresbackuplocations                sql.tanzu.vmware.com/v1   true         PostgresBackupLocation
postgresbackups                        sql.tanzu.vmware.com/v1   true         PostgresBackup
postgresbackupschedules                sql.tanzu.vmware.com/v1   true         PostgresBackupSchedule
postgresrestores                       sql.tanzu.vmware.com/v1   true         PostgresRestore
postgresversions                       sql.tanzu.vmware.com/v1   false        PostgresVersion

Next steps

After you install the Postgres Operator, you can use it to deploy and manage Postgres instances. To interact with the Postgres Operator, you place a set of instructions into a YAML-formatted configuration file (a Kubernetes manifest) and then use the kubectl utility to send the file instructions to the Operator. The Postgres Operator is then responsible for following the instructions that you provide, and also for maintaining the state of the Postgres instance according to the properties that you defined.

For more details, see: