This topic provides steps to upgrade the VMware Postgres Operator and VMware Postgres Operator instances to a newer version. Upgrading the Postgres Operator also upgrades the existing Postgres instances. The topic covers three upgrade scenarios:

Important upgrade notes

  • In 2.1.0 release of VMware SQL with Postgres for Kubernetes, VMware Postgres Operator adds support for configuration pg_hba.conf through the Kubernetes ConfigMap. If you have been manually modifying the pg_hba.conf file, remove those entries from the pg_hba.conf file and transition to the supported workflow.
  • The VMware Postgres Operator 2.0.0 release upgrades the glibc library from 2.27 to 2.35. Therefore, indexes using locales other than C or POSIX need to be reindexed. Review the following steps to avoid issues with data consistency:
    • Create a query which will allow you to identify the affected indexes. For details you might refer to Postgres Locale data changes. Be aware that a possible query may not catch every index (e.g. partial indexes).
    • Rebuild the indexes immediately after upgrading. For reindexing instructions refer to Rebuilding indexes.
  • Customers upgrading from versions earlier than 1.9.0 note:
    Existing manually created roles on postgres and pgConfig.dbname, without explicitly set GRANT privileges, will lose the default CREATE and USAGE privileges on the schema public, and lose CONNECT privileges on the postgres, and pgConfig.dbname databases. To avoid any upgrade issues, check all manually created roles and update their privileges. For example: - Use the psql query /du to check if you have any manually created roles on postgres and pgConfig.dbname databases, other than the spec.pgConfig.username and spec.pgConfig.appUser. - Run GRANT statements for roles that need these permissions before upgrading the Operator. For details on GRANT queries, refer to [GRANT] (https://www.postgresql.org/docs/current/sql-grant.html) in the PostgreSQL documentation.
  • Customers who are upgrading to 2.0.0, and do not currently specify a storage class in their instance manifests, might encounter an error. The VMware Postgres Operator (from version 1.9.0) will attempt to change the pre-existing standard storage class to the default storage class. Users should update their instance manifests to explicitly specify standard, if that's the storage class used by their PVCs. See release 1.9.0 Release Notes.
  • When upgrading the VMware Postgres Operator, the Operator will ensure that existing Postgres instances have the appropriate version reference added to the object. Specifically, the Operator will set spec.postgresVersion.name to postgres-15. If you are tracking manifest files in source control, update those manifests files to reflect the change. Note that existing Postgres instances cannot be upgraded to a different major version.

Upgrading the Operator using Helm

Ensure you have access to Tanzu Network and Tanzu Network Registry. You can use the same credentials for both sites.

Note: Use Helm CLI 3.8.0 and later.

Accessing the Resources

Access the resources using two different methods:

Setup via the Tanzu Network Registry

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

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

  3. Follow the steps in Upgrading 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.

  1. Download the latest VMware Postgres Operator version from VMware Tanzu Network. The VMware Postgres Operator download filename has the format: postgres-for-kubernetes-v<version>.tar.gz.

  2. Load the new Postgres Operator and Postgres instances images into your container registry following the steps in Setup the VMware Postgres Operator via a Downloaded Archive File.

Upgrading the Operator

  1. Navigate to where you have downloaded the helm chart:

    cd /directory/with/helm-chart

  2. Update the existing instance of Postgres Custom Resource Definition (CRD) with the new values:

    kubectl apply -f crds/

  3. Create an operator-overrides.yaml file at a location of your choice or update an existing overrides file.

    Replace the sample parameters for operatorImage, postgresImage, dockerRegistrySecretName, certManagerClusterIssuerName, and resources with your 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: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: 500m
#    memory: 300Mi
#  requests:
#    cpu: 500m
#    memory: 300Mi

  4. Target the namespace where you have installed the helm release.

    kubectl config set-context --current --namespace=<POSTGRES-OPERATOR-NAMESPACE>

    where POSTGRES-OPERATOR-NAMESPACE is the namespace.

    List the helm releases using:

    helm ls

    NAME             	NAMESPACE	REVISION	UPDATED                             	STATUS  	CHART                     APP VERSION
postgres-operator	default  	3       	2022-01-06 13:28:05.704226 -0500 CDT	deployed	postgres-operator-v1.7.0  v1.7.0

  5. Upgrade using:

    helm upgrade <RELEASE-NAME> /tmp/postgres-operator/ -f /<path-to-your-file>/operator_overrides_values.yaml --wait

    where

    • RELEASE-NAME is the name of the helm release listed from the list output
    • operator_overrides_values.yaml is the overrides file

    The output is similar to:

    Release "postgres-operator" has been upgraded. Happy Helming!
NAME: postgres-operator 
LAST DEPLOYED: Fri Jan 7 15:31:43 2022
NAMESPACE: default
STATUS: deployed
REVISION: 4
TEST SUITE: None

    where REVISION is a counter for the number of Operator upgrades you have performed. If you have upgraded from 1.0 to 1.1, and from 1.1 to 1.2, the REVISION number would be 3.

  6. Verify the Postgres Operator status:

    helm ls

    NAME             	NAMESPACE	REVISION	UPDATED                             	STATUS  	CHART                     APP VERSION
postgres-operator	default  	4       	2022-10-11 13:28:05.704226 -0500 CDT	deployed	postgres-operator-v2.3.0  v2.3.0

    Confirm that the images version has also been upgraded:

    kubectl describe statefulset.apps/<INSTANCE-NAME> | grep Image | uniq

    where INSTANCE-NAME is the name of the Postgres instance. For example:

    Image: registry.tanzu.vmware.com/tanzu-sql-postgres/postgres-instance:v2.3.0

    To verify the new Postgres instance version, use a command similar to:

    kubectl exec pod/INSTANCE-NAME-0 -c pg-container -- psql -c 'select version()'

    where INSTANCE-NAME is the name of the Postgres instance.

Upgrading the Operator using the Tanzu CLI

  1. Find the package repository name of the VMware Tanzu Data Services package repository:

    tanzu package repository list -A

    | Retrieving repositories...
NAME                 REPOSITORY                                                                          TAG    STATUS               DETAILS  NAMESPACE
tds-repo             registry.tanzu.vmware.com/packages-for-vmware-tanzu-data-services/tds-packages      1.1.0  Reconcile succeeded           postgres-operator
tanzu-rabbitmq-repo  registry.tanzu.vmware.com/p-rabbitmq-for-kubernetes/tanzu-rabbitmq-package-repo     1.3.0  Reconcile succeeded           rabbitmq-operator

    where column NAME represents the name of the package repository.

    Note the namespace where registry.tanzu.vmware.com/packages-for-vmware-tanzu-data-services/tds-packages repository is located.

  2. Update the package repository to reflect the new target version:

    tanzu package repository update <PACKAGE-REPOSITORY-NAME> \
    --url <MY-REGISTRY>/<TARGET-REPOSITORY>/tds-packages:<TDS-VERSION> \
    --namespace=<POSTGRES-OPERATOR-NAMESPACE>

    where:

    • PACKAGE-REPOSITORY-NAME is your chosen name for the installed package repository
    • MY-REGISTRY is your own image registry
    • TARGET-REPOSITORY is your target repository
    • TDS-VERSION is the target version you'll like to upgrade to (e.g. 1.5.0)
    • POSTGRES-OPERATOR-NAMESPACE is the namespace of the packagerepository
    | Updating package repository 'tanzu-data-services-repository'
- Getting package repository 'tanzu-data-services-repository' 
/ Getting package repository 'tanzu-data-services-repository'
| Validating provided settings for the package repository
| Updating package repository resource
- Waiting for 'PackageRepository' reconciliation for 'tanzu-data-services-repository'
/ 'PackageRepository' resource install status: Reconciling

Updated package repository 'tanzu-data-services-repository' in namespace 'default'

  3. Verify you have updated the package repository

    tanzu package repository get tanzu-data-services-repository --namespace=<POSTGRES-OPERATOR-NAMESPACE>

    where POSTGRES-OPERATOR-NAMESPACE is the namespace of the package repository.

    - Retrieving repository tanzu-data-services-repository... 
/ Retrieving repository tanzu-data-services-repository...
NAME:          tanzu-data-services-repository
VERSION:       2571192
REPOSITORY:    registry.tanzu.vmware.com/packages-for-vmware-tanzu-data-services/tds-packages
TAG:           1.1.0
STATUS:        Reconcile succeeded
REASON:

  4. Select your desired version of the available Postgres Operator version

    tanzu package available list postgres-operator.sql.tanzu.vmware.com --namespace=<POSTGRES-OPERATOR-NAMESPACE>

    where POSTGRES-OPERATOR-NAMESPACE is the namespace of the package repository.

  5. Update the Postgres Operator package to your desired version:

    tanzu package installed update <PACKAGE-NAME> \ 
  --package-name postgres-operator.sql.tanzu.vmware.com \
  --version <POSTGRES-OPERATOR-VERSION> \
  -f <YOUR-OVERRIDES-FILE-PATH> \
  --namespace <POSTGRES-OPERATOR-NAMESPACE>

    where:

    • PACKAGE-NAME is the name you choose during installation.
    • POSTGRES-OPERATOR-VERSION is the Operator version you choose in the step above
    • YOUR-OVERRIDES-FILE-PATH is your custom overrides path and file, for example overrides.yaml.
    • POSTGRES-OPERATOR-NAMESPACE is the namespace of the packagerepository
    | Updating installed package 'postgres-operator'
- Getting package install for 'postgres-operator' 
/ Getting package install for 'postgres-operator'
/ Getting package metadata for 'postgres-operator.sql.tanzu.vmware.com'
| Updating package install for 'postgres-operator'
/ Waiting for 'PackageInstall' reconciliation for 'postgres-operator'
/ 'PackageInstall' resource install status: Reconciling

Updated installed package 'postgres-operator' in namespace 'default'

  6. Verify the Postgres Operator package was updated successfully:

    tanzu package installed get postgres-operator --namespace=<POSTGRES-OPERATOR-NAMESPACE>

    where POSTGRES-OPERATOR-NAMESPACE is the namespace of the package repository.

    - Retrieving installation details for postgres-operator... 
/ Retrieving installation details for postgres-operator...
NAME:                    postgres-operator
PACKAGE-NAME:            postgres-operator.sql.tanzu.vmware.com
PACKAGE-VERSION:         
STATUS:                  Reconcile succeeded
CONDITIONS:              [{ReconcileSucceeded True  }]
USEFUL-ERROR-MESSAGE:
check-circle-line exclamation-circle-line close-line
Scroll to top icon