diff --git a/docs/changelog.md b/docs/changelog.md index 1e5365e94..b13537c6a 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -12,6 +12,11 @@ Each revision is versioned by the date of the revision. - Added relation endpoints reference page. +## 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 - Added missing settings from haproxy-route-tcp relation template. 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..095c4a197 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 +## Load balancing -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 load balancing to your deployment +depending on your required server protocol. ```{toctree} :maxdepth: 1 -Configure virtual IP on OpenStack +Provide load balancing for a gRPC server +Provide load balancing 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..4c175f0d5 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 load balancing 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..17be40ca3 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 load balancing 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 96d71d915..d0303aba3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,34 +5,51 @@ 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. ## 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 | +```{list-table} + :header-rows: 1 + :widths: 10 25 -## Contributing to this documentation +* - + - +* - **Get started** + - {ref}`tutorial_getting_started` +* - **Deployment** + - {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 ` +* - **Security** + - {ref}`Overview ` | {ref}`Enable DDoS protection ` | {ref}`Protect a hostname ` +``` -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. +## How this documentation is organized +This 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. +* 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. ## Project and community 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) -- [Get support](https://discourse.charmhub.io/) -- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) +- [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) - {ref}`Contribute ` Thinking about using the HAProxy operator for your next project? @@ -45,5 +62,10 @@ Tutorial How-to guides Reference Explanation +``` + +```{toctree} +:hidden: +:maxdepth: 1 Release notes ``` 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..7e44824ea 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 @@ -136,13 +138,21 @@ 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 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 -```