Migrate to the latest version of the AlloyDB Omni Kubernetes Operator

This page covers instructions for upgrading from version 1.0.0 to version 1.1.0 of the AlloyDB Omni Operator.

The steps that you take to upgrade AlloyDB Omni in Kubernetes depend upon the version of AlloyDB Omni that you run, and the version that you upgrade to.

Determine your current version numbers

Kubernetes

To check the version of AlloyDB Omni used by your database cluster, run this command:

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -n NAMESPACE -o jsonpath='{.status.primary.currentDatabaseVersion}'

Replace the following:

  • DB_CLUSTER_NAME: the name of your database cluster. It's the same database cluster name that you declared when you created it.

  • NAMESPACE: the Kubernetes namespace of your database cluster.

If you run version 1.0.0 or later of the AlloyDB Omni Operator, then this command prints the version of AlloyDB Omni used by your database cluster.

To check the version of the AlloyDB Omni Operator installed on your Kubernetes cluster, run this command:

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -n NAMESPACE -o jsonpath='{.status.primary.currentControlPlaneAgentsVersion}'

If you run version 1.0.0 or later of the AlloyDB Omni Operator, then this command prints the version number of the AlloyDB Omni Operator running on your Kubernetes cluster.

If you run a version of AlloyDB Omni Operator earlier than 1.0.0, follow the instructions in Upgrade from a pre-1.0.0 AlloyDB Omni Operator.

Otherwise, continue to the Check your target version numbers section.

Drop ScaNN indexes created with postgres_ann extension

The postgres_ann extension is renamed to alloyd_scann. If you have installed the postgres_ann extension and created ScaNN indexes using the extension, you must drop all ScaNN indexes and uninstall the extension before performing an upgrade, then upgrade AlloyDB Omni, and then create the indexes again using the alloydb_scann extension.

To handle any impact to your database due to the renaming of the postgres_ann extension, complete the following steps:

  1. Run and connect to AlloyDB Omni.

  2. Identify all tables that use the ScaNN index.

     \c DATABASE_NAME
 select schemaname, relname, indexrelname, indextype, indexconfig, indexsize, indexscan FROM pg_stat_ann_indexes;

    Replace DATABASE_NAME with the name of the database where you want to run the query.

  3. Save index definitions and parameters as a dump DDL using a utility like pg_dump to recreate the ScaNN indexes later.

    pg_dump -st TABLE_NAME DATABASE_NAME

    Replace the following:

    • DATABASE_NAME: the name of the database.
    • TABLE_NAME: the name of the table.

  4. Drop ScaNN Indexes that were created using the postgres_ann index.

    DROP INDEX INDEX_NAME;

    Replace INDEX_NAME with the name of the database where you want to run the query.

  5. Verify that none of your databases include ScaNN indexes. Use the following SQL query to verify the deletion: The following sql should return an empty result set.

     \c DATABASE_NAME
 select schemaname, relname, indexrelname, indextype, indexconfig, indexsize, indexscan FROM pg_stat_ann_indexes;

  6. Drop the postgres_ann extension using the following steps:

    1. Verify that the postgres_ann extension is installed in your database.
    select * from pg_extension;
    1. Drop the postgres_ann extension.
    DROP EXTENSION postgres_ann CASCADE;
    1. Verify that the postgres_ann extension is no longer installed in your database.
    select * from pg_extension;

Check your target version numbers

Kubernetes

If you run a version of AlloyDB Omni Operator 1.0.0 or later, then your next steps depend upon the version of AlloyDB Omni that you want to upgrade to. This, in turn, requires understanding of the AlloyDB Omni version number.

The AlloyDB Omni version number has the following components:

  • The major version number of its PostgreSQL compatibility
  • The minor version number of its PostgreSQL compatibility
  • The patch version number of this AlloyDB Omni release

For example, AlloyDB Omni version 15.5.5 is patch version 5 of the AlloyDB Omni that supports PostgreSQL version 15.5.

If you want to upgrade to a version of AlloyDB Omni that supports a newer version of PostgreSQL, then you must upgrade the AlloyDB Omni Operator itself, alongside your database cluster. Each set of AlloyDB Omni releases that support a particular PostgreSQL minor version has its own AlloyDB Omni Operator version number, which you can find in the release note for the AlloyDB Omni version.

If you want to upgrade only to a newer patch version of AlloyDB Omni, then you can upgrade only your database cluster, with no need to upgrade the AlloyDB Omni Operator itself.

Otherwise, continue to the Upgrade the AlloyDB Omni Operator section.

Upgrade the AlloyDB Omni Operator

Kubernetes

To upgrade the AlloyDB Omni Operator, follow these steps:

  1. Define the environment variables:

    export GCS_BUCKET=alloydb-omni-operator
export OPERATOR_VERSION=OPERATOR_VERSION
export HELM_PATH=$OPERATOR_VERSION/alloydbomni-operator-$OPERATOR_VERSION.tgz

    Replace OPERATOR_VERSION with the version of the AlloyDB Omni Operator that you are upgrading to—for example, 1.1.0.

  2. Download the latest AlloyDB Omni Operator:

    gsutil cp -r gs://$GCS_BUCKET/$HELM_PATH ./
tar -xvzf alloydbomni-operator-${OPERATOR_VERSION}.tgz

  3. Apply the latest AlloyDB Omni Operator custom resource definitions:

    kubectl apply -f alloydbomni-operator/crds

  4. Upgrade the AlloyDB Omni Operator Helm chart:

    helm upgrade alloydbomni-operator alloydbomni-operator-${OPERATOR_VERSION}.tgz \
--namespace alloydb-omni-system \
--atomic \
--timeout 5m

After completing the upgrade of your AlloyDB Omni Operator, follow the instructions in Perform an in-place upgrade to create a new database cluster.

If your AlloyDB Omni cluster was created with AlloyDB Omni Operator 1.0.0, then add the controlPlaneAgentsVersion field to the manifest and set it to 1.1.0 before upgrading the cluster to version 15.5.5. Otherwise, the following error displays:

admission webhook "vdbcluster.alloydbomni.dbadmin.goog" denied the request: unsupported database version 15.5.5 and/or control plane agents version 1.0.0

A sample manifest with the controlPlaneAgentsVersion field looks as follows:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
spec:
  databaseVersion: "15.5.5"
  controlPlaneAgentsVersion: "1.1.0"
...