From 437d8c84fee00432ac1339c7eebeb94373f21ce7 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 25 May 2026 13:37:14 -0400 Subject: [PATCH 01/16] chore: reorganize home page for new model --- docs/index.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/index.md b/docs/index.md index 96d71d915..f8783b728 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,21 +9,17 @@ The HAProxy operator is an open-source software operator that deploys and operat ## In this documentation -| | | -|--|--| -| {ref}`Tutorial `
Get started - a hands-on introduction to using the charm for new users
| {ref}`How-to guides `
Step-by-step guides covering key operations and common tasks | -| {ref}`Reference `
Technical information - specifications, APIs, architecture | {ref}`Explanation `
Concepts - discussion and clarification of key topics | +TBD -## Contributing to this documentation +## How this documentation is organized -Documentation is an important part of this project, and we take the same open-source approach -to the documentation as the code. As such, we welcome community contributions, suggestions, and -constructive feedback on our documentation. -See {ref}`how_to_contribute` for more information. +The documentation uses the +[Diátaxis documentation structure](https://diataxis.fr/). - -If there's a particular area of documentation that you'd like to see that's missing, please -[file a bug](https://github.com/canonical/haproxy-operator/issues). +* The {ref}`Tutorial ` takes you step-by-step through a basic deployment of the HAProxy charm, and there are advanced tutorials covering load balancing for different server protocols. +* The {ref}`How-to guides ` assume you have basic familiarity with the HAProxy charm. They cover practical tasks such as configuring, integrating, and upgrading your HAProxy deployment. +* {ref}`Reference ` provides technical details on supported server protocols and authentication. +* {ref}`Explanation ` includes context and overviews on security and high availability. ## Project and community @@ -45,5 +41,10 @@ Tutorial How-to guides Reference Explanation +``` + +```{toctree} +:hidden: +:maxdepth: 1 Release notes ``` From 87246c6d97354b75da43238e0a806768fce3691a Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 25 May 2026 14:28:31 -0400 Subject: [PATCH 02/16] docs: New home page pattern --- docs/index.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index f8783b728..ddc00ccc1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,22 @@ The HAProxy operator is an open-source software operator that deploys and operat ## In this documentation -TBD +### Basics + +Start here to prepare your environment and set up a basic deployment of the HAProxy charm. + +* **Tutorial**: {ref}`tutorial_getting_started` + +### Understanding the HAProxy charm + +* **Server protocols**: {ref}`reference_http2_support` • {ref}`tutorial_loadbalancing_for_an_ftp_server` • {ref}`tutorial_loadbalancing_for_a_grpc_server` • {ref}`reference_grpc_support` +* **Configuring and integrating**: {ref}`Provide extra configuration to ingress requirers ` • {ref}`Configure a virtual IP on OpenStack ` • {ref}`Integrate with non-charmed workloads ` + +### Security and performance + +* **Security**: {ref}`Overview ` • {ref}`how_to_enable_ddos_protection` +* **SPOE authentication**: {ref}`reference_spoe-auth_support` • {ref}`Protect a hostname using OpenID Connect ` +* **High availability**: {ref}`explanation_high_availability` • {ref}`how_to_configure_high_availability` ## How this documentation is organized From 63c08b2de15fda919b1aab9e25d458f4ad5b7929 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 25 May 2026 14:33:44 -0400 Subject: [PATCH 03/16] chore: changelog --- docs/changelog.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/changelog.md b/docs/changelog.md index db0223ef7..e3d2845c2 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-05-25 + +- docs: Updated the home page to implement the new pattern for the "In this documentation" section. + ## 2026-04-17 - Added missing settings from haproxy-route-tcp relation template. From ef2c8e358b8e0adc3f9a8b4423fa13b7a557d3b9 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 25 May 2026 15:03:44 -0400 Subject: [PATCH 04/16] docs: Flesh out intro text, fix typos --- docs/index.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index ddc00ccc1..c2afc9af0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,11 @@ myst: --- # HAProxy operator -The HAProxy operator is an open-source software operator that deploys and operates HAProxy IAAS/VM that functions on Juju 3.3 and above. The charm offers advanced features such as TLS, monitoring and high-availability. This operator is built for **IAAS/VM** and is not supported in **Kubernetes** environments. +The HAProxy operator is an open-source software operator that deploys and operates HAProxy on Juju 3.3 and above. + +The charm provides a managed ingress entry point for backend applications, handling secure traffic routing and load balancing. It also offers advanced features such as TLS, monitoring and high-availability. This operator is built for **IaaS/VM** and is not supported in **Kubernetes** environments. + +This charm provides infrastructure operators and DevOps engineers straightforward deployment and operation of HAProxy. ## In this documentation @@ -28,7 +32,7 @@ Start here to prepare your environment and set up a basic deployment of the HAPr ## How this documentation is organized -The documentation uses the +This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/). * The {ref}`Tutorial ` takes you step-by-step through a basic deployment of the HAProxy charm, and there are advanced tutorials covering load balancing for different server protocols. @@ -42,8 +46,8 @@ The HAProxy operator is a member of the Ubuntu family. It's an open-source proje projects, contributions, suggestions, fixes, and constructive feedback. - [Code of conduct](https://ubuntu.com/community/code-of-conduct) -- [Get support](https://discourse.charmhub.io/) -- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) +- Get support through the [Discourse forum](https://discourse.charmhub.io/) +- Join our [online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) - {ref}`Contribute ` Thinking about using the HAProxy operator for your next project? From daa43bc323372532a767918819bd4ae4a1391bd1 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 25 May 2026 15:05:50 -0400 Subject: [PATCH 05/16] chore: remove intro text for basics sub-heading --- docs/index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index c2afc9af0..46227a10c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,9 +13,7 @@ This charm provides infrastructure operators and DevOps engineers straightforwar ## In this documentation -### Basics - -Start here to prepare your environment and set up a basic deployment of the HAProxy charm. +### Basics * **Tutorial**: {ref}`tutorial_getting_started` From ea13bd1ed9b24241c73440e7a099499a7ddc8f2f Mon Sep 17 00:00:00 2001 From: erinecon Date: Tue, 26 May 2026 11:15:06 -0400 Subject: [PATCH 06/16] docs: table format for new home page pattern --- docs/index.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/docs/index.md b/docs/index.md index 46227a10c..0e56833f8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,20 +13,13 @@ This charm provides infrastructure operators and DevOps engineers straightforwar ## In this documentation -### Basics - -* **Tutorial**: {ref}`tutorial_getting_started` - -### Understanding the HAProxy charm - -* **Server protocols**: {ref}`reference_http2_support` • {ref}`tutorial_loadbalancing_for_an_ftp_server` • {ref}`tutorial_loadbalancing_for_a_grpc_server` • {ref}`reference_grpc_support` -* **Configuring and integrating**: {ref}`Provide extra configuration to ingress requirers ` • {ref}`Configure a virtual IP on OpenStack ` • {ref}`Integrate with non-charmed workloads ` - -### Security and performance - -* **Security**: {ref}`Overview ` • {ref}`how_to_enable_ddos_protection` -* **SPOE authentication**: {ref}`reference_spoe-auth_support` • {ref}`Protect a hostname using OpenID Connect ` -* **High availability**: {ref}`explanation_high_availability` • {ref}`how_to_configure_high_availability` +| | | +|--|--| +| **Tutorial** | {ref}`tutorial_getting_started` | +| **Deployment** | {ref}`Ingress requirers ` • {ref}`Virtual IP on OpenStack ` • {ref}`High availability ` | +| **Supported protocols** | {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` | +| **Operations** | {ref}`Integrate with non-charmed workloads ` • {ref}`Upgrade ` | +| **Security** | {ref}`Overview ` • {ref}`DDoS protection ` • {ref}`Authentication proxy ` | ## How this documentation is organized From 56db03dd831af4f04cfa0617c35118659ce81b69 Mon Sep 17 00:00:00 2001 From: erinecon Date: Wed, 27 May 2026 15:48:12 -0400 Subject: [PATCH 07/16] docs: suggestions from @seb4stien --- docs/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 0e56833f8..ec53fdd95 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,9 +16,10 @@ This charm provides infrastructure operators and DevOps engineers straightforwar | | | |--|--| | **Tutorial** | {ref}`tutorial_getting_started` | -| **Deployment** | {ref}`Ingress requirers ` • {ref}`Virtual IP on OpenStack ` • {ref}`High availability ` | +| **Deployment** | {ref}`High availability ` • {ref}`Virtual IP on OpenStack ` | +| **Operations** | {ref}`Upgrade ` • {ref}`Contribute ` | +| **Integrations** | {ref}`Non-charmed workloads ` • {ref}`Ingress requirers ` | | **Supported protocols** | {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` | -| **Operations** | {ref}`Integrate with non-charmed workloads ` • {ref}`Upgrade ` | | **Security** | {ref}`Overview ` • {ref}`DDoS protection ` • {ref}`Authentication proxy ` | ## How this documentation is organized From 3b56454a610b9993e6a613ec16d4c07e899dd477 Mon Sep 17 00:00:00 2001 From: erinecon Date: Fri, 29 May 2026 11:49:53 -0400 Subject: [PATCH 08/16] docs: apply suggestions from @srbouffard --- docs/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index ec53fdd95..a1e474006 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ This charm provides infrastructure operators and DevOps engineers straightforwar | | | |--|--| -| **Tutorial** | {ref}`tutorial_getting_started` | +| **Get started** | {ref}`tutorial_getting_started` | | **Deployment** | {ref}`High availability ` • {ref}`Virtual IP on OpenStack ` | | **Operations** | {ref}`Upgrade ` • {ref}`Contribute ` | | **Integrations** | {ref}`Non-charmed workloads ` • {ref}`Ingress requirers ` | @@ -38,6 +38,7 @@ The HAProxy operator is a member of the Ubuntu family. It's an open-source proje projects, contributions, suggestions, fixes, and constructive feedback. - [Code of conduct](https://ubuntu.com/community/code-of-conduct) +- [File a bug](https://github.com/canonical/haproxy-operator/issues) - Get support through the [Discourse forum](https://discourse.charmhub.io/) - Join our [online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) - {ref}`Contribute ` From a5f2ab87b947d0aaf6f2f7982cdc2c5d83237124 Mon Sep 17 00:00:00 2001 From: erinecon Date: Fri, 29 May 2026 11:54:45 -0400 Subject: [PATCH 09/16] docs: add new pages, remove operations domain, and update redirected link --- docs/index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index a1e474006..7c890dec1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,9 +16,8 @@ This charm provides infrastructure operators and DevOps engineers straightforwar | | | |--|--| | **Get started** | {ref}`tutorial_getting_started` | -| **Deployment** | {ref}`High availability ` • {ref}`Virtual IP on OpenStack ` | -| **Operations** | {ref}`Upgrade ` • {ref}`Contribute ` | -| **Integrations** | {ref}`Non-charmed workloads ` • {ref}`Ingress requirers ` | +| **Deployment** | {ref}`High availability ` • {ref}`Backend routing ` • {ref}`Virtual IP on OpenStack ` | +| **Integrations** | {ref}`Relation endpoints ` • {ref}`Non-charmed workloads ` • {ref}`Ingress requirers ` | | **Supported protocols** | {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` | | **Security** | {ref}`Overview ` • {ref}`DDoS protection ` • {ref}`Authentication proxy ` | @@ -37,7 +36,7 @@ This documentation uses the The HAProxy operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community projects, contributions, suggestions, fixes, and constructive feedback. -- [Code of conduct](https://ubuntu.com/community/code-of-conduct) +- [Code of conduct](https://ubuntu.com/community/docs/ethos/code-of-conduct) - [File a bug](https://github.com/canonical/haproxy-operator/issues) - Get support through the [Discourse forum](https://discourse.charmhub.io/) - Join our [online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) From 3ffaef22f58a9a848c51b0992d1435838aabddc4 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 1 Jun 2026 10:29:18 -0400 Subject: [PATCH 10/16] docs: feedback from EvilDMP --- docs/index.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/index.md b/docs/index.md index 7c890dec1..2cda7c29d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,25 +9,33 @@ The HAProxy operator is an open-source software operator that deploys and operat The charm provides a managed ingress entry point for backend applications, handling secure traffic routing and load balancing. It also offers advanced features such as TLS, monitoring and high-availability. This operator is built for **IaaS/VM** and is not supported in **Kubernetes** environments. -This charm provides infrastructure operators and DevOps engineers straightforward deployment and operation of HAProxy. - ## In this documentation -| | | -|--|--| -| **Get started** | {ref}`tutorial_getting_started` | -| **Deployment** | {ref}`High availability ` • {ref}`Backend routing ` • {ref}`Virtual IP on OpenStack ` | -| **Integrations** | {ref}`Relation endpoints ` • {ref}`Non-charmed workloads ` • {ref}`Ingress requirers ` | -| **Supported protocols** | {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` | -| **Security** | {ref}`Overview ` • {ref}`DDoS protection ` • {ref}`Authentication proxy ` | +```{list-table} + :header-rows: 1 + :widths: 10 20 + +* - + - +* - **Get started** + - {ref}`tutorial_getting_started` +* - **Deployment** + - {ref}`Configure high availability ` • {ref}`Control backend routing ` • {ref}`Configure OpenStack virtual IP ` +* - **Integrations** + - {ref}`Relation endpoints ` • {ref}`Integrate with non-charmed workloads ` • {ref}`Configure ingress requirers ` +* - **Supported protocols** + - {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` +* - **Security** + - {ref}`Overview ` • {ref}`Enable DDoS protection ` • {ref}`Protect a hostname ` +``` ## How this documentation is organized This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/). -* The {ref}`Tutorial ` takes you step-by-step through a basic deployment of the HAProxy charm, and there are advanced tutorials covering load balancing for different server protocols. -* The {ref}`How-to guides ` assume you have basic familiarity with the HAProxy charm. They cover practical tasks such as configuring, integrating, and upgrading your HAProxy deployment. +* The {ref}`Tutorial ` takes you step-by-step through a basic deployment of the HAProxy charm. +* The {ref}`How-to guides ` cover practical tasks for configuring, integrating, and maintaining your HAProxy deployment. * {ref}`Reference ` provides technical details on supported server protocols and authentication. * {ref}`Explanation ` includes context and overviews on security and high availability. From 150160117b76ba4f43b90c1782795ed8574173d0 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 1 Jun 2026 15:50:02 -0400 Subject: [PATCH 11/16] docs: more feedback from evildmp --- docs/conf.py | 2 + docs/how-to/index.md | 30 ++++++----- .../loadbalancing-for-a-grpc-server.md | 50 ++++--------------- .../loadbalancing-for-an-ftp-server.md | 50 ++++--------------- docs/how-to/upgrade.md | 13 ++++- docs/index.md | 4 +- docs/reference/index.md | 2 +- docs/tutorial/getting-started.md | 8 +-- docs/tutorial/index.md | 12 +---- 9 files changed, 58 insertions(+), 113 deletions(-) rename docs/{tutorial => how-to}/loadbalancing-for-a-grpc-server.md (75%) rename docs/{tutorial => how-to}/loadbalancing-for-an-ftp-server.md (63%) diff --git a/docs/conf.py b/docs/conf.py index f1280bb86..5d6f64ad9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -232,6 +232,8 @@ 'reference/style-guide-myst/': '../myst-syntax-reference', 'reference/style-guide/': '../rst-syntax-reference', './getting-started': './tutorial/getting-started', + 'tutorial/loadbalancing-for-a-grpc-server': '/how-to/loadbalancing-for-a-grpc-server', + 'tutorial/loadbalancing-for-an-ftp-server': '/how-to/loadbalancing-for-an-ftp-server', } diff --git a/docs/how-to/index.md b/docs/how-to/index.md index ec4a0fc5f..96bc8f8f9 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -8,7 +8,8 @@ myst: # How-to guides -The following guides cover key processes and common tasks for managing and using the HAProxy charm. +Manage the full operations lifecycle of the HAProxy charm, from initial deployment through +production maintenance. Each guide assumes that you’ve already deployed the charm with Juju. ## Common use-cases @@ -16,37 +17,42 @@ Once you've set up the HAProxy charm, you can take advantage of the built-in fea ```{toctree} :maxdepth: 1 +Configure high availability Integrate with non-charm workloads Provide extra configurations for ingress requirer charms -Protect a hostname using OpenID Connect -Enable DDoS Protection Control haproxy-route relation data -Configure high availability +Configure virtual IP on OpenStack ``` -## Platform-specific workflows +## Loadbalancing -In some cases additional steps need to be performed on specific substrates to ensure that the charm is working as intended. +Additional steps need to be performed to provide loadbalancing to your deployment +depending on your required server protocol. ```{toctree} :maxdepth: 1 -Configure virtual IP on OpenStack +Provide loadbalancing for a gRPC server +Provide loadbalancing for an FTP server ``` -## Maintenance +## Security -This section contains how-to guides for maintenance actions that you might need to take while operating the charm. +The HAProxy charm comes with built-in configurations and integrations to secure your deployment +against vulnerabilities and attacks. ```{toctree} :maxdepth: 1 -Upgrade +Enable DDoS Protection +Protect a hostname using OpenID Connect ``` -## Development +## Maintenance and development -This section contains how-to guides for developing the charm. +Upgrades and community contributions ensure the HAProxy charm stays current +and benefits from ongoing improvements. ```{toctree} :maxdepth: 1 +Upgrade Contribute ``` diff --git a/docs/tutorial/loadbalancing-for-a-grpc-server.md b/docs/how-to/loadbalancing-for-a-grpc-server.md similarity index 75% rename from docs/tutorial/loadbalancing-for-a-grpc-server.md rename to docs/how-to/loadbalancing-for-a-grpc-server.md index f3f308cca..4c51a54e2 100644 --- a/docs/tutorial/loadbalancing-for-a-grpc-server.md +++ b/docs/how-to/loadbalancing-for-a-grpc-server.md @@ -1,53 +1,30 @@ -(tutorial_loadbalancing_for_a_grpc_server)= +(how_to_loadbalancing_for_a_grpc_server)= -# Loadbalancing for a gRPC server +# How to provide loadbalancing for a gRPC server -In this tutorial we'll look at how to deploy the HAProxy charm to provide load balancing for a VM running [`flagd`](https://flagd.dev). This tutorial is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms. +In this guide we'll look at how to deploy the HAProxy charm to provide load balancing for a VM running [`flagd`](https://flagd.dev). This guide is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms. ## Requirements You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space. -````{tip} -You can use Multipass to create an isolated environment by running: -``` -multipass launch 24.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G -``` -```` - -This tutorial requires the following software to be installed on your working station +This guide requires the following software to be installed on your working station (either locally or in the Multipass VM): - Juju 3.3 - LXD 5.21.4 -Use [Concierge](https://github.com/canonical/concierge) to set up Juju and LXD: - -``` -sudo snap install --classic concierge -sudo concierge prepare -p machine -``` +For this guide, Juju must be bootstrapped to a LXD controller. -This first command installs Concierge, and the second command uses Concierge to install -and configure Juju and LXD. +Follow the {ref}`setup instructions ` in the tutorial to achieve these requirements. -For this tutorial, Juju must be bootstrapped to a LXD controller. Concierge should -complete this step for you, and you can verify by checking for `msg="Bootstrapped Juju" provider=lxd` -in the terminal output and by running `juju controllers`. +## Set up a Juju model -If Concierge did not perform the bootstrap, run: +To manage resources effectively and to separate this guide's workload from your usual work, create a new model using the following command: -```bash -juju bootstrap lxd tutorial-controller ``` - -## Set up a tutorial model - -To manage resources effectively and to separate this tutorial's workload from your usual work, create a new model using the following command: - -``` -juju add-model haproxy-tutorial +juju add-model haproxy-guide ``` ## Deploy the HAProxy charm @@ -184,12 +161,3 @@ After running the command you should see the reply from `flagd`: } ``` -## Clean up the environment - -Well done! You've successfully completed this tutorial. - -To remove the model environment you created, use the following command: - -``` -juju destroy-model haproxy-tutorial -``` diff --git a/docs/tutorial/loadbalancing-for-an-ftp-server.md b/docs/how-to/loadbalancing-for-an-ftp-server.md similarity index 63% rename from docs/tutorial/loadbalancing-for-an-ftp-server.md rename to docs/how-to/loadbalancing-for-an-ftp-server.md index 2d27607e5..17dc42c42 100644 --- a/docs/tutorial/loadbalancing-for-an-ftp-server.md +++ b/docs/how-to/loadbalancing-for-an-ftp-server.md @@ -1,53 +1,30 @@ -(tutorial_loadbalancing_for_an_ftp_server)= +(how_to_loadbalancing_for_an_ftp_server)= -# Loadbalancing for an FTP server +# How to provide loadbalancing for an FTP server -In this tutorial we'll look at how to deploy the HAProxy charm to provide TCP load balancing for a VM running an FTP server. This tutorial is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms. +In this guide we'll look at how to deploy the HAProxy charm to provide TCP load balancing for a VM running an FTP server. This guide is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms. ## Requirements You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space. -````{tip} -You can use Multipass to create an isolated environment by running: -``` -multipass launch 24.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G -``` -```` - -This tutorial requires the following software to be installed on your working station +This guide requires the following software to be installed on your working station (either locally or in the Multipass VM): - Juju 3.3 - LXD 5.21.4 -Use [Concierge](https://github.com/canonical/concierge) to set up Juju and LXD: - -``` -sudo snap install --classic concierge -sudo concierge prepare -p machine -``` +For this guide, Juju must be bootstrapped to a LXD controller. -This first command installs Concierge, and the second command uses Concierge to install -and configure Juju and LXD. +Follow the {ref}`setup instructions ` in the tutorial to achieve these requirements. -For this tutorial, Juju must be bootstrapped to a LXD controller. Concierge should -complete this step for you, and you can verify by checking for `msg="Bootstrapped Juju" provider=lxd` -in the terminal output and by running `juju controllers`. +## Set up a Juju model -If Concierge did not perform the bootstrap, run: +To manage resources effectively and to separate this guide's workload from your usual work, create a new model using the following command: -```bash -juju bootstrap lxd tutorial-controller ``` - -## Set up a tutorial model - -To manage resources effectively and to separate this tutorial's workload from your usual work, create a new model using the following command: - -``` -juju add-model haproxy-tutorial +juju add-model haproxy-guide ``` ## Deploy the HAProxy charm @@ -132,12 +109,3 @@ Using binary mode to transfer files. ftp> ``` -## Clean up the environment - -Well done! You've successfully completed this tutorial. - -To remove the model environment you created, use the following command: - -``` -juju destroy-model haproxy-tutorial -``` diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md index 1e6582752..62c806f0f 100644 --- a/docs/how-to/upgrade.md +++ b/docs/how-to/upgrade.md @@ -2,8 +2,17 @@ # How to upgrade -Upgrade the charm with the `juju refresh` command: +Upgrade the charm with the `juju refresh` command. +For example, to upgrade `haproxy` along the `2.8/edge` channel, use: ```bash -juju refresh --channel=2.8/edge +juju refresh haproxy --channel=2.8/edge ``` + +The charm is stateless, so you don't need to perform a data backup +before upgrading. + +Breaking changes aren't introduced in subsequent revisions in a given `channel`. +As long as you upgrade using the same `channel`, all configurations and +relations should remain intact between `haproxy` and the other charms +in your deployment. diff --git a/docs/index.md b/docs/index.md index 2cda7c29d..05492ade8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,11 +20,11 @@ The charm provides a managed ingress entry point for backend applications, handl * - **Get started** - {ref}`tutorial_getting_started` * - **Deployment** - - {ref}`Configure high availability ` • {ref}`Control backend routing ` • {ref}`Configure OpenStack virtual IP ` + - {ref}`Configure high availability ` • {ref}`Control backend routing ` • {ref}`Create OpenStack virtual IP ` * - **Integrations** - {ref}`Relation endpoints ` • {ref}`Integrate with non-charmed workloads ` • {ref}`Configure ingress requirers ` * - **Supported protocols** - - {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` + - {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` * - **Security** - {ref}`Overview ` • {ref}`Enable DDoS protection ` • {ref}`Protect a hostname ` ``` diff --git a/docs/reference/index.md b/docs/reference/index.md index 20060d6d8..24708553b 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -15,6 +15,6 @@ The pages in this section contain technical information for topics relevant to t grpc-support.md http2-support.md relation-endpoints.md -spoe-auth-support.md +SPOE authentication Changelog <../changelog.md> ``` diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md index 9bdd156fa..e555dcbfa 100644 --- a/docs/tutorial/getting-started.md +++ b/docs/tutorial/getting-started.md @@ -4,6 +4,8 @@ In this tutorial we'll deploy the HAProxy charm to provide ingress to a backend application, then configure high-avalability using the `hacluster` relation. This tutorial is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms. +(tutorial_requirements)= + ## Requirements You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station @@ -142,7 +144,7 @@ juju destroy-model haproxy-tutorial --no-prompt ## Next steps -Check out these advanced tutorials to learn how to use HAProxy to provide load balancing for different protocols. +Check out these advanced guides to learn how to use HAProxy to provide load balancing for different protocols. -* {ref}`tutorial_loadbalancing_for_an_ftp_server` -* {ref}`tutorial_loadbalancing_for_a_grpc_server` +* {ref}`how_to_loadbalancing_for_an_ftp_server` +* {ref}`how_to_loadbalancing_for_a_grpc_server` diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 0152a32c2..ede3b739e 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -17,16 +17,6 @@ This tutorial walks through the deployment of the HAProxy charm to provide HTTP ```{toctree} :glob: :titlesonly: -Getting Started +Basic HAProxy deployment ``` -## Protocol-specific setup - -In these tutorials you will learn how to use HAProxy to provide load balancing for different protocols. - -```{toctree} -:glob: -:titlesonly: -Loadbalancing for an FTP server -Loadbalancing for a gRPC server -``` From 00578e8491ce2181295c8b596ad0e4f15d12b216 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 1 Jun 2026 15:54:45 -0400 Subject: [PATCH 12/16] fix(docs): spelling --- docs/how-to/index.md | 8 ++++---- docs/how-to/loadbalancing-for-a-grpc-server.md | 2 +- docs/how-to/loadbalancing-for-an-ftp-server.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 96bc8f8f9..095c4a197 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -24,15 +24,15 @@ Control haproxy-route relation data Configure virtual IP on OpenStack ``` -## Loadbalancing +## Load balancing -Additional steps need to be performed to provide loadbalancing to your deployment +Additional steps need to be performed to provide load balancing to your deployment depending on your required server protocol. ```{toctree} :maxdepth: 1 -Provide loadbalancing for a gRPC server -Provide loadbalancing for an FTP server +Provide load balancing for a gRPC server +Provide load balancing for an FTP server ``` ## Security diff --git a/docs/how-to/loadbalancing-for-a-grpc-server.md b/docs/how-to/loadbalancing-for-a-grpc-server.md index 4c51a54e2..4c175f0d5 100644 --- a/docs/how-to/loadbalancing-for-a-grpc-server.md +++ b/docs/how-to/loadbalancing-for-a-grpc-server.md @@ -1,6 +1,6 @@ (how_to_loadbalancing_for_a_grpc_server)= -# How to provide loadbalancing for a gRPC server +# How to provide load balancing for a gRPC server In this guide we'll look at how to deploy the HAProxy charm to provide load balancing for a VM running [`flagd`](https://flagd.dev). This guide is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms. diff --git a/docs/how-to/loadbalancing-for-an-ftp-server.md b/docs/how-to/loadbalancing-for-an-ftp-server.md index 17dc42c42..17be40ca3 100644 --- a/docs/how-to/loadbalancing-for-an-ftp-server.md +++ b/docs/how-to/loadbalancing-for-an-ftp-server.md @@ -1,6 +1,6 @@ (how_to_loadbalancing_for_an_ftp_server)= -# How to provide loadbalancing for an FTP server +# How to provide load balancing for an FTP server In this guide we'll look at how to deploy the HAProxy charm to provide TCP load balancing for a VM running an FTP server. This guide is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms. From 16fd8437e8ff9b726c73afcf98f8edac35bb6678 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 1 Jun 2026 15:55:36 -0400 Subject: [PATCH 13/16] chore: changelog --- docs/changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/changelog.md b/docs/changelog.md index ac6bcb141..b13537c6a 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -15,6 +15,7 @@ Each revision is versioned by the date of the revision. ## 2026-05-25 - docs: Updated the home page to implement the new pattern for the "In this documentation" section. +- docs: Reorganized two tutorials to how-to section; expanded the upgrade guide ## 2026-04-17 From 2bffa9a980e0a5cfba7379265b8a6dfa58c58b8b Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 1 Jun 2026 15:57:43 -0400 Subject: [PATCH 14/16] chore(docs): table width --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 05492ade8..54a2ba7e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,7 @@ The charm provides a managed ingress entry point for backend applications, handl ```{list-table} :header-rows: 1 - :widths: 10 20 + :widths: 10 25 * - - From 28c6dd21aa13ebe465d85c5893ee00f79f296eb3 Mon Sep 17 00:00:00 2001 From: erinecon Date: Mon, 1 Jun 2026 16:34:24 -0400 Subject: [PATCH 15/16] chore(docs): make spread test happy --- docs/tutorial/getting-started.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md index e555dcbfa..7e44824ea 100644 --- a/docs/tutorial/getting-started.md +++ b/docs/tutorial/getting-started.md @@ -138,10 +138,18 @@ Well done! You've successfully completed the HAProxy tutorial. To remove the model environment you created, use the following command: + + ``` juju destroy-model haproxy-tutorial --no-prompt ``` + + + + ## Next steps Check out these advanced guides to learn how to use HAProxy to provide load balancing for different protocols. From 450394fbb531dc763b8fcf6fcb0885c295bb7632 Mon Sep 17 00:00:00 2001 From: erinecon Date: Tue, 2 Jun 2026 14:40:37 -0400 Subject: [PATCH 16/16] docs: apply suggestions from @srbouffard --- docs/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index 54a2ba7e0..d0303aba3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,7 +7,9 @@ myst: The HAProxy operator is an open-source software operator that deploys and operates HAProxy on Juju 3.3 and above. -The charm provides a managed ingress entry point for backend applications, handling secure traffic routing and load balancing. It also offers advanced features such as TLS, monitoring and high-availability. This operator is built for **IaaS/VM** and is not supported in **Kubernetes** environments. +The charm provides a managed ingress entry point for backend applications, handling secure traffic routing and load balancing. It also offers advanced features such as TLS, monitoring and high-availability. + +This operator is built for **IaaS/VM** and is not supported in **Kubernetes** environments. ## In this documentation @@ -20,13 +22,13 @@ The charm provides a managed ingress entry point for backend applications, handl * - **Get started** - {ref}`tutorial_getting_started` * - **Deployment** - - {ref}`Configure high availability ` • {ref}`Control backend routing ` • {ref}`Create OpenStack virtual IP ` + - {ref}`Configure high availability ` | {ref}`Control backend routing ` | {ref}`Create OpenStack virtual IP ` * - **Integrations** - - {ref}`Relation endpoints ` • {ref}`Integrate with non-charmed workloads ` • {ref}`Configure ingress requirers ` + - {ref}`Relation endpoints ` | {ref}`Integrate with non-charmed workloads ` | {ref}`Configure ingress requirers ` * - **Supported protocols** - - {ref}`FTP ` • {ref}`gRPC ` • {ref}`HTTP/2 ` + - {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 ` ``` ## How this documentation is organized