This page describes how to run and connect to AlloyDB Omni after you install it on your own machine or 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 in a container on a single server, or on a Kubernetes cluster. This section divides its instructions between these deployment styles.
Start AlloyDB Omni
Single-server
To start a stopped AlloyDB Omni container, run either the
docker container start
command or the
podman container start
command:
Docker
docker container start CONTAINER_NAME
Replace CONTAINER_NAME
with the name that you assigned
to the AlloyDB Omni container when you installed it.
Podman
podman container start CONTAINER_NAME
Replace CONTAINER_NAME
with the name that you assigned
to the AlloyDB Omni container when you installed it.
Kubernetes
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
Single-server
To check the status of all of the containers you have running, run either
the docker container ls
command or the podman container ls
command:
Docker
docker container ls
Podman
podman container ls
If your AlloyDB Omni container is running, then its
name will appear in the NAMES
column of the output table. The corresponding
row summarizes the container's state.
If the name of your container doesn't appear in the NAMES
column, then
your AlloyDB Omni is not running.
Kubernetes
kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME
Replace DB_CLUSTER_NAME
with the name of your database
cluster.
Stop AlloyDB Omni
Single-server
To stop a AlloyDB Omni container, run either the
docker container stop
command or the
podman container stop
command:
Docker
docker container stop CONTAINER_NAME
Replace CONTAINER_NAME
with the name that you assigned
to the AlloyDB Omni container when you installed it.
Podman
podman container stop CONTAINER_NAME
Replace CONTAINER_NAME
with the name that you assigned
to the AlloyDB Omni container when you installed it.
Kubernetes
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 a single server
The AlloyDB Omni container includes its own copy of psql
that lets
you open an interactive SQL shell session with its database server.
You can also connect to AlloyDB Omni from outside the container, using the PostgreSQL-compatible software of your choice.
For information about connecting to an AlloyDB Omni database cluster running on a Kubernetes cluster, see Connect to AlloyDB Omni running on Kubernetes.
Connect using the containerized psql
To connect to the AlloyDB Omni database server using its own
containerized copy of psql
, run the following command:
Docker
docker exec -it CONTAINER_NAME psql -U postgres
Replace CONTAINER_NAME
with the name that you assigned
to the AlloyDB Omni container when you installed it.
Podman
podman exec -it CONTAINER_NAME psql -U postgres
Replace CONTAINER_NAME
with the name that you assigned
to the AlloyDB Omni container when you installed it.
This command 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 using your own applications
Any application that works with PostgreSQL can also work with AlloyDB Omni, with no modification needed.
To connect to the AlloyDB Omni database server, expose networking from the AlloyDB Omni docker container to your host machine by adding --network=host
or -p 5432:5432
to your docker run
or podman run
command when you start AlloyDB Omni.
To select a custom port number, use -p [HOST_PORT]:5432
when you start AlloyDB Omni. Then, use any PostgreSQL-compatible client or code library to connect to port 5432
or the custom port number that you specified.
After connecting to the database server, you can define, query, and modify your databases using DML and SQL queries by using standard PostgreSQL communication protocols.
Because AlloyDB Omni runs within your own environment, you can control how you connect to AlloyDB Omni. This includes allowing or restricting network access to this service according to the needs of your application, just as you would with an ordinary PostgreSQL server.
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 relevantca.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:
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.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.