This project demonstrates a zero-toil observability architecture for dynamic infrastructure fleets using OpenVox (Puppet), VictoriaMetrics, Vmagent, Caddy, and Grafana — all orchestrated through Docker Compose.
The core idea is that every node should self-register, self-classify, and self-instrument from the moment it boots, with no manual configuration file updates required.
Five implementation patterns underpin the architecture:
- CSR Classification — nodes embed their role (
pp_role) as a certificate extension at provisioning time, creating a tamper-proof, agent-immutable identity that drives all downstream automation. - Pure Data Roles — the Puppet site manifest contains zero classification logic; a single
lookup('classes', Array[String], 'unique').includecall delegates all node classification to Hiera YAML role files. - Auto-Discovery via Exported Resources — each node publishes its own scrape target to OpenVoxDB using Puppet exported resources; the metrics scraper collects them dynamically, eliminating static target lists entirely.
- Zero-Trust mTLS — Caddy acts as a sidecar reverse proxy in front of every exporter, enforcing mutual TLS authenticated by the existing Puppet CA so only authorised scrapers can reach metrics endpoints.
- Layered Observability — a
profile::baseclass applies node-exporter to every host automatically, while Hiera role data layers on workload-specific exporters (e.g. Apache, PostgreSQL) only where needed.
Use rv to install ruby. E.g.:
rv ruby install 3.3.10Use the following to install r10k:
cd openvox-code
gem cleanup
bundle config set path vendor/bundle
bundle installUse the following to install Puppet module dependencies:
cd openvox-code && bundle exec r10k puppetfile installUse the following docker command:
docker compose up -dUse the following commands to teardown:
docker compose down --volumes
rm -rf openvoxserver-ca openvoxserver-sslThis project is based on the excellent OpenVox community project and crafty. 100% thanks to them and all the contributors of the VoxPupuli community! Their work has been instrumental in helping me understand the Puppet ecosystem and how to make it work for me.