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

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

<br />

This page describes how to run and connect to AlloyDB Omni
after you [deploy it to your Kubernetes cluster](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/deploy-kubernetes.md.txt).

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

```bash
  kubectl patch dbclusters.alloydbomni.dbadmin.goog dbcluster-sample \
  -p '{"spec":{"primarySpec":{"isStopped":false}}}' --type=merge
```

### Check the status of AlloyDB Omni

```bash
kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME
```

Replace `DB_CLUSTER_NAME` with the [name of your database
cluster](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/deploy-kubernetes#create).

### 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`:

```bash
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:

```bash
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](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/deploy-kubernetes#create).

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](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/deploy-kubernetes#create). 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](https://www.postgresql.org/docs/current/app-psql.html)
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](https://kubernetes.io/docs/concepts/configuration/secret/#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](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/deploy-kubernetes#create). Therefore, the
AlloyDB Omni Kubernetes Operator uses the default TLS secret, which is named
`dbs-al-cert-DB_CLUSTER_NAME`.

```yaml
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](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/deploy-kubernetes#create).

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:

   ```bash
   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:

   ```bash
   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](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/manage.md.txt)