This topic describes how to install VMware Postgres Operator.
The primary method for installing the VMware Postgres Operator is via Helm. See Installing using Helm for install instructions using the Broadcom Support Portal 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.
To run VMware Postgres Operator you need:
Access to Broadcom Support. A Broadcom Support Portal account provides access to the Broadcom Support Portal 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.
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.
You can setup VMware Postgres Operator using two different methods:
Use Setup VMware Postgres Operator via Broadcom Support Portal 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.
Use Helm to log in to the packages.broadcom.com Registry, using your credentials:
helm registry login tanzu-sql-postgres.packages.broadcom.com \
--username=<USERNAME> \
--password=<PASSWORD>
Follow the prompts to enter the email address and password for your Broadcom Support Portal account.
Download the Helm chart from the Tanzu distribution registry, and export it into a local /tmp/
directory:
helm pull oci://tanzu-sql-postgres.packages.broadcom.com/vmware-sql-postgres-operator --version v3.0.0 --untar --untardir /tmp
Follow the steps in Installing the Operator.
Choose this method if the installation destination (for example an air-gapped network) cannot access the Broadcom Support Portal, or you wish to load the Operator and instance images to private Docker registry.
Download the VMware Postgres Operator distribution from the Broadcom Support Portal. 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-v3.0.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
931b7ff0cb6f: Loading layer [==================================================>] 80.41MB/80.41MB
63303ad6e5bf: Loading layer [==================================================>] 488.1MB/488.1MB
9655cb91a56a: Loading layer [==================================================>] 40.06MB/40.06MB
5bea796b8d94: Loading layer [==================================================>] 3.072kB/3.072kB
2f41e76478a8: Loading layer [==================================================>] 26.62kB/26.62kB
fa3d7e6de939: Loading layer [==================================================>] 40.4MB/40.4MB
c1231727363e: Loading layer [==================================================>] 2.326GB/2.326GB
fdd1c8aec8b8: Loading layer [==================================================>] 575.5MB/575.5MB
1524e0cc3d7c: Loading layer [==================================================>] 17.13MB/17.13MB
d12657205845: Loading layer [==================================================>] 4.096kB/4.096kB
Loaded image: postgres-instance:v3.0.0
Load the Postgres operator image.
docker load -i ./images/postgres-operator
57ebe25ef5bf: Loading layer [==================================================>] 28.27MB/28.27MB
66f2b7ed67a8: Loading layer [==================================================>] 4.608kB/4.608kB
7d19e131fe74: Loading layer [==================================================>] 2.56kB/2.56kB
9859e3aa8a55: Loading layer [==================================================>] 56.15MB/56.15MB
186503d18239: Loading layer [==================================================>] 470.5MB/470.5MB
878e32dc7a61: Loading layer [==================================================>] 7.19MB/7.19MB
4c33af9867b1: Loading layer [==================================================>] 3.072kB/3.072kB
9655cb91a56a: Loading layer [==================================================>] 40.06MB/40.06MB
54908428d481: Loading layer [==================================================>] 3.072kB/3.072kB
d5a3c5b9aa11: Loading layer [==================================================>] 40.24MB/40.24MB
Loaded image: postgres-operator:v3.0.0
Verify that the two Docker images are now available.
docker images "postgres-*"
REPOSITORY TAG IMAGE ID CREATED SIZE
postgres-operator v3.0.0 763a7dd5121f 7 days ago 712MB
postgres-instance v3.0.0 1ddfee136935 7 days ago 3.54GB
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.
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 Broadcom Support Portal, 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.
Broadcom Support Portal
kubectl create secret docker-registry regsecret \
--docker-server=https://tanzu-sql-postgres.packages.broadcom.com/ \
--docker-username='USERNAME' \
--docker-password='PASSWD'
where USERNAME
and password PASSWD
are your access credentials to the Broadcom Support Portal. 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.
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: tanzu-sql-postgres.packages.broadcom.com/postgres-operator:v3.0.0
# specify the docker image for postgres instance, e.g. gcr.io/<my_project>/postgres-instance
postgresImage: tanzu-sql-postgres.packages.broadcom.com/postgres-instance:v3.0.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 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. |
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:v3.0.0
postgresImage: ${REGISTRY}/postgres-instance:v3.0.0
For manual changes, without using an Operator values file, you may also set individual parameters using the --set
flag on the command line.
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 releasePATH_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 startsIf 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/
Relocate the images from Broadcom Support Portal registry to a private registry before attempting installation. The Broadcom Support Portal 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 Broadcom Support Portal registry to a private registry:
Log in to your image registry by running:
docker login <MY-REGISTRY>
where:
MY-REGISTRY
is your own image registryLog in to the Broadcom Support Portal registry with your Broadcom Support Portal credentials by running:
docker login tanzu-sql-postgres.packages.broadcom.com
Relocate the images with the Carvel tool imgpkg
by running:
imgpkg copy -b tanzu-sql-postgres.packages.broadcom.com/tds-packages:<TDS-VERSION> \
--to-repo <MY-REGISTRY>/<TARGET-REPOSITORY>/tds-packages
where:
MY-REGISTRY
is your own image registryTARGET-REPOSITORY
is your target repositoryTDS-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.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 tanzu-sql-postgres.packages.broadcom.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 createdMY-REGISTRY
is your own image registryMY-REGISTRY-USERNAME
is the username for your own container registryMY-REGISTRY-PASSWORD
is the password for your own container registryAdd 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 registryTARGET-REPOSITORY
is your target repositoryTDS-VERSION
is the tag for the image bundle (e.g. 1.14.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 Tanzu for Postgres on Kubernetes Kubernetes Operator for PostgreSQL 3.0.0
Check the values for the Postgres Operator package:
tanzu package available get postgres-operator.sql.tanzu.vmware.com/3.0.0 \
--values-schema \
--namespace <NAMESPACE>
- Retrieving package details for postgres-operator.sql.tanzu.vmware.com/3.0.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
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
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 3.0.0 \
--namespace <NAMESPACE> \
-f <YOUR-OVERRIDES-FILE-PATH>
where:
PACKAGE-NAME
is the name you choose for the package installationYOUR-OVERRIDES-FILE-PATH
is your custom overrides path and file, for example overrides.yaml
NAMESPACE
is the namespace that the package repository was added toThe 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 3.0.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 --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
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.
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
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: