cl8r Logo

cl8r

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

cl8r (pronounced Clouder) is a statically compiled Crystal CLI tool and Single Source of Truth (SSoT) compiler for bare-metal multi-plane infrastructure deployments.

From a single declarative specification file (cluster.yaml), cl8r performs bitwise-exact dual-stack IPv4/IPv6 IPAM math, resolves cross-rack high-availability bonding and switch port patch schedules, and deterministically compiles deployment manifests for 15 infrastructure and orchestration backends.

Why `cl8r` is So Cool

Traditional multi-plane bare-metal deployments (OpenStack Kolla, OpenShift bare-metal, Ceph, Kubernetes) suffer from spreadsheet drift, manual configuration fatigue, and disjointed tooling. Modifying a single VLAN ID or management subnet often requires manually editing dozens of network configuration scripts, DNS zone files, DHCP reservations, and switch trunks.

cl8r solves this with an architectural, compiler-first approach:

Single Source of Truth (SSoT): One file (cluster.yaml) governs everything. Change a subnet, VIP, or switch port once, and every downstream configuration updates in lockstep.
Bitwise-Exact IPAM Math Engine: Native bitwise IPv4 (UInt32) and IPv6 (UInt128) calculation with zero IP collisions, deterministic host offset allocation, and dynamic range slicing.
Full Physical-to-Logical Mapping: Models the complete physical datacenter reality—Dual Upstream ISPs, High-Availability Border Firewalls, 100G MLAG Core Switches, Top-of-Rack (TOR) Leaf Switches, 42U/48U Rack Elevations, server PCIe NICs, transceivers, and cable schedules.
Domain-Driven Scaffolding: Emits an organized, intuitive directory structure separating host configurations (nodes/<hostname>/) from cluster-wide daemons (services/<service>/), visual diagrams (diagrams/), and executive dossiers (reports/).
Malleable Plain-Text External Templates: Sizing archetypes and service templates in ./resources/ are standalone, plain-text files that can be customized on disk without recompiling the binary.
Instant Bi-Directional Introspection: Sub-millisecond CLI query engine (cl8r find) resolving IP from MAC, MAC from IP, partial substring lookups, and switch port allocations.
Executive Technical Memoirs & D2 Graphics: Compiles pure reStructuredText Sphinx documentation trees, print-ready standalone PDF dossiers, and declarative D2 network fabric diagrams.
Zero-Dependency Web Cockpit: Built-in cl8r serve embedded HTTP server providing live-reloading D2 topology views, visual RU rack front elevations, switch patching matrices, and searchable IPAM tables.

Output Backends & Scaffolding Targets

Running cl8r generate --backend=all outputs:

.
├── nodes/                               # Host-specific configurations
│   ├── ctrl-01/
│   │   ├── networkmanager/              # Standard .nmconnection keyfiles (0o600)
│   │   │   ├── eth0.nmconnection
│   │   │   ├── eth1.nmconnection
│   │   │   ├── bond0.nmconnection       # 802.3ad LACP bonding (layer3+4)
│   │   │   ├── bond0.100.nmconnection   # VLAN sub-interfaces + PBR routing rules
│   │   │   └── ...
│   │   ├── nmstate.yaml                 # Declarative host networking state
│   │   └── kickstart.ks                 # Drive-safe RHEL/CentOS Stream autoinstaller
│   └── ...
├── services/                            # Cluster-wide subsystem configurations
│   ├── dhcp/                            # ISC Kea DHCPv4 & DHCPv6 JSON + reservations
│   ├── dns/                             # Split-horizon BIND9 named.conf, zones & FreeIPA
│   ├── pki/                             # Sovereign Root CA & FreeIPA Sub-CA OpenSSL configs
│   ├── ceph/                            # ceph.conf dual-plane MTU 9000 & CRUSH failure map
│   ├── boot/                            # GRUB2 UEFI HTTP boot (grub.cfg) & signed boot.ipxe
│   ├── haproxy/                         # haproxy.cfg, keepalived.conf VRRP & sysctl VIP drop-in
│   ├── chrony/                          # Stratum-2 master & client chrony.conf hierarchy
│   ├── sysctl/                          # Role-tailored /etc/sysctl.d/ kernel optimizations
│   ├── kolla/                           # OpenStack Kolla globals.yml & multinode inventory
│   └── openshift/                       # OKD/OCP install-config.yaml & agent-config.yaml
├── diagrams/                            # Declarative D2 diagram sources
│   ├── topology.d2                      # Logical network planes & VIP routing
│   ├── wiring.d2                        # End-to-end network fabric & server bonding
│   └── racks.d2                         # 42U/48U physical rack front elevations
├── reports/                             # Executive deliverables
│   ├── cluster_memoir.html              # Standalone executive dossier
│   └── cluster_memoir.pdf               # Print-ready Technical Memoirs PDF
└── docs/                                # Full Sphinx documentation project
    ├── conf.py, Makefile, GNUmakefile
    ├── index.rst                        # Technical Memoirs master index
    ├── ip_matrix.rst                    # Dual-stack IP allocation matrix
    ├── vlan_matrix.rst                  # VLAN schedule & plane routing
    ├── cabling_schedule.rst             # Datacenter switch port patch schedule
    ├── rack_elevation.rst               # Physical rack unit allocation
    ├── bill_of_materials.rst            # Hardware procurement BOM
    └── subsystems.rst                   # Cluster daemon blueprints

Dependencies

Core Build Dependencies

Crystal Compiler: >= 1.21.0
Shards Package Manager
GNU Make
System Libraries: openssl-devel, libyaml-devel, pcre2-devel

On Fedora / RHEL:

sudo dnf install crystal shards make openssl-devel libyaml-devel pcre2-devel

Optional Visualization & Documentation Tools

d2 (Declarative diagram compiler): For compiling .d2 files to SVG/PNG graphics (curl -fsSL https://d2lang.com/install.sh | sh -s --).
sphinx-build (python3-sphinx): For building HTML documentation in docs/.
weasyprint or google-chrome / chromium: For compiling standalone executive PDF dossiers (reports/cluster_memoir.pdf).

Quick Start

1. Build `cl8r`

git clone https://gitlab.com/renich/cl8r.git
cd cl8r
shards install
make build

(The statically typed binary is compiled to bin/cl8r)

2. Initialize a Cluster Specification

Generate a standard cluster blueprint:

bin/cl8r init --profile=minimal --output=cluster.yaml

(Available built-in archetypes: minimal, small, medium, large)

3. Validate & Plan

Verify IPAM math, VLAN tagging, rack slots, and switch port constraints:

bin/cl8r validate cluster.yaml
bin/cl8r plan cluster.yaml

4. Query & Search (CLI Introspection)

Query anything in under 5 milliseconds with exact or substring partial search:

# Lookup IP (surfaces host, interface, bound MAC, and IPMI BMC)
bin/cl8r find ip 10.10.10.12

# Lookup MAC (surfaces bound IPv4/IPv6 addresses and network planes)
bin/cl8r find mac 52:54:00:12:34:01

# Substring partial lookups (table or JSON output)
bin/cl8r find ip 10.20
bin/cl8r find mac 12:34 --format=json

# Inspect physical switch port allocation
bin/cl8r find port tor-01 1/1

5. Generate Scaffolding & Technical Memoirs

Compile all 15 backends into domain directories:

bin/cl8r generate --backend=all --target=. cluster.yaml

6. Launch the Local Web Cockpit

Launch the zero-dependency live inspector on http://localhost:3000:

bin/cl8r serve cluster.yaml

Enterprise Demo

A fully configured 3-rack, 6-node enterprise cluster (3 controllers + 3 compute/storage nodes) with Top-of-Rack switches, Core 100G MLAG switches, border firewalls, and dual ISPs is included in demo/:

cd demo
make all        # Validates, plans, generates scaffolds, builds Sphinx HTML, and compiles PDF
make find       # Runs bi-directional IP and MAC search tests
make inspect    # Launches local web cockpit at http://localhost:3000

Running Tests & Quality Verification

# Run unit specs (128 specs, AAA pattern)
crystal spec

# Run comprehensive 5-Tier E2E test matrix (400 tests)
crystal run test/e2e/runner.cr -- --all

# Run Ameba static analysis
bin/ameba

# Validate all documentation with crstlint
find docs/ -name "*.rst" -exec crstlint {} +

Contributing & Changelog

CHANGELOG.rst: Version history, semantic changes, and release milestones.
CONTRIBUTING.rst: Developer guidelines, TDD workflows, and pull request standards.

Support & Sponsorship

If cl8r helps streamline your bare-metal deployments, datacenter planning, or infrastructure automation, consider supporting ongoing independent development: