add 1st draft for charm architecture docs by Thanhphan1147 · Pull Request #534 · canonical/haproxy-operator

Thanhphan1147 · 2026-06-04T15:10:17Z

What this PR does

Why we need it

Checklist

I followed the contributing guide
I added or updated the documentation (if applicable)
I updated docs/changelog.md with user-relevant changes
I added a change artifact for user-relevant changes in docs/release-notes/artifacts. If no change artifact is necessary, I tagged the PR with the label no-release-note.
I used AI to assist with preparing this PR
I added or updated tests as needed (unit and integration)
If integration test modules are used: I updated the workflow configuration
(e.g., in .github/workflows/integration_tests.yaml, ensure the modules list is correct)
If this PR involves a Grafana dashboard: I added a screenshot of the dashboard
If this PR involves Terraform: terraform fmt passes and tflint reports no errors

erinecon

Thanks so much for drafting this Explanation page 🎉 some initial thoughts from me

erinecon

Thanks so much for adding more information to this page! This round of comments contains nits + questions about the ddos-configurator

erinecon · 2026-06-08T13:48:21Z

+1. `haproxy`: A machine charm managing HAProxy. See the [haproxy README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-operator) for more information.
+2. `haproxy-spoe-auth-operator`: A machine charm deploying an SPOE agent that serves as an authentication proxy. See the [haproxy-spoe-auth-operator README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-spoe-auth-operator) for more information.
+3. `haproxy-route-policy-operator`: A machine charm deploying the `haproxy-route-policy` application for controlling the data from different `haproxy-route` relations. See the [haproxy-route-policy-operator README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-route-policy-operator) for more information.


Suggested change

1. `haproxy`: A machine charm managing HAProxy. See the [haproxy README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-operator) for more information.

2. `haproxy-spoe-auth-operator`: A machine charm deploying an SPOE agent that serves as an authentication proxy. See the [haproxy-spoe-auth-operator README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-spoe-auth-operator) for more information.

3. `haproxy-route-policy-operator`: A machine charm deploying the `haproxy-route-policy` application for controlling the data from different `haproxy-route` relations. See the [haproxy-route-policy-operator README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-route-policy-operator) for more information.

1. `haproxy`: A machine charm managing HAProxy. See the [`haproxy` README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-operator) for more information.

2. `haproxy-spoe-auth-operator`: A machine charm deploying an SPOE agent that serves as an authentication proxy. See the [`haproxy-spoe-auth-operator` README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-spoe-auth-operator) for more information.

3. `haproxy-route-policy-operator`: A machine charm deploying the `haproxy-route-policy` application for controlling the data from different `haproxy-route` relations. See the [`haproxy-route-policy-operator` README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-route-policy-operator) for more information.

Nits for code-formatting the (CLI) charm names

erinecon · 2026-06-08T13:51:30Z

+1. `haproxy-spoe-auth-snap`: A snap of the SPOE agent made for the haproxy-spoe-auth-operator charm. See the [haproxy-spoe-auth-snap README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-spoe-auth-snap) for more information.
+2. `haproxy-route-policy-snap`: A snap of the `haproxy-route-policy` app made for the `haproxy-route-policy-operator` charm. See the [haproxy-route-policy-snap README](https://github.com/canonical/haproxy-operator/tree/main/haproxy-route-policy) for more information.
+
+## Architecture diagram


I would either remove this header entirely or update to something like

Suggested change

## Architecture diagram

## High-level overview of deployment

erinecon · 2026-06-08T13:54:29Z

+    Container_Boundary(ddos, "ddos-configurator") {
+        Component(ddos, "ddos-configurator charm")
+    }


Any relations we can show between the ddos-configurator and any of the other charms? If they're optional, then we can explicitly state that in the text.

erinecon · 2026-06-08T13:57:34Z

+The `haproxy` charm is the central component, responsible for configuring and running the HAProxy reverse proxy on machine. It receives routing information from related applications via `haproxy-route` (HTTP) and `haproxy-route-tcp` (TCP) relations and generates the appropriate HAProxy configuration.
+
+The `haproxy` charm can be deployed with the `haproxy-spoe-auth-operator` charm to add an authentication layer via an SPOE (Stream Processing Offload Engine) agent packaged in `haproxy-spoe-auth-snap`. HAProxy delegates authentication decisions to this agent which is integrated with an OIDC (OpenID Connect) provider charm.
+
+The `haproxy` charm can also be deployed with the `haproxy-route-policy-operator` charm to control which backends are permitted to be routed through `haproxy-route` relations. The workload of the `haproxy-route-policy-operator` charm is a Django application packaged as a snap. It evaluates incoming requests against configured rules and accepts or rejects them accordingly. It's deployed together with a PostgreSQL database.


Should we include information about the ddos-configurator here?

erinecon · 2026-06-08T13:58:05Z

+C4Component
+title Component diagram for HAProxy Charm
+
+Container_Boundary(haproxy, "HAProxy charm monorepo") {


Suggested change

Container_Boundary(haproxy, "HAProxy charm monorepo") {

Container_Boundary(haproxy, "HAProxy deployment") {

erinecon · 2026-06-08T13:59:36Z

+
+The `haproxy` charm is the central component, responsible for configuring and running the HAProxy reverse proxy on machine. It receives routing information from related applications via `haproxy-route` (HTTP) and `haproxy-route-tcp` (TCP) relations and generates the appropriate HAProxy configuration.
+
+The `haproxy` charm can be deployed with the `haproxy-spoe-auth-operator` charm to add an authentication layer via an SPOE (Stream Processing Offload Engine) agent packaged in `haproxy-spoe-auth-snap`. HAProxy delegates authentication decisions to this agent which is integrated with an OIDC (OpenID Connect) provider charm.


Suggested change

The `haproxy` charm can be deployed with the `haproxy-spoe-auth-operator` charm to add an authentication layer via an SPOE (Stream Processing Offload Engine) agent packaged in `haproxy-spoe-auth-snap`. HAProxy delegates authentication decisions to this agent which is integrated with an OIDC (OpenID Connect) provider charm.

The `haproxy` charm can be deployed with the `haproxy-spoe-auth-operator` charm to add an authentication layer via a Stream Processing Offload Engine (SPOE) agent packaged in `haproxy-spoe-auth-snap`. HAProxy delegates authentication decisions to this agent which is integrated with an OpenID Connect (OIDC) provider charm.

nitpick

erinecon · 2026-06-08T14:00:19Z

+## Integrations
+
+See the Integrations section on each of the component's Charmhub page for more details:
+
+1. [Integrations for haproxy-operator](https://charmhub.io/haproxy/integrations?channel=2.8/edge)
+2. [Integrations for haproxy-spoe-auth-operator](https://charmhub.io/haproxy-spoe-auth/integrations?channel=latest/edge)
+3. [Integrations for haproxy-route-policy-operator](https://charmhub.io/haproxy-route-policy/integrations?channel=latest/edge)


Should this section also link to the ddos-configurator charm's integrations tab?

erinecon · 2026-06-08T14:05:41Z

+## Integrations
+
+See the Integrations section on each of the component's Charmhub page for more details:


I feel like this section could be enhanced. The basic question: What do we want readers to know about the available integrations?

Some additional questions: Did we make any explicit design choices or enforce any opinions with the integrations that we want to highlight here (e.g., did we design the integrations so that they all feed back into haproxy)? Are any of the integrations required for a basic deployment? What integrations are required when the user wants DDOS protection, or OIDC?

erinecon · 2026-06-08T14:10:35Z

+Rel(charm, spoe_auth, "SPOE protocol", "Authentication offload")
+Rel(haproxy_route_policy_charm, charm, "haproxy-route-policy", "Route approval")
+Rel(spoe_auth, spoe_auth_snap, "Manages")
+Rel(haproxy_route_policy_charm, haproxy_route_policy_snap, "Manages")


Suggested change

Rel(charm, spoe_auth, "SPOE protocol", "Authentication offload")

Rel(haproxy_route_policy_charm, charm, "haproxy-route-policy", "Route approval")

Rel(spoe_auth, spoe_auth_snap, "Manages")

Rel(haproxy_route_policy_charm, haproxy_route_policy_snap, "Manages")

Rel(charm, spoe_auth, "SPOE protocol", "Authentication offload")

Rel(haproxy_route_policy_charm, charm, "haproxy-route-policy", "Route approval")

Rel(spoe_auth, spoe_auth_snap, "Manages")

Rel(haproxy_route_policy_charm, haproxy_route_policy_snap, "Manages")

UpdateRelStyle(haproxy_route_policy_charm, charm, $offsetY="-60", $offsetX="-130")

UpdateRelStyle(charm, spoe_auth, $offsetY="10", $offsetX="-50")

UpdateRelStyle(spoe_auth, spoe_auth_snap, $offsetX="10")

UpdateRelStyle(haproxy_route_policy_charm, haproxy_route_policy_snap, $offsetX="10")

Nitpick, to move the relation labels around so they're easier to read

add 1st draft for charm architecture docs

5892aaa

Thanhphan1147 requested a review from erinecon June 4, 2026 15:10

Thanhphan1147 added documentation Improvements or additions to documentation no-release-note This PR does not require a change artifact labels Jun 4, 2026

github-actions Bot added Libraries: OK Libraries: Out of sync and removed Libraries: OK Libraries: Out of sync labels Jun 4, 2026

erinecon reviewed Jun 4, 2026

View reviewed changes

update project architecture docs

d09ad38

github-actions Bot added Libraries: OK Libraries: Out of sync and removed Libraries: Out of sync Libraries: OK labels Jun 5, 2026

erinecon reviewed Jun 8, 2026

View reviewed changes

	Container_Boundary(haproxy, "HAProxy charm monorepo") {
	Container_Boundary(haproxy, "HAProxy deployment") {


		The `haproxy` charm is the central component, responsible for configuring and running the HAProxy reverse proxy on machine. It receives routing information from related applications via `haproxy-route` (HTTP) and `haproxy-route-tcp` (TCP) relations and generates the appropriate HAProxy configuration.

		The `haproxy` charm can be deployed with the `haproxy-spoe-auth-operator` charm to add an authentication layer via an SPOE (Stream Processing Offload Engine) agent packaged in `haproxy-spoe-auth-snap`. HAProxy delegates authentication decisions to this agent which is integrated with an OIDC (OpenID Connect) provider charm.

		## Integrations

		See the Integrations section on each of the component's Charmhub page for more details:

Conversation

Thanhphan1147 commented Jun 4, 2026

What this PR does

Why we need it

Checklist

Uh oh!

erinecon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

erinecon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants