Install AlloyDB Omni on Kubernetes

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.

For instructions on installing AlloyDB Omni onto a standard Linux environment, see Install AlloyDB Omni.


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. You do not use the AlloyDB Omni CLI, which is intended for deployments onto individual Linux machines and not Kubernetes clusters.

Before you begin

You need access to the following:

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.

Use Helm charts

You can use Helm charts from the repository alloydb-omni-samples to deploy the components shown in this guide.

Install the AlloyDB Omni Operator

To install the AlloyDB Omni Operator, follow these steps:

  1. Define several environment variables:

    export GCS_BUCKET=alloydb-omni-operator
    export HELM_PATH=$(gsutil cat gs://$GCS_BUCKET/latest)
    export OPERATOR_VERSION="${HELM_PATH%%/*}"
  2. Download the AlloyDB Omni Operator:

    gsutil cp -r gs://$GCS_BUCKET/$HELM_PATH ./
  3. Install the AlloyDB Omni Operator:

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

    Successful installation displays the following output:

    NAME: alloydbomni-operator
    NAMESPACE: alloydb-omni-system
    STATUS: deployed
    TEST SUITE: None
  4. Clean up by deleting the downloaded AlloyDB Omni Operator installation file. The file is named alloydbomni-operator-VERSION_NUMBER.tgz, and is located in your current working directory.

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
  name: db-pw-DB_CLUSTER_NAME
type: Opaque
kind: DBCluster
  databaseVersion: "15.5.2"
        name: db-pw-DB_CLUSTER_NAME
      cpu: CPU_COUNT
      memory: MEMORY_SIZE
      - name: DataDisk
        size: DISK_SIZE
        storageClass: standard

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.

What's next