factory/vibe/guidebooks/lab-ecosystem/02-tools.md

vibe > Guidebooks > Lab ecosystem > 02 · tools

02 · tools

Status: ✅ Active Last Updated: 2026-06-23 Upstream: 01 · factory Related: secrets-and-vault.md · storage-and-recovery.md

The tools repo 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.

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); 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

%%{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.

Where to look

• Repo: arcodange-org/tools — each component is a top-level chart/overlay with its own iac/.
• Vault config patterns: hashicorp-vault/iac/modules (e.g. app_roles, app_policy) — referenced by the naming convention.

Cross-references

• Lab ecosystem hub — the whole-lab map.
• 01 · factory — the ArgoCD that deploys this namespace, and the postgres/iac/ roles + user_lookup() that pgbouncer consumes.
• 03 · cms — the public edge protected by CrowdSec (Turnstile → CrowdSec wiring).
• secrets-and-vault.md — full Vault detail: KV/transit/dynamic engines, Gitea OIDC JWT, VSO injection.
• storage-and-recovery.md — Longhorn PVCs these stateful tools mount, and the Vault-unseal step in recovery.