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/redhat-orchestrator/current/docs/configure-load-balancer.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/redhat-orchestrator/18.4.0/docs/configure-load-balancer.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/redhat-orchestrator/18.3.0/docs/configure-load-balancer.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/redhat-orchestrator/18.1.0/docs/configure-load-balancer.md.txt)

<br />

You can configure a load balancer for AlloyDB Omni using the RPM orchestrator.

<br />

## Limitations

The following limitations apply:

- The endpoint is limited to the ReadWrite endpoint. Readonly endpoints will be supported in future.

## Before you begin

Before you configure the load balancer, make sure that you meet the following
requirements:

- To define load balancer nodes, in your deployment specification file,
  include a `load_balancer_nodes` group that contains the hostnames or IP
  addresses of your dedicated load balancer VMs:

  ```yaml
  alloydbomni:
    vars:
      ...
    children:
      load_balancer_nodes:
  hosts:
  lb-node-1:
  lb-node-2:
  ```
- To configure the firewall, allow the following incoming traffic:

  - On dedicated load balancer VMs:

    - Port `5432` (TCP): for HAProxy database traffic.

    - Port `6432` (TCP): for PgBouncer connection pooling traffic, if
      applicable.

    - VRRP protocol: for `keepalived` leader election and health checks.

  - On database nodes:

    - Port `8086` (HTTP): for load balancer health checks.
- If you're using the Google Cloud environment, then set `ENVIRONMENT_TYPE` to `gcp`.
  Then you must authenticate your gcloud CLI account by running
  `gcloud auth login` as the `root` user. Additionally, the authenticated
  account must have the following permissions:

  - `compute.instances.get`
  - `compute.instances.list`
  - `compute.instances.updateNetworkInterface`

## Configure the load balancer

The RPM orchestrator uses HAProxy to distribute traffic and Keepalived
to provide high availability with a virtual IP (VIP).

### Update the resource specification

In your `DBCluster` specification file, add `dbLoadBalancerOptions`, which makes
sure that the cluster manager and orchestrator know how to manage the load
balancer endpoints.

```yaml
DBCluster:
  metadata:
    name: DBCLUSTER_NAME
  spec:
    primarySpec:
      # ... other primary settings ...
      dbLoadBalancerOptions:
ENVIRONMENT_TYPE::
loadBalancerIP: "VIRTUAL_IP"
loadBalancerType: "internal"
loadBalancerInterface: "VIRTUAL_IP_INTERFACE"
```

Replace the following:

- `ENVIRONMENT_TYPE`:
  determines the environment where cluster is set up---`onprem` or `gcp`.

- `DBCLUSTER_NAME`:
  the name of your AlloyDB Omni database cluster---for
  example, `my-db-cluster`.

- `VIRTUAL_IP`: static IP
  address used for the floating, virtual IP. Database client applications use
  the IP address defined here. To make sure that Keepalived can broadcast
  Gratuitous Address Resolution Protocols (GARPs) successfully, this IP
  address must meet the following conditions: it must be available; it can't
  loopback; and in the case of on-premises, it belongs to the same subnet as
  your primary node interfaces.

- `VIRTUAL_IP_INTERFACE`:
  network interface where
  `VIRTUAL_IP` is configured.
  The default value is `eth0`.

## Apply the configuration

Apply the configuration changes using your preferred orchestrator interface.

### Ansible

Run the bootstrap playbook using your inventory and resource specification files:

```bash
ansible-playbook DBCLUSTER_PLAYBOOK -i "DEPLOYMENT_SPECIFICATION" \
      -e resource_spec="DBCLUSTER_SPECIFICATION"
```

Replace the following variables:

- `DBCLUSTER_PLAYBOOK`:
  path to the playbook that you created for your database cluster in
  [Create a cluster](https://docs.cloud.google.com/alloydb/omni/redhat-orchestrator/current/docs/create-cluster.md.txt).

- `DEPLOYMENT_SPECIFICATION`:
  path to the deployment specification that you created in
  [Install AlloyDB Omni components](https://docs.cloud.google.com/alloydb/omni/redhat-orchestrator/current/docs/install-components.md.txt).

- `DBCLUSTER_SPECIFICATION`:
  path to your cluster specifications.

### `alloydbctl`

Apply the resource and deployment specifications:

```bash
alloydbctl apply -d "DEPLOYMENT_SPECIFICATION" -r "DBCLUSTER_SPECIFICATION"
```

Replace the following variables:

- `DEPLOYMENT_SPECIFICATION`:
  path to the deployment specification you created in
  [Install AlloyDB Omni components](https://docs.cloud.google.com/alloydb/omni/redhat-orchestrator/current/docs/install-components.md.txt).

- `DBCLUSTER_SPECIFICATION`:
  path to your cluster specifications.

## Verify the load balancer

After the RPM orchestrator completes the setup, verify
that you can connect to the database cluster using the VIP:

```bash
psql -h VIRTUAL_IP -U postgres
```

Replace `VIRTUAL_IP` with the IP address you
configured in the `loadBalancerIP` field.

The load balancer automatically routes your connection to the current primary
node.