[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)
> **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

- [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.