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.
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. 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:
A Kubernetes cluster, running the following software:
If you do need to install the gcloud CLI, note that the step of
running gcloud init is optional. Installing AlloyDB Omni
does not require authentication with a Google Account.
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:
Successful installation displays the following output:
NAME: alloydbomni-operator
LAST DEPLOYED: CURRENT_TIMESTAMP
NAMESPACE: alloydb-omni-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
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:
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[[["\u003cp\u003eThis guide explains how to deploy AlloyDB Omni onto a Kubernetes cluster using the AlloyDB Omni Operator, an extension to the Kubernetes API.\u003c/p\u003e\n"],["\u003cp\u003eDeployment of AlloyDB Omni on Kubernetes clusters is managed through declarative manifest files and the \u003ccode\u003ekubectl\u003c/code\u003e utility, not the AlloyDB Omni CLI.\u003c/p\u003e\n"],["\u003cp\u003eBefore starting, you need access to a Kubernetes cluster, \u003ccode\u003ecert-manager\u003c/code\u003e, \u003ccode\u003ekubectl\u003c/code\u003e, \u003ccode\u003ehelm\u003c/code\u003e, and the Google Cloud CLI, and ensure each node has sufficient CPU, RAM, and Linux kernel version.\u003c/p\u003e\n"],["\u003cp\u003eThe installation of the AlloyDB Omni Operator involves defining environment variables, downloading the operator, and installing it via Helm, with a cleanup step afterward.\u003c/p\u003e\n"],["\u003cp\u003eCreating an AlloyDB Omni database cluster in Kubernetes involves applying a manifest file that defines the cluster's name, version, CPU, memory, and disk specifications.\u003c/p\u003e\n"]]],[],null,["# Install AlloyDB Omni on Kubernetes\n\nSelect a documentation version: 15.5.2keyboard_arrow_down\n\n- [Current (16.8.0)](/alloydb/omni/current/docs/deploy-kubernetes)\n- [16.8.0](/alloydb/omni/16.8.0/docs/deploy-kubernetes)\n- [16.3.0](/alloydb/omni/16.3.0/docs/deploy-kubernetes)\n- [15.12.0](/alloydb/omni/15.12.0/docs/deploy-kubernetes)\n- [15.7.1](/alloydb/omni/15.7.1/docs/deploy-kubernetes)\n- [15.7.0](/alloydb/omni/15.7.0/docs/deploy-kubernetes)\n- [15.5.5](/alloydb/omni/15.5.5/docs/deploy-kubernetes)\n- [15.5.4](/alloydb/omni/15.5.4/docs/deploy-kubernetes)\n- [15.5.2](/alloydb/omni/15.5.2/docs/deploy-kubernetes)\n\n\u003cbr /\u003e\n\n| **Note:** Your use of AlloyDB Omni is subject to the agreement between you and Google that governs Google Cloud offerings. If you do not have a Google Cloud account, or have not otherwise entered into an agreement with Google that governs Google Cloud offerings, please do not proceed or download this software until you have done so. To create a Google Cloud account, see [the Google Cloud homepage](/docs/get-started).\n\n\u003cbr /\u003e\n\nThis page provides an overview of the AlloyDB Omni Kubernetes Operator, with instructions\nfor using it to deploy AlloyDB Omni onto a Kubernetes cluster. This\npage assumes basic familiarity with Kubernetes operation.\n\nFor instructions on installing AlloyDB Omni onto a standard Linux\nenvironment, see [Install AlloyDB Omni](/alloydb/omni/15.5.2/docs/install).\n\nOverview\n--------\n\nTo deploy AlloyDB Omni onto a Kubernetes cluster, install the\nAlloyDB Omni Operator, an extension to the Kubernetes API provided by\nGoogle.\n\nYou configure and control a Kubernetes-based AlloyDB Omni database\ncluster by pairing declarative manifest files with the `kubectl` utility, just\nlike any other Kubernetes-based deployment. You do not use [the\nAlloyDB Omni CLI](/alloydb/omni/15.5.2/docs/omni-cli), which is intended for\ndeployments onto individual Linux machines and not Kubernetes clusters.\n\nBefore you begin\n----------------\n\nYou need access to the following:\n\n- A Kubernetes cluster, running the following software:\n - Kubernetes version 1.21 or later.\n - [The `cert-manager` service](https://cert-manager.io/docs/installation).\n- [The `kubectl` utility](https://kubernetes.io/docs/tasks/tools/#kubectl).\n- [The `helm` package manager](https://helm.sh/docs/intro/install/).\n- The [Google Cloud CLI](/sdk/docs/install).\n\n If you do need to install the gcloud CLI, note that the step of\n running `gcloud init` is optional. Installing AlloyDB Omni\n does not require authentication with a Google Account.\n\nEach node in the Kubernetes cluster must have the following:\n\n- A minimum of two x86 or AMD64 CPUs.\n- At least 8GB of RAM.\n- Linux kernel version 4.18 or later.\n- Control group v2 (cgroup v2) enabled.\n\nUse Helm charts\n---------------\n\nYou can use Helm charts from the repository [alloydb-omni-samples](https://github.com/GoogleCloudPlatform/alloydb-omni-samples/tree/main/k8s/helm) to deploy the components shown in this guide.\n\nInstall the AlloyDB Omni Operator\n---------------------------------\n\nTo install the AlloyDB Omni Operator, follow these steps:\n\n1. Define several environment variables:\n\n export GCS_BUCKET=alloydb-omni-operator\n export HELM_PATH=$(gcloud storage cat gs://$GCS_BUCKET/latest)\n export OPERATOR_VERSION=\"${HELM_PATH%%/*}\"\n\n2. Download the AlloyDB Omni Operator:\n\n gcloud storage cp gs://$GCS_BUCKET/$HELM_PATH ./ --recursive\n\n3. Install the AlloyDB Omni Operator:\n\n helm install alloydbomni-operator alloydbomni-operator-${OPERATOR_VERSION}.tgz \\\n --create-namespace \\\n --namespace alloydb-omni-system \\\n --atomic \\\n --timeout 5m\n\n Successful installation displays the following output: \n\n NAME: alloydbomni-operator\n LAST DEPLOYED: \u003cvar translate=\"no\"\u003eCURRENT_TIMESTAMP\u003c/var\u003e\n NAMESPACE: alloydb-omni-system\n STATUS: deployed\n REVISION: 1\n TEST SUITE: None\n\n4. Clean up by deleting the downloaded AlloyDB Omni Operator\n installation file. The file is named\n `alloydbomni-operator-`\u003cvar translate=\"no\"\u003eVERSION_NUMBER\u003c/var\u003e`.tgz`, and is located in\n your current working directory.\n\nCreate a database cluster\n-------------------------\n\nAn AlloyDB Omni *database cluster* contains all the storage and\ncompute resources needed to run an AlloyDB Omni server, including\nthe primary server, any replicas, and all of your data.\n\nAfter you install the AlloyDB Omni Operator on your Kubernetes cluster,\nyou can create an AlloyDB Omni database cluster on the Kubernetes\ncluster by applying a manifest similar to the following: \n\n apiVersion: v1\n kind: Secret\n metadata:\n name: db-pw-\u003cvar translate=\"no\"\u003eDB_CLUSTER_NAME\u003c/var\u003e\n type: Opaque\n data:\n \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nt\"\u003eDB_CLUSTER_NAME\u003c/span\u003e\u003c/var\u003e: \"\u003cvar translate=\"no\"\u003eENCODED_PASSWORD\u003c/var\u003e\"\n ---\n apiVersion: alloydbomni.dbadmin.goog/v1\n kind: DBCluster\n metadata:\n name: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eDB_CLUSTER_NAME\u003c/span\u003e\u003c/var\u003e\n spec:\n databaseVersion: \"15.5.2\"\n primarySpec:\n adminUser:\n passwordRef:\n name: db-pw-\u003cvar translate=\"no\"\u003eDB_CLUSTER_NAME\u003c/var\u003e\n resources:\n cpu: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eCPU_COUNT\u003c/span\u003e\u003c/var\u003e\n memory: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eMEMORY_SIZE\u003c/span\u003e\u003c/var\u003e\n disks:\n - name: DataDisk\n size: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eDISK_SIZE\u003c/span\u003e\u003c/var\u003e\n storageClass: standard\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eDB_CLUSTER_NAME\u003c/var\u003e: the name of this database cluster---for\n example, `my-db-cluster`.\n\n- \u003cvar translate=\"no\"\u003eENCODED_PASSWORD\u003c/var\u003e: the database login password for the\n default `postgres` user role, encoded as a base64 string---for example,\n `Q2hhbmdlTWUxMjM=` for `ChangeMe123`.\n\n- \u003cvar translate=\"no\"\u003eCPU_COUNT\u003c/var\u003e: the number of CPUs available to each\n database instance in this database cluster.\n\n- \u003cvar translate=\"no\"\u003eMEMORY_SIZE\u003c/var\u003e: the amount of memory per database instance of this\n database cluster. We recommend setting this to 8 gigabytes per CPU. For\n example, if you set `cpu` to `2` earlier in this manifest, then we recommend\n setting `memory` to `16Gi`.\n\n- \u003cvar translate=\"no\"\u003eDISK_SIZE\u003c/var\u003e: the disk size per database instance---for example, `10Gi`.\n\nAfter you apply this manifest, your Kubernetes cluster contains an\nAlloyDB Omni database cluster with the specified memory, CPU,\nand storage configuration. To establish a test connection with the new\ndatabase cluster, see [Connect using the preinstalled `psql`](/alloydb/omni/15.5.2/docs/run-connect#psql-kubernetes).\n\nFor more information about Kubernetes manifests and how to apply them, see\n[Managing\nresources](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/).\n\nWhat's next\n-----------\n\n- [Run and connect to AlloyDB Omni](/alloydb/omni/15.5.2/docs/run-connect)\n- [Manage AlloyDB Omni](/alloydb/omni/15.5.2/docs/manage)\n- [Manage high availability in Kubernetes](/alloydb/omni/15.5.2/docs/kubernetes-ha)"]]