diff --git a/docs/changelog.md b/docs/changelog.md index c8b8261e6..9cf30c4db 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Each revision is versioned by the date of the revision. +## 2026-07-06 + +- docs: Add a how-to guide for configuring the backend protocol. + ## 2026-06-26 - docs: Add docs on the Terraform module. diff --git a/docs/how-to/configure-backend-protocol.md b/docs/how-to/configure-backend-protocol.md new file mode 100644 index 000000000..3c5764ba5 --- /dev/null +++ b/docs/how-to/configure-backend-protocol.md @@ -0,0 +1,45 @@ +--- +myst: + html_meta: + "description lang=en": "Learn about how to configure the backend protocol to use HTTPS for connections." +--- + +(how_to_configure_backend_protocol)= + +# How to set the protocol to HTTPS for a backend application + +By default, the HAProxy charm enforces HTTPS for connections from clients while communicating with backend applications over HTTP. In some scenarios, you may also want to use HTTPS as the communication protocol for connections between HAProxy and the backend applications. + +To do so, HAProxy verifies the identity of the backend application against a set of trusted certificate authority (CA) certificates. These certificates are sent to the `haproxy` charm through the `receive-ca-certs` relation. Therefore, at least one `receive-ca-certs` relation is required before you can set the backend protocol to HTTPS. + +This guide assumes that you have already deployed the `haproxy` charm and integrated it with a `haproxy-route` requirer. In this guide we use the [`ingress-configurator`](https://charmhub.io/ingress-configurator) charm as the requirer. + +## Transfer the CA certificate of the backend application + +Integrate the charm that provides the backend CA certificate with the `haproxy` charm through the `receive-ca-certs` relation. In this guide we use the `self-signed-certificates` charm as an example: + +```sh +juju integrate haproxy:receive-ca-certs self-signed-certificates +``` + +Verify that the CA certificate has been transferred and written to the expected location on the HAProxy unit: + +```sh +juju ssh haproxy/leader ls /var/lib/haproxy/cas +``` + +You should see the `cas.pem` file listed in the output. + +## Configure the backend protocol + +Set the `backend-protocol` configuration on the `ingress-configurator` charm to `https`: + +```sh +juju config ingress-configurator backend-protocol=https +``` + +Once all charms have settled into an "Active" state, HAProxy establishes HTTPS connections to the backend application and verifies its identity using the transferred CA certificate. + +## Verify the backend protocol + +Send a request through HAProxy and confirm that you can still reach the backend application, and that the backend application is now terminating TLS. diff --git a/docs/how-to/index.md b/docs/how-to/index.md index dba3b920a..e6dacacfb 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -45,6 +45,7 @@ against vulnerabilities and attacks. :maxdepth: 1 Enable DDoS Protection Protect a hostname using OpenID Connect +Configure the backend protocol ``` ## Maintenance and development diff --git a/docs/index.md b/docs/index.md index 1f73aefa9..88776e062 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,7 @@ This operator is built for **IaaS/VM** and is not supported in **Kubernetes** en * - **Other supported protocols** - {ref}`FTP ` | {ref}`gRPC ` | {ref}`HTTP/2 ` * - **Security** - - {ref}`Overview ` | {ref}`Enable DDoS protection ` | {ref}`Protect a hostname ` + - {ref}`Overview ` | {ref}`Enable DDoS protection ` | {ref}`Protect a hostname ` | {ref}`Configure HTTPS backend protocol ` ``` ## How this documentation is organized