Run and connect to AlloyDB Omni

Select a documentation version:

This page describes how to run and connect to AlloyDB Omni after you deploy it to your Kubernetes cluster.

The Kubernetes-specific instructions on this page assume basic familiarity with operating Kubernetes.

Run AlloyDB Omni

The procedures you use to run AlloyDB Omni depend on whether you're running AlloyDB Omni on a Kubernetes cluster.

Start AlloyDB Omni

Start a stopped database cluster by setting isStopped to false in its manifest definition.

You can perform this on the command line using kubectl:

  kubectl patch dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME \
  -p '{"spec":{"primarySpec":{"isStopped":false}}}' --type=merge  -n DB_CLUSTER_NAMESPACE

Replace the following:

  • DB_CLUSTER_NAME: the name of this database cluster—for example, my-db-cluster.
  • DB_CLUSTER_NAMESPACE (Optional): the namespace you where created this database cluster—for example, my-db-cluster-namespace.

Check the status of AlloyDB Omni

  kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME  -n DB_CLUSTER_NAMESPACE

Replace the following:

Stop AlloyDB Omni

To stop a database cluster, set isStopped to true in its manifest definition.

You can perform this on the command line using kubectl:

  kubectl patch dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -p '{"spec":{"primarySpec":{"isStopped":true}}}' --type=merge -n DB_CLUSTER_NAMESPACE

Replace the following:

*   `DB_CLUSTER_NAME`: the name of this database cluster—for example, `my-db-cluster`.
*   `DB_CLUSTER_NAMESPACE` (Optional): the namespace where you created this database cluster—for example, `my-db-cluster-namespace`.

Connect to AlloyDB Omni running on Kubernetes

The AlloyDB Omni Kubernetes operator allows connections to the database cluster from within the same Kubernetes cluster, optionally using certificates for authentication.

Connect using the preinstalled psql

You can make a test connection using a psql client already installed on the pod running the database.

To do this, run the following commands:

export DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -n DB_CLUSTER_NAMESPACE -c database -- psql -h localhost -U postgres

Replace DB_CLUSTER_NAME with the name of your database cluster. It's the same database cluster name you declared when you created it.

You can skip setting the DB_CLUSTER_NAMESPACE, if you created the database cluster in the default namespace.

After you enter the command, the database server prompts you for a password. Enter the password whose base64-encoded version you supplied as a Kubernetes secret when creating the database cluster. For example, if you created the database cluster with a secret of Q2hhbmdlTWUxMjM=, then the login password to use here is ChangeMe123.

The AlloyDB Omni operator connects you to the server as the postgres user role and displays a postgres=# command prompt. You can now run psql commands and SQL queries.

To exit psql, run the \q command.

Connect from a separate pod in the same cluster

The pod running the AlloyDB Omni database cluster allows connections from within the same Kubernetes cluster, by default. As a best practice, we recommend securing all connections to the database cluster using TLS.

To provide your own server TLS certificate, specify a certificate secret when configuring your database cluster. If you don't specify a certificate secret, then the AlloyDB Omni Kubernetes operator creates a TLS certificate secret for you, based on a certificate signed by a self-signed certificate authority. In either case, you can require your database client pod to require certificate validation on every connection, ensuring TLS security.

To establish secure database connections using TLS, perform the following actions:

  • In the manifest that defines the pod making the client connections, specify a TLS certificate secret. It can be one of the following:

    • A TLS certificate secret that you have already created in your Kubernetes cluster. For more information about working with TLS certificate secrets in Kubernetes, see TLS Secrets.

    • The default certificate secret that the AlloyDB Omni Kubernetes operator creates for you, named DB_CLUSTER_NAME-ca-cert, if you do not specify a TLS secret as part of your database cluster's manifest.

  • Whenever your client pod connects to the database cluster, it must define the following environment variables prior to establishing the connection:

    • Set PGSSLMODE to "verify-ca".

    • Set PGSSLROOTCERT to the absolute path, on the client pod's filesystem, of the relevant ca.crt file.

The following example manifest shows how to configure a pod that installs the official PostgreSQL image, which includes the psql command-line client. The example presumes that you don't specify any TLS secret configuration in the manifest that defines your database cluster. Therefore, the AlloyDB Omni Kubernetes operator uses the default TLS secret, which is named dbs-al-cert-DB_CLUSTER_NAME.

apiVersion: v1
kind: Pod
metadata:
  name: postgres
  namespace: DB_CLUSTER_NAMESPACE
spec:
  containers:
  - image: "docker.io/library/postgres:latest"
    command:
      - "sleep"
      - "604800"
    imagePullPolicy: IfNotPresent
    name: db-client
    volumeMounts:
    - name: ca-cert
      mountPath: "/DB_CLUSTER_NAME-ca-cert"
      readOnly: true
  volumes:
  - name: ca-cert
    secret:
      secretName: dbs-al-cert-DB_CLUSTER_NAME
  restartPolicy: Always

Replace the following:

  • DB_CLUSTER_NAME: the name of your database cluster. It is the same database cluster name you declared when you created it.
  • DB_CLUSTER_NAMESPACE (Optional): the namespace where you created your database cluster.

You can now use the pod to securely connect to your database cluster using the following steps:

  1. Determine the internal IP address of your database cluster:

    kubectl get dbclusters.alloydbomni.dbadmin.goog -n DB_CLUSTER_NAMESPACE

    The output resembles the following:

    NAME              PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE
DB_CLUSTER_NAME   IP_ADDRESS        Ready          DBClusterReady

    Take note of IP_ADDRESS, and use it in the following step.

  2. Use psql to connect to your cluster from the client pod, setting the environment variables that enable and require TLS certificate verification:

    kubectl exec -it postgres -n DB_CLUSTER_NAMESPACE -- bash
PGSSLMODE="verify-ca" PGSSLROOTCERT=/DB_CLUSTER_NAME-ca-cert/ca.crt psql -h IP_ADDRESS -p 5432 -U postgres -d postgres

    Replace IP_ADDRESS with the internal IP address that you determined in the previous step.

What's next