Select a documentation version: <button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">18.4.0</button>

- [Current (18.4.0)](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/deploy-kubernetes.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/deploy-kubernetes.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.3.0/docs/deploy-kubernetes.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.1.0/docs/deploy-kubernetes.md.txt)
- [17.10.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.10.0/docs/deploy-kubernetes.md.txt)
- [17.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.9.0/docs/deploy-kubernetes.md.txt)
- [17.7.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.7.0/docs/deploy-kubernetes.md.txt)
- [17.5.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.5.0/docs/deploy-kubernetes.md.txt)
- [16.14.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.14.0/docs/deploy-kubernetes.md.txt)
- [16.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.13.0/docs/deploy-kubernetes.md.txt)
- [16.11.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.11.0/docs/deploy-kubernetes.md.txt)
- [16.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.9.0/docs/deploy-kubernetes.md.txt)
- [16.8.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.8.0/docs/deploy-kubernetes.md.txt)
- [16.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.3.0/docs/deploy-kubernetes.md.txt)
- [15.18.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.18.0/docs/deploy-kubernetes.md.txt)
- [15.17.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.17.0/docs/deploy-kubernetes.md.txt)
- [15.15.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.15.0/docs/deploy-kubernetes.md.txt)
- [15.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.13.0/docs/deploy-kubernetes.md.txt)
- [15.12.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.12.0/docs/deploy-kubernetes.md.txt)
- [15.7.1](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.7.1/docs/deploy-kubernetes.md.txt)
- [15.7.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.7.0/docs/deploy-kubernetes.md.txt)
- [15.5.5](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.5/docs/deploy-kubernetes.md.txt)
- [15.5.4](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/deploy-kubernetes.md.txt)
- [15.5.2](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.2/docs/deploy-kubernetes.md.txt)

<br />

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.

<br />

For instructions on installing AlloyDB Omni onto a standard Linux
environment, see
[Install AlloyDB Omni](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/deploy-vm.md.txt).

## Overview

To deploy AlloyDB Omni onto a Kubernetes cluster, install the
AlloyDB Omni Kubernetes 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 don't use the
AlloyDB Omni CLI, which is intended for
deployments onto individual Linux machines and not on Kubernetes clusters.

### Base image

Starting with version 1.5.0, AlloyDB Omni operator Kubernetes images are
built upon Red Hat's Universal Base Image (UBI) 9. This transition enhances
security, consistency, and compliance for your deployments.

### SHA digest image references

To prevent supply attacks and meet OpenShift Certification requirements,
the AlloyDB Omni operator uses SHA-256 digests instead of version tags
for all container image references.

- Automatic Upgrades: the AlloyDB Omni operator uses an internal
  ImageCatalog to manage these digests and to ensure reliable data plane
  rollbacks during failed upgrades.

- Enablement: while enabled by default for the OpenShift Certified package, users of the
  OLM or Helm packages can manually enable digest references by setting
  the `ENABLE_DIGEST_IMAGE_REFS` environment variable to `true` using
  the [Subscription config for OLM](https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md#env) or the `enableDigestImageRefs` value in the Helm chart.

## Before you begin

Before you install AlloyDB Omni on a Kubernetes cluster with
AlloyDB Omni operator, make sure that you meet the
following requirements.

### Choose a download or installation option

When you manage workloads on a generic Kubernetes cluster, you can use either Helm
or OLM. Helm is a universal package manager that uses Helm charts to install any
workload, including operators, across all Kubernetes variants. OLM---the standard, preferred choice on OpenShift platforms---
manages operator lifecycles with specialized OLM bundles.

Based on your environment and tooling, choose one of the following deployment methods:

<br />

| **Media** | **Download locations and installation guides** | **Deployment to** |
|---|---|---|
| **AlloyDB Omni operator with Helm Chart** | [Install AlloyDB Omni on Kubernetes](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/deploy-kubernetes.md.txt#install) | Bring-your-own Kubernetes container environment---for example, on-premises, public clouds, GKE, Amazon EKS, and Azure AKS. **Tip:** If your continuous delivery (CD) tooling is integrated with Helm, use this option. |
| **AlloyDB Omni operator with OLM bundle** | [OperatorHub.io](https://operatorhub.io/operator/alloydb-omni-operator) | Bring-your-own Kubernetes container environment---for example, on-premises, public clouds, Google Kubernetes Engine, Amazon EKS, and Azure AKS. To use an OLM bundle, install OLM on the Kubernetes cluster before you install the operator. For more information, see [olm.operatorframework.io](https://olm.operatorframework.io/). **Tip:** If your continuous delivery (CD) tooling already uses OLM, choose this option. |
| **OpenShift Operator with OLM Bundle** | [Openshift Container Platform Web Console](https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/web_console/web-console) | OpenShift environment OpenShift, a variant of Kubernetes, uses OLM as its standard, built-in method for packaging and deploying operators. |

<br />

### Verify access

Verify that you have access to the following:

- A Kubernetes cluster, running the following software:

  - Kubernetes version 1.21 or later.
  - [The `cert-manager` service](https://cert-manager.io/docs/installation/helm/#installing-from-the-oci-registry), installed using Helm.

  > [!NOTE]
  > **Note:** For GKE Autopilot clusters, install `cert-manager` with this flag: `--set global.leaderElection.namespace=cert-manager`

  A known race condition in `cert-manager` might cause certificate issuance to fail. To reduce the likelihood of this issue, configure the `cert-manager` controller with the recommended settings. For more information, see [Resolve certificate issuance failures in cert-manager](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/troubleshoot-kubernetes-operator.md.txt#cert-manager-issuance-failures).
- [The `kubectl` utility](https://kubernetes.io/docs/tasks/tools/#kubectl).

- [The `helm` package manager](https://helm.sh/docs/intro/install/) or [the Operator Lifecycle Manager](https://olm.operatorframework.io/docs/getting-started/).

### Fulfill hardware and software requirements

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 (cgroup) v2 enabled.

## Install the AlloyDB Omni operator

If you want to deploy AlloyDB Omni in your production
environment, see [Run AlloyDB Omni in production](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/run-alloydb-omni-production.md.txt).

You can install the AlloyDB Omni operator using different methods,
including Helm and the Operator Lifecycle Manager (OLM).

> [!NOTE]
> **Note:** AlloyDB Omni operator Helm charts are no longer available in Cloud Storage. You must download them from the OCI registry.

### Helm

To install the AlloyDB Omni operator, follow these steps:
**Note:** AlloyDB Omni operator Helm charts aren't available in Cloud Storage. You must download them from the OCI registry.

1. Install the AlloyDB Omni operator from the OCI registry:

   ```
   helm install alloydbomni-operator oci://gcr.io/alloydb-omni/alloydbomni-operator \
   --version 1.9.0 \
   --create-namespace \
   --namespace alloydb-omni-system \
   $(helm install --help | grep -q -- '--rollback-on-failure' && echo '--rollback-on-failure' || echo '--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
   ```

### OLM

To install the AlloyDB Omni operator using the Operator Lifecycle Manager, follow these steps:

1. Go to the [**AlloyDB Omni Operator**](https://operatorhub.io/operator/alloydb-omni-operator) page.

2. Click **Install**. If you haven't done
   so already, follow the instructions to install only the OLM operator
   and OperatorHub.io catalog.

3. Create the `alloydb-omni-system` namespace if it does not already exist.

   ```
   kubectl create ns alloydb-omni-system
   ```
4. Set up the OLM `OperatorGroup` to make sure that the operator is cluster-scoped.

   ```
   kubectl apply -f - <<EOF
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: operator-sdk-og
     namespace: alloydb-omni-system
   spec:
     upgradeStrategy: Default
   EOF
   ```
5. Install the operator using an OLM Subscription resource.

   ```
   kubectl apply -f - <<EOF
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: my-alloydb-omni-operator
     namespace: alloydb-omni-system
   spec:
     channel: stable
     name: alloydb-omni-operator
     source: operatorhubio-catalog
     sourceNamespace: olm
   EOF
   ```
6. Install the default certificate `ClusterIssuer`. This step is optional if you use
   [custom certificate issuers](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/manage-certificates-kubernetes-operator.md.txt).

   ```
   kubectl apply -f - <<EOF
   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: alloydbomni-selfsigned-cluster-issuer
   spec:
     selfSigned: {}
   EOF
   ```

### OLM

To install the AlloyDB Omni operator on your Red Hat OpenShift environment using the OLM, follow these steps:

1. [Sign in to your Red Hat OpenShift web console](https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/web_console/web-console).
2. For offline or disconnected users, you must manually mirror the required images to your private registry using tools that preserve SHA digests, such as `oc image mirror`. You must configure an `ImageDigestMirrorSet` to redirect image pulls from the public `gcr.io` repository to your private registry. This makes sure that the AlloyDB Omni operator can pull the required images using their immutable SHA256 digests.
3. In the OpenShift web console, navigate to **Operators \> OperatorHub** .
   The **AlloyDB Omni Operator** is listed in the **Certified** and **Community** catalogs.

4. In the AlloyDB Omni operator pane, click **Install**.

5. Install the default certificate `ClusterIssuer` by
   running the following commands. This step is optional if you use
   [custom certificate issuers](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/manage-certificates-kubernetes-operator.md.txt).

   ```
   kubectl apply -f - <<EOF
   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: alloydbomni-selfsigned-cluster-issuer
   spec:
     selfSigned: {}
   EOF
   ```

## Configure GDC connected storage

To install the AlloyDB Omni operator on
[GDC connected](https://docs.cloud.google.com/distributed-cloud/edge/latest/docs/overview),
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](https://docs.cloud.google.com/distributed-cloud/connected/latest/docs/storage.md.txt#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](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/).

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

> [!NOTE]
> **Note:** To secure data at rest using an external Key Management Service (KMS), such as HashiCorp Vault, you can [create a TDE-enabled cluster](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/create-tde-cluster.md.txt).

> [!CAUTION]
> **Important:** Don't create a database cluster in the `alloydb-omni-system` namespace. Not using this namespace improves isolation and security, and prevents conflicts between the operator and the database resources in the same Kubernetes cluster.

After you [install the AlloyDB Omni operator](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/deploy-kubernetes.md.txt) on your Kubernetes cluster, you can create an AlloyDB Omni database cluster on the Kubernetes cluster by applying a manifest similar to the following:

```yaml
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.4.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`](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/run-connect.md.txt#psql-kubernetes).

> [!NOTE]
> **Note:** Starting with version 1.1.0 of AlloyDB Omni operator, the administrator password secret is no longer deleted after you set it. You must keep the newly set secret for the lifespan of your AlloyDB Omni database cluster.

For additional sample manifests, see
[Kubernetes configuration samples](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/samples.md.txt). For more information
about Kubernetes manifests and how to apply them, see
[Managing resources](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/).

### Image pull secrets

If you are using a private registry for your container images, you can specify
the [image pull secrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)
for your database cluster. The AlloyDB Omni operator propagates the image
pull secrets to the database cluster's service account, named
`DB_CLUSTER_NAME-sa`.

To configure image pull secrets, provide the secret names in your database
cluster specification. The secret must exist in the same namespace as the
database cluster.

```yaml
spec:
  primarySpec:
    serviceAccount:
      imagePullSecrets:
      - name: PULL_SECRET_NAME
```

Replace `PULL_SECRET_NAME` with the name of the image pull
secret.

## 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)](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/kubernetes-ha.md.txt) 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 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:

1. 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.
2. 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
   ```
3. 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 roll back after an LDTM scaling operation fails.

## What's next

- [Explore Kubernetes configuration samples](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/samples.md.txt).
- [Plan storage and PVC sizes](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/plan-storage-kubernetes.md.txt).
- [Run and connect to AlloyDB Omni](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/run-connect.md.txt).
- [Manage AlloyDB Omni](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/manage.md.txt).
- [Manage high availability in Kubernetes](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/kubernetes-ha.md.txt).
- [Create a TDE-enabled cluster](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/create-tde-cluster.md.txt).