<a id="how-to-index"></a>

# How-to guides

Manage the full operations lifecycle of the HAProxy charm, from initial traffic routing and protocol configuration through high-availability scaling and security hardening. Each guide assumes that you have already deployed the charm with Juju.

## Ingress and routing

HAProxy routes traffic to charmed applications as well as external workloads. Route behavior and backend approval policies can be customized through dedicated integrator charms.

* [Integrate with non-charm workloads](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/integrate-with-non-charm-workload/index.html.md#how-to-integrate-with-non-charm-workload): Route HTTP and TCP traffic to external services running outside Juju using the `ingress-configurator` charm.
* [Provide extra configuration to ingress requirers](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/provide-extra-configurations-for-ingress-requirer-charms/index.html.md#how-to-provide-extra-configurations-for-ingress-requirer-charms): Extend standard `ingress` relations with advanced `haproxy-route` features such as path rewrites and custom hostnames.
* [Control haproxy-route relation data with the policy charm](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/control-haproxy-route-relation-data/index.html.md#how-to-control-haproxy-route-relation-data): Restrict and approve backend routes dynamically using the `haproxy-route-policy` REST API.

## Protocol load balancing

Workloads requiring protocols beyond standard HTTP requires more advanced configurations. The HAProxy charm can provide gRPC load balancing over HTTP/2 and routes TCP traffic to a range of backend ports for services like FTP.

* [Provide load balancing for a gRPC server](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/loadbalancing-for-a-grpc-server/index.html.md#how-to-loadbalancing-for-a-grpc-server): Configure Layer-7 load balancing and ALPN negotiation for gRPC services.
* [Provide load balancing for an FTP server](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/loadbalancing-for-an-ftp-server/index.html.md#how-to-loadbalancing-for-an-ftp-server): Configure Layer-4 TCP frontends and port ranges for passive FTP and FTPS traffic.

## Security

Production deployments require defense against malicious traffic, identity verification, and encrypted communication. Built-in integrations protect frontends and ensure privacy compliance.

* [Enable DDoS Protection](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/enable-ddos-protection/index.html.md#how-to-enable-ddos-protection): Integrate the DDoS protection configurator charm to mitigate volumetric and rate-based abuse.
* [Protect a hostname using OpenID Connect](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/protect-hostname-spoe-auth/index.html.md#how-to-protect-hostname-spoe-auth): Enforce user authentication for proxied routes via the `haproxy-spoe-auth` integration.
* [Configure the backend protocol](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/configure-backend-protocol/index.html.md#how-to-configure-backend-protocol): Establish secure HTTPS connections between HAProxy and backend applications using CA certificates.
* [Use self-signed certificates](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/use-self-signed-certificates/index.html.md#how-to-use-self-signed-certificates): Generate and apply TLS certificates for testing and internal transport security.
* [Hash client IP addresses in logs](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/hash-client-ip-addresses-in-logs/index.html.md#how-to-hash-client-ip-addresses-in-logs): Anonymize client IP addresses in access logs using cryptographic salting for privacy compliance.

## High availability

Clustered deployments ensure uninterrupted traffic handling during unit failures or maintenance. A shared virtual IP coordinates traffic distribution and automatic recovery across units.

* [Configure high availability](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/configure-high-availability/index.html.md#how-to-configure-high-availability): Deploy the `keepalived` subordinate charm to establish a shared virtual IP across multiple HAProxy units.

## Operations and maintenance

Automated deployment workflows, version upgrades, and development tooling keep the HAProxy operator aligned with infrastructure requirements and community standards.

* [Add to existing Terraform project](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/deploy-with-terraform/index.html.md#how-to-deploy-with-terraform): Define and provision the HAProxy charm and its integrations using Terraform.
* [Upgrade](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/upgrade/index.html.md#how-to-upgrade): Update the HAProxy charm to a newer revision or track with minimal operational disruption.
* [Contribute](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/contribute/index.html.md#how-to-contribute): Set up a development environment to build the charm, run tests, and submit improvements.
