<a id="explanation-project-architecture"></a>

# Project architecture

HAProxy is a TCP/HTTP reverse proxy which is particularly suited for high availability environments. It features connection persistence through HTTP cookies, load balancing, header addition, modification, and deletion both ways. It has request blocking capabilities and provides interface to display server status.

The `haproxy-operator` repository is a collection of charms and snaps that manages the deployment and operation of HAProxy:

1. `haproxy`: A machine charm managing HAProxy. See the [`haproxy` README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-operator) for more information.
2. `haproxy-spoe-auth`: A machine charm deploying an SPOE agent that serves as an authentication proxy. See the [`haproxy-spoe-auth-operator` README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-spoe-auth-operator) for more information.
3. `haproxy-route-policy`: A machine charm deploying the `haproxy-route-policy` application for controlling the data from different `haproxy-route` relations. See the [`haproxy-route-policy-operator` README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-route-policy-operator) for more information.

The repository also contains the snapped workload of some charms:

1. `haproxy-spoe-auth-snap`: A snap of the SPOE agent made for the haproxy-spoe-auth-operator charm. See the [haproxy-spoe-auth-snap README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-spoe-auth-snap) for more information.
2. `haproxy-route-policy-snap`: A snap of the `haproxy-route-policy` app made for the `haproxy-route-policy-operator` charm. See the [haproxy-route-policy-snap README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-route-policy) for more information.

## High-level overview of deployment

The `haproxy` charm is the central component, responsible for configuring and running the HAProxy reverse proxy on machine. It receives routing information from related applications via `haproxy-route` (HTTP) and `haproxy-route-tcp` (TCP) relations and generates the appropriate HAProxy configuration.

The `haproxy` charm can be deployed with the `haproxy-spoe-auth` charm to add an authentication layer via a Stream Processing Offload Engine (SPOE) agent packaged in `haproxy-spoe-auth-snap`. HAProxy delegates authentication decisions to this agent which is integrated with an OpenID Connect (OIDC) provider charm.

The `haproxy` charm can also be deployed with the `haproxy-route-policy` charm to control which backends are permitted to be routed through `haproxy-route` relations. The workload of the `haproxy-route-policy` charm is a Django application packaged as a snap. It evaluates incoming requests against configured rules and accepts or rejects them accordingly. It’s deployed together with a PostgreSQL database.

The `haproxy` charm can optionally be deployed with the `haproxy-ddos-protection-configurator` charm to add advanced DDoS protection via the `ddos-protection` interface. The `haproxy-ddos-protection-configurator` charm provides features such as rate limiting, connection blocking, and timeout to help protect backend services against distributed denial-of-service attacks.

## Integrations

The `haproxy` charm integrates with backend application charms via `haproxy-route` (HTTP) and `haproxy-route-tcp` (TCP) relations — these are required for a basic reverse proxy deployment. Optionally, the `haproxy-spoe-auth`, the `haproxy-route-policy`, and the `haproxy-ddos-protection-configurator` can be integrated with the `haproxy` charm to enable OIDC, policy enforcement and DDoS protection respectively.

See the Integrations section on each of the component’s Charmhub page for more details:

1. [Integrations for `haproxy`](https://charmhub.io/haproxy/integrations?channel=3.2/edge)
2. [Integrations for `haproxy-spoe-auth`](https://charmhub.io/haproxy-spoe-auth/integrations?channel=latest/edge)
3. [Integrations for `haproxy-route-policy`](https://charmhub.io/haproxy-route-policy/integrations?channel=latest/edge)
4. [Integrations for `haproxy-ddos-protection-configurator`](https://charmhub.io/haproxy-ddos-protection-configurator/integrations)
