Installing a Tanzu Postgres Operator

This topic describes how to install Tanzu Postgres.

The primary method for installing Tanzu Postgres 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 Tanzu Postgres Operator can be installed using the Tanzu CLI. For more details, see Installing using the Tanzu CLI.

Installing using Helm

Prerequisites

To run Tanzu Postgres 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. For more information, see Installing Helm in the Helm documentation.

Note: Helm CLI 3.7.0 is not supported. Please use 3.7.1 and later.
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.

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

For more advanced security scenarios, see Configuring TLS for Tanzu Postgres Instances.

Accessing the Resources

You can setup Tanzu Postgres using two different methods:

Use Setup Tanzu Postgres Operator via Tanzu Network Registry for a faster installation process, and if your server hosts have access to the internet.
Use Setup Tanzu 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

Set the environment variable to enable Open Container Initiative (OCI) support in the Helm v3 client:
```
export HELM_EXPERIMENTAL_OCI=1
```
Without setting the variable, the following error message might appear:
```
Error: this feature has been marked as experimental and is not enabled by default.
```
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:

For Helm CLI 3.6 and earlier:

helm chart pull registry.tanzu.vmware.com/tanzu-sql-postgres/postgres-operator-chart:v1.8.0
helm chart export registry.tanzu.vmware.com/tanzu-sql-postgres/postgres-operator-chart:v1.8.0  --destination=/tmp/

For Helm CLI 3.7.1 and later:

helm pull oci://registry.tanzu.vmware.com/tanzu-sql-postgres/postgres-operator-chart --version v1.8.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 Tanzu Postgres distribution from VMware Tanzu Network. The Tanzu Postgres download filename has the format: postgres-for-kubernetes-v<version>.tar.gz
Unpack the downloaded software:
```
cd ~/Downloads
tar xzf postgres-for-kubernetes-v<version>.tar.gz
```
This command unpacks the distribution into a new directory named postgres-for-kubernetes-v<version>, for example postgres-for-kubernetes-v1.8.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:v1.8.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:v1.8.0

Verify that the two Docker images are now available.

docker images "postgres-*"

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

Push the Tanzu Postgres 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.

This example tags and pushes the images to the Google Cloud Registry, using the default (core) project name for the example Google Cloud account.

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.

Review the Operator Values

This step is optional. Go to the directory where you unpacked the Tanzu Postgres distribution. View the file operator/values.yaml in the Tanzu Postgres directory:

cat ./operator/values.yaml

The file specifies the location of the Postgres Operator and instance images. By default it contains the following values:

---
# 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:v1.8.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:v1.8.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

Determine which values in the values.yaml file need to be changed for your environment. Use the table below as a guide.

Key	Value Type	Description
`operatorImage`	URI	Reference to the Tanzu Postgres Operator image. Change this reference to show the URI of your private registry where you uploaded the Operator image.
`instanceImage`	URI	Reference to the Tanzu Postgres 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 Tanzu Postgres Instances.
`resources`	Object	Limits and requests for CPU and memory for the Operator. You can change these values to scale your resources.

To alter any of the default values create a operator-values-overrides.yaml (choose your own name) configuration file under the same location, and specify any custom values, for example a custom container registry, and a secret. For manual changes, you may also set individual parameters using the --set flag on the command line. 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:v1.8.0
postgresImage: ${REGISTRY}/postgres-instance:v1.8.0

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 (see step 5).
Install the Tanzu Postgres Operator by running one of the following:

If you created a custom operator-values-overrides.yaml 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 where the helm override file resides
- --namespace (optional) specifies the namespace you wish to deploy the Operator in, 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 did not create an operator-values-overrides.yaml configuration file run:
```
helm install my-postgres-operator /tmp/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/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 than the default, use the -n <your-namespace> 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 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

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.
Before using the Tanzu CLI, certain prerequisites (kapp-controller and secretgen-controller) must be installed on the Kubernetes cluster. For details on these requirements review Accepting Tanzu Application Platform EULAs, installing Cluster Essentials and the Tanzu CLI in the TAP documentation.
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 image bundle (e.g 1.1.0). Each Tanzu Postgres release corresponds to a TDS package version. For instance, Postgres Operator version 1.8.0 is part of TDS version 1.1.0. Insert the right version for your Tanzu Postgres Operator release.

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 package repository for VMware Tanzu Data Services:

tanzu package repository add tanzu-data-services-repository --url <MY-REGISTRY>/<TARGET-REPOSITORY>/tds-packages:<TDS-VERSION>

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)

List the available packages to confirm the addition:

tanzu package available list

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

Check the values for the Postgres Operator package:

tanzu package available get postgres-operator.sql.tanzu.vmware.com/1.8.0 --values-schema

- Retrieving package details for postgres-operator.sql.tanzu.vmware.com/1.8.0...
  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

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:

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

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 1.8.0 -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.

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

- Retrieving installed packages...
  NAME                  PACKAGE-NAME                            PACKAGE-VERSION  STATUS
  my-postgres-operator  postgres-operator.sql.tanzu.vmware.com  1.8.0            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

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 --selector app=postgres-operator

If your namespace is different than the default, add -n <your-namespace> to the command above 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 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: