package

gitlab.com/renich/cl8r

0.2.0 / published Aug 29, 2026 / repository

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

cl8r banner

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

Version 0.1.0 Crystal >= 1.21.0 GitLab CI Passing Specs Passed Ameba Clean License: GPL-3.0-or-later Donate using Liberapay

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 18 infrastructure, network, 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 rack elevations, TOR leaf switches, port cabling patch schedules, LACP bonding, and out-of-band IPMI / BMC management interfaces.
  • 18 Scaffolding Backends: Generates NetworkManager keyfiles (0o600), ISC Kea DHCPv4/v6 (with BMC reservations), BIND9 DNS, HAProxy, nftables firewalls, WireGuard VPNs, Libvirt domain XML, OpenStack Kolla-Ansible, OKD/OpenShift, Ceph CRUSH rules, D2 visual diagrams, and Sphinx documentation.
  • Sub-Millisecond CLI Introspection (cl8r find): Query nodes, BMC controllers, switches, free/connected ports, racks, IPAM ranges, and L2 reachability across 5 formats (pretty, text, json, yaml, csv).
  • 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, and searchable IPAM matrices.

Quick Start

1. Build from Source

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

(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 (cl8r find)

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

# Inspect out-of-band BMC / IPMI controller
bin/cl8r find bmc ctrl-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. Generate Infrastructure Scaffolding

# Compile all 18 backends into domain-driven directories
bin/cl8r generate -b all -t output/ cluster.yaml

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

Architecture & Specifications

Pre-Configured Cluster Topologies (demo/)

  • Explore 10 ready-to-run cluster blueprints under demo/: minimal, small, medium, large, openstack, openshift, ceph, libvirt, libvirt-ceph, and generic.

Repositories & Mirrors

Maintainer & Funding

cl8r is maintained by Rénich Bon Ćirić (renich@evalinux.com) at EVALinux.

If you find cl8r valuable for your infrastructure planning, please consider supporting its ongoing development:

Donate using Liberapay

License

API

  • Cl8r

    Root namespace for the cl8r cluster planner and scaffolding compiler.