<a id="how-to-haproxy-loadbalancing-grpc"></a>

# How to load balance a gRPC server through HAProxy

You can configure the `ingress-configurator` charm to expose a
gRPC backend through HAProxy.

gRPC load balancing requires the backend to support HTTP/2 over TLS. HAProxy
routes gRPC traffic through port 443 by default, or through a dedicated frontend
port configured via `external-grpc-port`.

## Prerequisites

- A HAProxy deployment with TLS configured. See the
  [HAProxy getting started tutorial](https://canonical.com/juju/docs/haproxy-charm/latest/tutorial/getting-started/) for setup
  instructions.
- A gRPC backend reachable from the Juju model with TLS enabled. See the HAProxy
  operator’s
  [gRPC load balancing guide](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/loadbalancing-for-a-grpc-server/)
  for instructions on setting up a gRPC backend (the `flagd` section).

## Deploy and configure the `ingress-configurator` charm

```sh
juju deploy ingress-configurator grpc-configurator --channel=latest/edge
```

Set the backend address, port, protocol, and hostname. The `backend-protocol`
must be `https` for gRPC backends:

```sh
GRPC_SERVER_ADDRESS=<backend-ip>
juju config grpc-configurator \
    backend-addresses=$GRPC_SERVER_ADDRESS \
    backend-ports=<backend-port> \
    backend-protocol=https \
    hostname=<grpc-hostname>
```

If you want gRPC traffic on a dedicated frontend port rather than port 443, also
set `external-grpc-port`:

```sh
juju config grpc-configurator external-grpc-port=<port>
```

## Integrate with HAProxy

Use the `haproxy-route` interface, which operates at the HTTP level and supports
gRPC traffic.

```sh
juju integrate grpc-configurator:haproxy-route haproxy
```

## Verify the connection

Once all charms are active, verify the gRPC server is reachable through HAProxy:

```sh
HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"')
grpcurl -insecure -d '{}' <grpc-hostname>:<port> <service-method>
```

A successful response returns the output from your gRPC service method with no connection errors.
