renich/cl8r: Crystal Cluster Planner & IPAM Compiler: Single Source of Truth bare-metal and cloud infrastructure architect.

Single Source of Truth Bare-Metal Cluster Planner & Scaffolding Compiler

Overview

cl8r (pronounced Clouder) is a Single Source of Truth (SSoT) datacenter compiler and real-time infrastructure introspection engine. From a single declarative specification file (cluster.yaml), cl8r executes bitwise-exact dual-stack IPv4/IPv6 IPAM calculations, resolves physical-to-logical switch port patch matrices, and deterministically compiles deployment manifests for 19 infrastructure, network, storage, and orchestrator backends.

Key Capabilities

Bitwise-Exact Dual-Stack IPAM: Native bitwise IPv4 (UInt32) and IPv6 (UInt128) calculation with zero IP collisions, dynamic DHCP pool slicing, and deterministic static host offset assignment.
Physical Datacenter Reality: Models 42U/48U multi-U rack elevations, Spine/Leaf/OOB switch fabrics, Spine-Leaf ISL port links, cabling patch schedules, LACP bonding, bare-metal border firewall tiers, and out-of-band IPMI/BMC management interfaces.
19 Scaffolding Backends & Verbatim Overlays: Generates NetworkManager keyfiles (0o600), ISC Kea DHCPv4/v6 (with BMC and Option 82 reservations), BIND9 split-horizon DNS, HAProxy/Keepalived, nftables firewalls, WireGuard VPNs, RelaxNG-validated Libvirt domain/pool/secret XML (file, Ceph librbd network, and raw LVM block disks), host storage scripts and systemd .mount units, OpenStack Kolla-Ansible, OKD/OpenShift, Ceph CRUSH rules and client.libvirt keyrings, orthogonal ELK D2 diagrams, Sphinx Technical Memoirs, and executive PDF dossiers, with pure 1:1 in-memory overlays/ composition across generate, validate, and serve.
Sub-Millisecond CLI Introspection (cl8r find): Query IPs, MACs, nodes, BMC controllers, physical disks, storage pools, switches, free/connected ports, racks, IPAM ranges, and L2/L3 reachability across 5 formats (pretty, text, json, yaml, csv).
Declarative Server Builds & Generic Multi-Vendor Pricebooks (cl8r quote, cl8r catalogs): Define server hardware once under hardware-profiles: (cpu: { model, sockets }, ram: { dimms: 12, stick: 32GiB }, disks: [{ count: 4, size: 3.2TB, media: nvme }]) to auto-derive node vcpus, memory-mb, Linux block devices, bay occupancy, and socket-coupled DIMM slot validation. Pair with optional quote.yaml deal terms and switch across your own reusable XDG/FHS vendor pricebooks (~/.config/cl8r/catalogs/<vendor>.yaml, initialized via cl8r catalogs init <vendor>) across USD/MXN and native ODF 1.3 .ods spreadsheets.
360° Relational Web Cockpit (cl8r serve): Built-in zero-dependency HTTP server with interactive D2 topology diagrams, logical services tier graphs, physical rack elevation cards, searchable IPAM matrices, and live multi-vendor /quote?catalog=<vendor>&currency=<USD|MXN> BOM comparison with one-click /quote.ods export.

Quick Start

1. Build from Source

git clone https://gitlab.com/renich/cl8r.git
cd cl8r
shards install
make build
sudo make install      # Installs binary, resources, bash completion, and ~/.gemini/config/skills/cl8r/SKILL.md
make install-skill     # Optional: install/update the Gemini agent skill without root privileges

(Compiled statically typed binary is located at bin/cl8r)

2. Initialize a Cluster Specification

# List all 10 built-in datacenter sizing archetypes
bin/cl8r init --list

# Initialize a new cluster specification
bin/cl8r init -p minimal -o cluster.yaml

3. Validate & Plan

# Validate IPAM and syntax constraints with strict warning checks
bin/cl8r validate -s cluster.yaml

# Render infrastructure plan in plain text (UNIX pipeline-ready)
bin/cl8r plan --format=text cluster.yaml

4. Query Resources with Sub-Millisecond Search

# Inspect host hardware profile and network planes
bin/cl8r find node virt-01 -f cluster.yaml

# Inspect out-of-band BMC/IPMI controller
bin/cl8r find bmc virt-01 -f cluster.yaml

# Inspect switch fabric and query available (uncabled) ports
bin/cl8r find switch tor-01 -f cluster.yaml
bin/cl8r find ports tor-01 --available -f cluster.yaml

# Inspect physical rack capacity and elevation
bin/cl8r find rack rack-01 -f cluster.yaml

5. Manage Vendor Catalogs & Evaluate Multi-Vendor Quotes

# Initialize a starter vendor catalog in ~/.config/cl8r/catalogs/ and list installed catalogs
bin/cl8r catalogs init my-vendor
bin/cl8r catalogs list

# Render hardware BOM, multi-year amortization, OpEx, and compare illustrative example catalogs
bin/cl8r quote -f demo/ceph/cluster.yaml
bin/cl8r quote -f demo/ceph/cluster.yaml -c demo/catalogs/nimbus-cloud.example.yaml
bin/cl8r quote -f demo/ceph/cluster.yaml -c demo/catalogs/edgeworks-micro.example.yaml

# Export native ODF 1.3 OpenDocument spreadsheet with live Calc formulas
bin/cl8r quote -f demo/ceph/cluster.yaml --format=ods -o quote.ods

6. Generate Infrastructure Scaffolding

# Compile all 19 backends into domain-driven directories (auto-composes sibling overlays/ when present)
bin/cl8r generate -b all --clean -t output/ cluster.yaml

7. Launch the Live Web Cockpit

# Launch the embedded web inspector on http://localhost:8080
bin/cl8r serve -f cluster.yaml

Documentation & Reference Guides

Comprehensive specifications, roadmaps, and tutorials are maintained directly in the repository:

User Manual & How-To Guides

Getting Started Guide: Installation, CLI configuration, and basic usage.
Cluster Specification Reference: Complete schema guide for hardware-profiles, networks, switches, racks, nodes, quote.yaml, and generic vendor pricebooks.
Day-2 Operations & Modifications: 11 operational scenarios covering IPAM changes, VLAN re-tagging, hardware RAM/CPU/NVMe re-sizing, and multi-vendor quoting.
Troubleshooting & Remediation: Pre-flight validation, port re-cabling, and drift remediation.
Progressive How-To Manual (Levels 1–9): Step-by-step tutorials from basic clusters to custom compiler backends:

Architecture & Specifications

Technical Specification: Crystal domain model, bitwise IPAM solver, and generator architecture.
Functional Specification: Product requirements and CLI contracts.
Architecture Decision Records (ADRs): Architectural choices, tradeoffs, and rationale.
Problematic Scenarios & Solutions (PROB-01..28): 28 real-world datacenter problematics resolved by cl8r.
Project Roadmap: Phased development milestones and subsystem roadmap.

Pre-Configured Cluster Topologies

Explore 10 ready-to-run cluster blueprints under demo/: libvirt/minimal, libvirt/3-node-cluster, libvirt/3-node-cluster-hyperconverged, openstack/small, openstack/medium, openstack/big, k8s/small, k8s/medium, k8s/big, and ceph.