This page documents AlloyDB Omni version 18.1.0 using the Kubernetes deployment option. Choose a different deployment option.

Install AlloyDB Omni on Kubernetes

Select a documentation version:

This page provides an overview of the AlloyDB Omni Kubernetes operator, with instructions for using it to deploy AlloyDB Omni onto a Kubernetes cluster. This page assumes basic familiarity with Kubernetes operation.

Overview

To deploy AlloyDB Omni onto a Kubernetes cluster, install the AlloyDB Omni operator, an extension to the Kubernetes API provided by Google.

You configure and control a Kubernetes-based AlloyDB Omni database cluster by pairing declarative manifest files with the kubectl utility, just like any other Kubernetes-based deployment.

AlloyDB Omni operator 1.1.0 compatibility

The AlloyDB Omni operator version 1.1.0 is not compatible with versions 15.5.3 and 15.5.4 of AlloyDB Omni. If you use one of these versions of AlloyDB Omni, you might receive an error similar to the following:

Error from server (Forbidden): error when creating "[...]/dbcluster.yaml": admission webhook "vdbcluster.alloydbomni.dbadmin.goog" denied the request: unsupported database version 15.5.3

Before you begin

You need access to the following:

A Kubernetes cluster, running the following software:
- Kubernetes version 1.21 or later.
- The cert-manager service.
The kubectl utility.
The helm package manager.
The Google Cloud CLI. After you install the gcloud CLI, you must authenticate your Google Cloud account by running gcloud auth login.

Each node in the Kubernetes cluster must have the following:

A minimum of two x86 or AMD64 CPUs.
At least 8GB of RAM.
Linux kernel version 4.18 or later.
Control group v2 (cgroup v2) enabled.

Install the AlloyDB Omni operator

To install the AlloyDB Omni operator, follow these steps:

Note: AlloyDB Omni operator Helm charts are no longer available in
Cloud Storage. You must download them from the OCI registry.

Authenticate Docker and Helm:

gcloud auth configure-docker gcr.io

gcloud auth print-access-token | helm registry login -u oauth2accesstoken --password-stdin gcr.io

Install the AlloyDB Omni operator from the OCI registry:

helm install alloydbomni-operator oci://gcr.io/alloydb-omni/alloydbomni-operator \
  --version 1.7.0 \
  --create-namespace \
  --namespace alloydb-omni-system \
  --atomic \
  --timeout 5m

Successful installation displays the following output:

NAME: alloydbomni-operator
LAST DEPLOYED: CURRENT_TIMESTAMP
NAMESPACE: alloydb-omni-system
STATUS: deployed
REVISION: 1
TEST SUITE: None

Configure GDC connected storage

To install the AlloyDB Omni operator on GDC connected, you need to follow additional steps to configure storage because GDC connected clusters don't set a default storage class. You must set a default storage class before you create an AlloyDB Omni database cluster.

To learn how to set Symcloud Storage as the default storage class, see Set Symcloud Storage as the default storage class.

For more information about changing the default for all other storage classes, see Change the default StorageClass.

Red Hat OpenShift reconciliation steps

If you use Red Hat OpenShift 4.12 or later, you must complete the following steps after you install the AlloyDB Omni operator and before you create an AlloyDB Omni database cluster on the Kubernetes cluster. Otherwise, you can skip these steps.

Add permissions to update AlloyDB Omni instance finalizers by editing the system:controller:statefulset-controller cluster role as follows:
```
kubectl edit clusterrole system:controller:statefulset-controller
```
In the text editor, append the following to the end of the cluster role:
```
- apiGroups:
  - alloydbomni.internal.dbadmin.goog
  resources:
  - instances/finalizers
  verbs:
  - update
- apiGroups:
  - alloydbomni.internal.dbadmin.goog
  resources:
  - backuprepositories/finalizers
  verbs:
  - update
```
The StatefulSet controller must have additional permissions to update instance finalizers added to the cluster role since Red Hat OpenShift has OwnerReferencesPermissionEnforcement enabled. Without the permission to update instance finalizers, the StatefulSet controller fails to create the database Persistent Volume Claim (PVC) with the following error message found in the database StatefulSet events:
```
Warning  FailedCreate  [...] cannot set blockOwnerDeletion if an ownerReference refers to a resource you can't set finalizers on
```
Add permissions to update AlloyDB Omni DBInstance finalizers by editing the fleet-manager-role cluster role:
```
kubectl edit clusterrole fleet-manager-role
```

In the text editor, append the following to the end of the cluster role:

- apiGroups:
  - alloydbomni.dbadmin.goog
  resources:
  - dbinstances/finalizers
  verbs:
  - update

Add the anyuid security context constraint to the default service account in your Red Hat OpenShift project as follows:
```
oc adm policy add-scc-to-user anyuid system:serviceaccount:OPENSHIFT_PROJECT:default
```
You must allow the default service account to use the anyuid security context constraint since, within the database Pod, the init container runs as root and the other containers run with specific user IDs. Without permission to use anyuid, the StatefulSet controller fails to create the database PVC with the following error message found in the database StatefulSet events:
```
Warning  FailedCreate  [...]    unable to validate against any security context constraint
```

Create a database cluster

An AlloyDB Omni database cluster contains all the storage and compute resources needed to run an AlloyDB Omni server, including the primary server, any replicas, and all of your data.

After you install the AlloyDB Omni operator on your Kubernetes cluster, you can create an AlloyDB Omni database cluster on the Kubernetes cluster by applying a manifest similar to the following:

apiVersion: v1
kind: Secret
metadata:
  name: db-pw-DB_CLUSTER_NAME
type: Opaque
data:
  DB_CLUSTER_NAME: "ENCODED_PASSWORD"
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
spec:
  databaseVersion: "18.1.0"
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-DB_CLUSTER_NAME
    resources:
      cpu: CPU_COUNT
      memory: MEMORY_SIZE
      disks:
      - name: DataDisk
        size: DISK_SIZE

Replace the following:

DB_CLUSTER_NAME: the name of this database cluster—for example, my-db-cluster.
ENCODED_PASSWORD: the database login password for the default postgres user role, encoded as a base64 string—for example, Q2hhbmdlTWUxMjM= for ChangeMe123.
CPU_COUNT: the number of CPUs available to each database instance in this database cluster.
MEMORY_SIZE: the amount of memory per database instance of this database cluster. We recommend setting this to 8 gigabytes per CPU. For example, if you set cpu to 2 earlier in this manifest, then we recommend setting memory to 16Gi.
DISK_SIZE: the disk size per database instance—for example, 10Gi.

After you apply this manifest, your Kubernetes cluster contains an AlloyDB Omni database cluster with the specified memory, CPU, and storage configuration. To establish a test connection with the new database cluster, see Connect using the preinstalled psql.

For more information about Kubernetes manifests and how to apply them, see Managing resources.

Scale a database cluster

To scale the compute resources for your database cluster, update the cpu and memory values in your db-cluster.yaml manifest and apply the changes. The scaling process depends on whether you opt for a regular scaling operation or a low downtime scaling operation.

Regular scaling

When you update your scaling specification and apply the manifest without any further configuration, the database pods restart instantly. This results in brief downtime across the primary and standby instances while the new resource allocations take effect.

Low downtime scaling

For high availability (HA) clusters with at least one standby, you can minimize downtime during scaling using the Low Downtime Maintenance (LDTM) prepare-and-switch strategy. This strategy applies the scaling changes to the standby first, performs a swift switchover, and then and then applies the changes to the original primary instance. You can scale up or down with the LDTM strategy.

To enable and monitor low downtime scaling, follow these steps:

Enable low downtime scaling. Add the enableLDTM annotation to your database cluster:
```
kubectl annotate dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME dbcluster.dbadmin.goog/enableLDTM=true
```
Replace DB_CLUSTER_NAME with the name of your database cluster.
Apply the updated scaling specs. Update the cpu and memory values under primarySpec.resources in your manifest, and apply the changes:
```
kubectl apply -f db-cluster.yaml
```
Monitor the scaling process. Check the LDTMScalingInProgress status condition to monitor the operation:
```
kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -o yaml | yq '.status.conditions[] | select(.type == "LDTMScalingInProgress")'
```
Replace DB_CLUSTER_NAME with the name of your database cluster.

While the process is in progress, the status is true. When the scaling is complete, the condition's status changes to false.

Limitations

LDTM scaling is only supported for HA clusters with at least one standby.
You cannot perform two LDTM operations simultaneously. For example, you can either use LDTM to scale database clusters or to perform minor version upgrades, but not both at the same time.
You must manually rollback after a failed LDTM scaling operation.