From 8370a515d027417cabf8c4c58694617f02531fb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Canna=C3=B2?= Date: Sun, 9 Aug 2026 18:14:01 +0700 Subject: [PATCH] docs: scope the architecture diagram to the operator path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Architecture at a glance" diagram sits immediately below a table advertising three Helm charts, so it reads as if it explains all of them. It does not: it shows only the operator path — ProxySQLCluster reconciling into a StatefulSet/Services/Secrets/PDB, and ProxySQLConfig pushing SQL to the admin port. Neither standalone chart has a CRD, a controller, or a SQL push anywhere in it. Retitled the section and added two clarifications underneath: - the diagram is the operator path only; the standalone charts render proxysql.cnf from their Helm values into a ConfigMap (charts/proxysql) or a Secret (charts/proxysql-cluster), which ProxySQL reads on first start - the SQL push targets every replica rather than one, with a link to the existing rationale in docs/architecture.md Everything asserted here was checked against the code rather than the prose: charts/proxysql/templates/configmap.yaml is a ConfigMap carrying proxysql.cnf; charts/proxysql-cluster/templates/secret-cnf.yaml is a Secret carrying the same key (its own header explains the difference — the rendered cnf embeds the admin/radmin/ monitor passwords); neither standalone chart passes --reload, unlike the operator's statefulset builder, so "read on first start" holds for them; and proxysqlcluster_controller_test.go asserts that replicas=3 populates proxysql_servers, confirming cluster sync is enabled as a backstop while the operator still writes to all. Reported by a reader who hit exactly this ambiguity. Co-Authored-By: Claude Opus 5 --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f977ff..b2597a0 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ operator's CR + a ProxySQL CR pair, get a working stack: - **PostgreSQL family:** [CloudNativePG](./examples/postgresql/cloudnativepg/), [Crunchy PGO](./examples/postgresql/crunchy-pgo/) - **Loadgen:** sysbench (MySQL) + pgbench (PostgreSQL) under [`examples/loadgen/`](./examples/loadgen/) -## Architecture at a glance +## Architecture at a glance — the operator path ``` ┌─────────────────────────────────────────────────────────────────────┐ @@ -91,8 +91,21 @@ operator's CR + a ProxySQL CR pair, get a working stack: └──────────────────────────┘ ``` +Two things the picture does not say out loud: + +- **This is the operator path only** (`charts/proxysql-operator`). The two standalone + charts skip all of it — no CRDs, no controller, and no `ProxySQLConfig`. They render + `proxysql.cnf` from their Helm values into a `ConfigMap` (`charts/proxysql`) or a + `Secret` (`charts/proxysql-cluster`), which ProxySQL reads on first start. +- **The SQL push goes to every replica, not one.** The operator writes to each pod's + admin port directly instead of writing once and letting ProxySQL's own cluster sync + propagate — see [why][why-write-to-all]. Cluster sync is still enabled as a backstop + when `replicas > 1`. + Full design notes in [`docs/architecture.md`](./docs/architecture.md). +[why-write-to-all]: ./docs/architecture.md#why-write-to-all-instead-of-letting-proxysql-cluster-sync-handle-it + ## Quick start ```bash