Gabriel Radureau
548dacfc44
Two code-grounded tree-docs guidebooks under vibe/guidebooks/, drilling into the lab-ecosystem 02-tools and 03-cms pages (bidirectional): - tools/ : hub + components.md (Vault+VSO, Prometheus, Grafana, CrowdSec, pgbouncer, Redis/KeyDB, Plausible, ClickHouse; pgcat/tool as Tier-2) + secrets-and-vso.md (Vault engines/auth, the app_roles/app_policy modules = the <app> join-key machinery, VSO CRDs, secret-paths inventory). - cms/ : hub + site.md (Nuxt + dual Pages/k3s deploy) + cloudflare.md (zone via OVH->CF, Pages, cloudflared tunnel, Turnstile, R2 state) + zoho-email.md (OAuth, MX/SPF/DKIM/DMARC/BIMI, the 7 aliases). Sibling-repo code linked via full gitea URLs; vibe-internal links bidirectional. Reconciled the cloudflared tunnel token path to kvv2 cms/cloudflared (the chart VaultStaticSecret is kv-v2; the kvv1 tofu reference is a commented-out stub). 6 mermaid diagrams MCP-validated; zero dead links. Lab Cartographer cohort. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
79 lines
5.6 KiB
Markdown
79 lines
5.6 KiB
Markdown
[vibe](../../README.md) > [Guidebooks](../README.md) > [Lab ecosystem](README.md) > **02 · tools**
|
|
|
|
# 02 · tools
|
|
|
|
> **Status:** ✅ Active
|
|
> **Last Updated:** 2026-06-23
|
|
> **Upstream:** [01 · factory](01-factory.md)
|
|
> **Deeper dive:** [Tools guidebook](../tools/README.md) — deploy model, component inventory, and per-component internals
|
|
> **Related:** [secrets-and-vault.md](secrets-and-vault.md) · [storage-and-recovery.md](storage-and-recovery.md)
|
|
|
|
The [`tools` repo](https://gitea.arcodange.lab/arcodange-org/tools) is deployed by factory's ArgoCD into the **`tools` namespace**. It is the platform layer that every app namespace depends on: secrets (Vault + VSO), observability (Prometheus + Grafana), edge security (CrowdSec), database pooling (pgbouncer / pgcat), caching (Redis/KeyDB), and analytics (Plausible + ClickHouse). Each component ships its own Helm chart or Kustomize overlay, and most carry an `iac/` directory of OpenTofu that declares the Vault config (roles, policies, dynamic-secret backends) that wires the component to secrets — see [secrets-and-vault.md](secrets-and-vault.md).
|
|
|
|
## Components in the `tools` namespace
|
|
|
|
| Component | What it does | How declared | How it gets secrets |
|
|
|---|---|---|---|
|
|
| **Vault** | Secrets engine: KV v1 + v2, transit, PostgreSQL **dynamic creds**; auth backends `kubernetes` + Gitea **OIDC/JWT** | Helm chart + `iac/` (Vault config of itself + apps) | Is the source of truth; unsealed at boot (1 key, threshold 1) |
|
|
| **VSO** (Vault Secrets Operator) | Injects Vault secrets into pods via `VaultAuth` + `VaultDynamicSecret` CRDs | Helm chart | Authenticates to Vault via **Kubernetes auth** (per-`<app>` role) |
|
|
| **Prometheus** | Metrics scraping + storage | Helm (community subchart) | — (scrape configs) |
|
|
| **Grafana** | Dashboards at `grafana.arcodange.lab`; datasources Prometheus + ClickHouse | Helm | Admin/datasource creds via VSO from Vault |
|
|
| **CrowdSec** | Behavioural detection + **Traefik bouncer** for the public edge | Helm + `iac/` | **Dynamic secrets** from Vault (VSO) |
|
|
| **pgbouncer** | Connection pooler to the **external** PostgreSQL on `pi2` | Helm | Auth via the per-app `user_lookup()` function (see [01 · factory](01-factory.md)); creds via VSO |
|
|
| **pgcat** | Alternative pooler (optional, **not the default**) | Helm | VSO-injected creds when enabled |
|
|
| **Redis / KeyDB** | In-memory cache; **KeyDB** master/replica (Redis-compatible) | Helm | VSO-injected auth when set |
|
|
| **Plausible** | Privacy-friendly web analytics | **Kustomize** | VSO-injected creds; backed by ClickHouse |
|
|
| **ClickHouse** | OLAP column store backing Plausible | **Kustomize** | VSO-injected creds |
|
|
| **`tool`** | A Helm **library chart** — shared templates/helpers reused by the other charts (not itself deployable) | Helm library chart | n/a |
|
|
|
|
## How tools fit together
|
|
|
|
```mermaid
|
|
%%{init: {'theme': 'base'}}%%
|
|
flowchart TB
|
|
classDef store fill:#7c3aed,stroke:#6d28d9,color:#fff
|
|
classDef proc fill:#059669,stroke:#047857,color:#fff
|
|
classDef edge fill:#d97706,stroke:#b45309,color:#fff
|
|
|
|
VAULT[("Vault<br>single source of truth")]:::store
|
|
VSO["VSO<br>VaultAuth / VaultDynamicSecret"]:::proc
|
|
PG[("External PostgreSQL<br>pi2 · 192.168.1.202")]:::store
|
|
PGB["pgbouncer<br>pooler"]:::proc
|
|
APPS["app pods<br>(webapp, erp, …)"]:::proc
|
|
PROM["Prometheus"]:::proc
|
|
GRAF["Grafana<br>grafana.arcodange.lab"]:::proc
|
|
CH[("ClickHouse")]:::store
|
|
PLA["Plausible"]:::proc
|
|
CS["CrowdSec + Traefik bouncer"]:::edge
|
|
|
|
VAULT --> VSO
|
|
VSO -- "inject secrets" --> APPS
|
|
VSO -- "inject secrets" --> PGB
|
|
VSO -- "dynamic secret" --> CS
|
|
APPS --> PGB --> PG
|
|
PROM --> GRAF
|
|
CH --> GRAF
|
|
PLA --> CH
|
|
```
|
|
|
|
1. **Vault** holds every secret; **VSO** is the operator that delivers them into pods.
|
|
2. VSO **injects** static and dynamic secrets into the app pods, into **pgbouncer**, and supplies **CrowdSec** its dynamic secret.
|
|
3. App pods connect through **pgbouncer**, which pools connections to the **external PostgreSQL** on `pi2` (using the per-app `user_lookup()` function defined in factory's `postgres/iac/`).
|
|
4. **Prometheus** scrapes metrics and **ClickHouse** stores analytics; both are wired as **Grafana** datasources.
|
|
5. **Plausible** writes its analytics into **ClickHouse**.
|
|
6. **CrowdSec** runs as a Traefik bouncer on the public edge, fed dynamic secrets from Vault — the same edge that fronts the CMS in [03 · cms](03-cms.md).
|
|
|
|
## Where to look
|
|
|
|
- Repo: [arcodange-org/tools](https://gitea.arcodange.lab/arcodange-org/tools) — each component is a top-level chart/overlay with its own `iac/`.
|
|
- Vault config patterns: [hashicorp-vault/iac/modules](https://gitea.arcodange.lab/arcodange-org/tools/src/branch/main/hashicorp-vault/iac) (e.g. `app_roles`, `app_policy`) — referenced by the [naming convention](../../../doc/runbooks/new-web-app/conventions.md).
|
|
|
|
## Cross-references
|
|
|
|
- [Tools guidebook](../tools/README.md) — the deeper dive: deploy model (one ArgoCD app → meta-chart → per-component Applications), full component inventory, and per-component internals.
|
|
- [Lab ecosystem hub](README.md) — the whole-lab map.
|
|
- [01 · factory](01-factory.md) — the ArgoCD that deploys this namespace, and the `postgres/iac/` roles + `user_lookup()` that pgbouncer consumes.
|
|
- [03 · cms](03-cms.md) — the public edge protected by **CrowdSec** (Turnstile → CrowdSec wiring).
|
|
- [secrets-and-vault.md](secrets-and-vault.md) — full Vault detail: KV/transit/dynamic engines, Gitea OIDC JWT, VSO injection.
|
|
- [storage-and-recovery.md](storage-and-recovery.md) — Longhorn PVCs these stateful tools mount, and the Vault-unseal step in recovery.
|