Run and connect to AlloyDB Omni

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  
dbcluster-sample  
 \ 
  
-p  
 '{"spec":{"primarySpec":{"isStopped":false}}}' 
  
--type = 
merge 

Check the status of AlloyDB Omni

 kubectl  
get  
dbclusters.alloydbomni.dbadmin.goog  
 DB_CLUSTER_NAME 
 

Replace DB_CLUSTER_NAME with the name of your database cluster .

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  
dbcluster-sample  
-p  
 '{"spec":{"primarySpec":{"isStopped":true}}}' 
  
--type = 
merge 

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  
-o  
 jsonpath 
 = 
 '{.items[0].metadata.name}' 
 ` 
 
 kubectl  
 exec 
  
-ti  
 $DBPOD 
  
-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 .

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 
 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 DB_CLUSTER_NAME with the name of your database cluster. It is the same database cluster name you declared when you created it .

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 
   

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

• Manage and monitor AlloyDB Omni