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/configure-load-balancer-k8s.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/configure-load-balancer-k8s.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.3.0/docs/configure-load-balancer-k8s.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.1.0/docs/configure-load-balancer-k8s.md.txt)
- [17.10.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.10.0/docs/configure-load-balancer-k8s.md.txt)
- [17.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.9.0/docs/configure-load-balancer-k8s.md.txt)
- [17.7.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.7.0/docs/configure-load-balancer-k8s.md.txt)
- [17.5.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.5.0/docs/configure-load-balancer-k8s.md.txt)
- [16.14.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.14.0/docs/configure-load-balancer-k8s.md.txt)
- [16.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.13.0/docs/configure-load-balancer-k8s.md.txt)
- [16.11.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.11.0/docs/configure-load-balancer-k8s.md.txt)
- [16.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.9.0/docs/configure-load-balancer-k8s.md.txt)
- [16.8.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.8.0/docs/configure-load-balancer-k8s.md.txt)
- [16.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.3.0/docs/configure-load-balancer-k8s.md.txt)
- [15.18.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.18.0/docs/configure-load-balancer-k8s.md.txt)
- [15.17.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.17.0/docs/configure-load-balancer-k8s.md.txt)
- [15.15.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.15.0/docs/configure-load-balancer-k8s.md.txt)
- [15.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.13.0/docs/configure-load-balancer-k8s.md.txt)
- [15.12.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.12.0/docs/configure-load-balancer-k8s.md.txt)
- [15.7.1](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.7.1/docs/configure-load-balancer-k8s.md.txt)
- [15.7.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.7.0/docs/configure-load-balancer-k8s.md.txt)
- [15.5.5](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.5/docs/configure-load-balancer-k8s.md.txt)
- [15.5.4](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.5.4/docs/configure-load-balancer-k8s.md.txt)

<br />

To expose your AlloyDB Omni database cluster to clients outside your Kubernetes cluster, you can configure a `LoadBalancer` Service in the `DBCluster` manifest. This document is for database administrators and Kubernetes operators who manage AlloyDB Omni deployments on Kubernetes and need to customize load balancer behavior.

<br />

When you enable external incoming traffic in your `DBCluster` manifest, the
AlloyDB Omni Kubernetes operator creates a Kubernetes `Service` object of type
`LoadBalancer`. Different Kubernetes platforms use custom annotations to control
load balancer properties, such as internal or external IP address assignment.
AlloyDB Omni lets you specify these annotations in the
`spec.primarySpec.dbLoadBalancerOptions.annotations` field of your `DBCluster`
manifest. When you create or update the database cluster with
`spec.allowExternalIncomingTraffic` set to `true`, the
AlloyDB Omni operator applies those annotations to the
`metadata.annotations` field of the `LoadBalancer` `Service` object.

## Configure a load balancer using the database spec

You can configure custom load balancer annotations by setting the
`dbLoadBalancerOptions` field in the `spec.primarySpec` section of your
`DBCluster` manifest.

### Kubernetes

Annotations define the type and properties of the load balancer `Service`
object in your Kubernetes environment. Check the documentation for your
Kubernetes platform or load balancer implementation to identify the
supported annotation keys and values.

To create a database cluster with custom load balancer annotations and allow
incoming traffic from outside the Kubernetes cluster, apply the following
manifest:

```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: db-pw-DB_CLUSTER_NAME
  namespace: NAMESPACE
type: Opaque
data:
  DB_CLUSTER_NAME: "ENCODED_PASSWORD"
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
  namespace: NAMESPACE
spec:
  databaseVersion: "18.4.0"
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-DB_CLUSTER_NAME
    resources:
      memory: 5Gi
      cpu: 1
      disks:
      - name: DataDisk
        size: 10Gi
    dbLoadBalancerOptions:
      annotations:
        ANNOTATION_KEY: "ANNOTATION_VALUE"
  allowExternalIncomingTraffic: true
EOF
```

Replace the following:

- `DB_CLUSTER_NAME`: a name for your database cluster---for example, `my-db-cluster`.
- `NAMESPACE`: the Kubernetes namespace for your database cluster.
- `ENCODED_PASSWORD`: the password for the `postgres` administrator user, encoded as a base64 string.
- `ANNOTATION_KEY` and `ANNOTATION_VALUE`: a load balancer annotation key and string value supported by your Kubernetes environment. Enclose the value in double quotes, even for boolean or numeric values such as `"true"`. You can specify one or more key-value pairs under `annotations`.

In this manifest:

- `ANNOTATION_KEY: "ANNOTATION_VALUE"`: specifies a custom annotation that the AlloyDB Omni operator adds to the load balancer `Service` object for your database cluster.
- `allowExternalIncomingTraffic: true`: sets the `allowExternalIncomingTraffic` field to `true` to allow incoming traffic from outside the Kubernetes cluster.

> [!NOTE]
> **Note:** To configure custom load balancer annotations on an existing database cluster, add `allowExternalIncomingTraffic: true` and `primarySpec.dbLoadBalancerOptions.annotations` to your existing `DBCluster` manifest and apply it, rather than re-applying the sample `Secret` and `resources` block.

## Get the database cluster and connectivity details

### Kubernetes

To verify that the database cluster resource is in the `Ready` status, run
the following command:

```bash
kubectl get dbclusters.alloydbomni.dbadmin.goog -n NAMESPACE -w
```

Replace `NAMESPACE` with the Kubernetes namespace for your
database cluster.

The output is similar to the following:

    NAME               PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE
    DB_CLUSTER_NAME    10.95.0.84        Ready          DBClusterReady

To verify that your custom annotation and the assigned external endpoint
exist on the load balancer `Service` object, run the following command:

```bash
kubectl get svc LOAD_BALANCER_SERVICE_NAME -n NAMESPACE -o yaml
```

Replace the following:

- `LOAD_BALANCER_SERVICE_NAME`: the name of the operator-managed `LoadBalancer` `Service` object. For the primary read-write endpoint, the AlloyDB Omni operator names this `Service` `al-DB_CLUSTER_NAME-rw-elb` (you can also list `Service` objects by running `kubectl get svc -n NAMESPACE`).
- `NAMESPACE`: the name of the Kubernetes namespace for your load balancer `Service` object.

The output is similar to the following:

```html
apiVersion: v1
kind: Service
metadata:
  annotations:
    ANNOTATION_KEY: "ANNOTATION_VALUE"
  creationTimestamp: "2024-02-22T15:26:18Z"
  finalizers:
  - service.kubernetes.io/load-balancer-cleanup
  labels:
    alloydbomni.internal.dbadmin.goog/dbcluster: DB_CLUSTER_NAME
    alloydbomni.internal.dbadmin.goog/dbcluster-ns: NAMESPACE
  name: LOAD_BALANCER_SERVICE_NAME
  namespace: NAMESPACE
  ownerReferences:
  - apiVersion: alloydbomni.dbadmin.goog/v1
    blockOwnerDeletion: true
    controller: true
    kind: DBCluster
    name: DB_CLUSTER_NAME
    uid: 2dd76c9f-7698-4210-be41-6d2259840a85
  resourceVersion: "33628320"
  uid: 1f45362b-6d6f-484d-ad35-11c14e91933e
spec:
  allocateLoadBalancerNodePorts: true
  clusterIP: 10.60.4.76
  clusterIPs:
  - 10.60.4.76
  externalTrafficPolicy: Cluster
  internalTrafficPolicy: Cluster
  ipFamilies:
  - IPv4
  ipFamilyPolicy: SingleStack
  ports:
  - name: db
    nodePort: 31453
    port: 5432
    protocol: TCP
    targetPort: 5432
  selector:
    alloydbomni.internal.dbadmin.goog/dbcluster: DB_CLUSTER_NAME
    alloydbomni.internal.dbadmin.goog/dbcluster-ns: NAMESPACE
    alloydbomni.internal.dbadmin.goog/task-type: database
    dbs.internal.dbadmin.goog/ha-role: Primary
  sessionAffinity: None
  type: LoadBalancer
status:
  loadBalancer:
    ingress:
    - ip: 10.95.0.84
```

The output includes the following fields:

- `metadata.annotations`: contains the `ANNOTATION_KEY: "ANNOTATION_VALUE"` annotation that you configured in your `DBCluster` manifest.
- `status.loadBalancer.ingress`: displays the external endpoint assigned to the load balancer `Service` object. Depending on your Kubernetes environment, the load balancer controller populates either `ip` (which matches the `PRIMARYENDPOINT` value of your database cluster) or `hostname` (for DNS-based load balancers such as on AWS EKS, where `status.primary.endpoints` on the `DBCluster` records the hostname and port).

## What's next

- [Manage and monitor AlloyDB Omni](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/manage.md.txt)
- [Use the PgBouncer connection pooler](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/use-connection-pooler-kubernetes.md.txt)