Installing a Tanzu Postgres Operator

This topic describes how to install Tanzu Postgres using two different methods, via the Tanzu Network Registry or a downloadable file.

Prerequisites

To run Tanzu Postgres you need:

Access to Tanzu Network and Tanzu Network Registry. You can use the same credentials for both sites.
Docker running and configured on your local computer, to access the Kubernetes cluster and Docker registry.
A running Kubernetes cluster - Google Kubernetes Engine (GKE), VMware Enterprise TKGi) or Minikube - 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 on your local client.
The Helm v3 command-line tool installed. For more information, see Installing Helm from 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.

Cert Manager installed on the Kubernetes cluster.

IMPORTANT: TKGm users need to upgrade the TKGm packaged cert-manager to a version above 1.0.

Install cert-manager by running these commands from your local client:

kubectl create namespace cert-manager
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager --namespace cert-manager  --version <1.latest> --set installCRDs=true

where:

--namespace cert-manager is the namespace used for cert manager in the Kubernetes cluster
--version <1.latest> is the latest cert-manager version available (minimum above 1.0.2)
--set installCRDs=true ensures cert manager installs all types necessary to create certificates

To verify the installation run:

kubectl get all --namespace=cert-manager

The output should be similar to:

NAME                                           READY   STATUS    RESTARTS   AGE
pod/cert-manager-57b65b7fc-x8vjt               1/1     Running   5          4d19h
pod/cert-manager-cainjector-5f988f74c6-tgk25   1/1     Running   15         4d19h
pod/cert-manager-webhook-7cf554f879-b5ss9      1/1     Running   4          4d19h

NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/cert-manager           ClusterIP   10.106.253.7    <none>        9402/TCP   4d19h
service/cert-manager-webhook   ClusterIP   10.108.17.113   <none>        443/TCP    4d19h

NAME                                      READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/cert-manager              1/1     1            1           4d19h
deployment.apps/cert-manager-cainjector   1/1     1            1           4d19h
deployment.apps/cert-manager-webhook      1/1     1            1           4d19h

NAME                                                 DESIRED   CURRENT   READY   AGE
replicaset.apps/cert-manager-57b65b7fc               1         1         1       4d19h
replicaset.apps/cert-manager-cainjector-5f988f74c6   1         1         1       4d19h
replicaset.apps/cert-manager-webhook-7cf554f879      1         1         1       4d19h

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 the Tanzu Operator via the Tanzu Network Registry

Set the environment variable to enable Open Container Initiative (OCI) support in the Helm v3 client by running:
```
export HELM_EXPERIMENTAL_OCI=1
```
If you skip this step, 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 by running:
```
helm registry login registry.pivotal.io \
       --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 into a local /tmp/ directory:

If you're using Helm CLI 3.6 and earlier:

helm chart pull registry.pivotal.io/tanzu-sql-postgres/postgres-operator-chart:v1.5.0
helm chart export registry.pivotal.io/tanzu-sql-postgres/postgres-operator-chart:v1.5.0  --destination=/tmp/

If you're using Helm CLI 3.7.1 and later:

helm pull oci://registry.pivotal.io/tanzu-sql-postgres/postgres-operator-chart --version v1.5.0 --untar --untardir /tmp

Setup the Tanzu Operator 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.5.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.5.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.5.0

Verify that the two Docker images are now available.

docker images "postgres-*"

REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
postgres-operator   v1.5.0    063a6186109b   10 days ago    111MB
postgres-instance   v1.5.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}

Installing the Operator

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.pivotal.io/tanzu-sql-postgres/postgres-operator:v1.5.0

# specify the docker image for postgres instance, e.g. gcr.io/<my_project>/postgres-instance
postgresImage: registry.pivotal.io/tanzu-sql-postgres/postgres-instance:v1.5.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.

You can choose to create a operator-values-overrides.yaml (choose your own name) configuration file under the same location, to specify the custom container registry and 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.5.0
postgresImage: ${REGISTRY}/postgres-instance:v1.5.0

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 using VMware Tanzu Network, or Harbor.

VMware Tanzu Network

Create a secret named regsecret by running:

kubectl create secret docker-registry regsecret \
    --docker-server=https://registry.pivotal.io/ \
    --docker-username='USERNAME' \
    --docker-password='PASSWD'

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

IMPORTANT: The command above creates the secret in the default namespace. Only pods created in the same default namespace can reference the secret. To create a secret in a different namespace, use the --namespace flag.

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.

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> \
    --wait 
```
where
- OPERATOR_NAME is the name you choose for the helm release
- PATH_TO_CHART is where the helm chart is downloaded based on the setup procedure
- PATH_TO_HELM_OVERRIDES_FILE where the helm override file is created
- --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
```
Throughout this documentation we have used the default namespace. If you want to install into a different namespace, include the --namespace option in the helm command:
```
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-namaspace> 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/
```

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: