cl8r

This README is the one indexed from the repository at its latest ref, not from the tag for this version.

---

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

• Getting Started Guide: Installation, CLI configuration, and basic usage.
• Cluster Specification Reference: Complete schema guide for networks, switches, racks, nodes, and services.
• Day-2 Operations & Modifications: 10 operational scenarios covering IPAM changes, VLAN re-tagging, and custom DHCP tables.
• 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:
  • Level 1: Simple Converged Cluster
  • Level 2: Networking & LACP Bonding
  • Level 3: Services & Security Policies
  • Level 4: Virtualization & Ceph Storage
  • Level 5: Custom Backend Foundations & /etc/hosts
  • Level 6: Multi-File YAML & Enterprise Ansible
  • Level 7: Terraform, OpenTofu & Cloud-Init
  • Level 8: Prometheus, IPMI BMC & SNMP Monitoring
  • Level 9: Physical Switch Matrix & NOS Compilers

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..26): 26 real-world datacenter problematics resolved by cl8r.
• Project Roadmap: Phased development milestones and subsystem roadmap.

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

• Primary Repository: https://gitlab.com/renich/cl8r
• Official Releases: https://gitlab.com/renich/cl8r/-/releases

---

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:

• Liberapay: https://liberapay.com/Renich

---

License

• Software released under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
• Documentation released under the GNU Free Documentation License v1.3 or later (GFDL-1.3-or-later).