From 68092e013297337feed3473880ab05bb5ad99dfd Mon Sep 17 00:00:00 2001 From: tphan025 Date: Mon, 6 Jul 2026 14:41:09 +0200 Subject: [PATCH 1/4] docs: add how-to guide for configuring the backend protocol --- docs/changelog.md | 4 +++ docs/how-to/configure-backend-protocol.md | 39 +++++++++++++++++++++++ docs/how-to/index.md | 1 + 3 files changed, 44 insertions(+) create mode 100644 docs/how-to/configure-backend-protocol.md 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..aa1e08571 --- /dev/null +++ b/docs/how-to/configure-backend-protocol.md @@ -0,0 +1,39 @@ +(how_to_configure_backend_protocol)= + +# How to configure the backend protocol + +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` integration 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 From 4e7a1708552a0773d79604c0bcaa4bb0d9de7cc7 Mon Sep 17 00:00:00 2001 From: Phan Trung Thanh Date: Tue, 7 Jul 2026 14:15:19 +0200 Subject: [PATCH 2/4] Update docs/how-to/configure-backend-protocol.md Co-authored-by: Erin Conley --- docs/how-to/configure-backend-protocol.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/how-to/configure-backend-protocol.md b/docs/how-to/configure-backend-protocol.md index aa1e08571..fa9023d26 100644 --- a/docs/how-to/configure-backend-protocol.md +++ b/docs/how-to/configure-backend-protocol.md @@ -1,3 +1,9 @@ +--- +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 configure the backend protocol From eeb73f3b5db3c9fb9e3e02390fd9cecffa432e12 Mon Sep 17 00:00:00 2001 From: Phan Trung Thanh Date: Tue, 7 Jul 2026 14:15:28 +0200 Subject: [PATCH 3/4] Update docs/how-to/configure-backend-protocol.md Co-authored-by: Erin Conley --- docs/how-to/configure-backend-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/configure-backend-protocol.md b/docs/how-to/configure-backend-protocol.md index fa9023d26..281737c16 100644 --- a/docs/how-to/configure-backend-protocol.md +++ b/docs/how-to/configure-backend-protocol.md @@ -10,7 +10,7 @@ myst: 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` integration is required before you can set the backend protocol to HTTPS. +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. From f6e2fa33e6f075b7fa224dfa5f2257503181e0fb Mon Sep 17 00:00:00 2001 From: tphan025 Date: Tue, 7 Jul 2026 14:19:38 +0200 Subject: [PATCH 4/4] docs: address review comments on configure-backend-protocol guide - Add HTML metadata description - Rename title to 'How to set the protocol to HTTPS for a backend application' - Fix 'integration' -> 'relation' in prerequisite paragraph - Add guide link to Security row in home page table --- docs/how-to/configure-backend-protocol.md | 2 +- docs/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/configure-backend-protocol.md b/docs/how-to/configure-backend-protocol.md index 281737c16..3c5764ba5 100644 --- a/docs/how-to/configure-backend-protocol.md +++ b/docs/how-to/configure-backend-protocol.md @@ -6,7 +6,7 @@ myst: (how_to_configure_backend_protocol)= -# How to configure the 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. 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