zmgr/docs/ai/architecture.md

Architecture

Overview

zmgr is a single Rust binary that manages illumos zones via flat KDL config files under /etc/zmgr. No daemon, no database — just a CLI that reads configs, calls system commands (zonecfg, zoneadm, dladm), and writes registry entries.

Module Layout

src/
  main.rs        CLI entry point (clap), command dispatch, table formatting
  config.rs      Global config (/etc/zmgr/config.kdl)
  template.rs    Zone templates (/etc/zmgr/templates/*.kdl) — multi-net
  pool.rs        IPAM pools (/etc/zmgr/pools/*.kdl) — range + list modes
  zone.rs        Zone registry (/etc/zmgr/zones/*.kdl) — multi-net
  publisher.rs   IPS publishers (/etc/zmgr/publishers/*.kdl)
  exec.rs        System command wrappers (zonecfg, zoneadm, dladm)
  import.rs      Import existing zones into registry
  validate.rs    Config validation (syntax, integrity, pool sanity)
  kdl_util.rs    KDL document parsing helpers
  error.rs       Error types (miette diagnostics)

Data Flow

Zone Creation (zmgr create <name>)

1. Load global config -> get default template name
2. Load template -> get brand, autoboot, net blocks (each references a pool)
3. For each net: load pool -> allocate next free IP from pool
4. Build zonecfg commands with one add net block per network
5. Step-by-step execution with progress:
   • Create VNICs via dladm create-vnic
   • Configure zone via zonecfg -z <name>
   • Install zone via zoneadm -z <name> install
   • Write zone registry entry (KDL file)
   • If autoboot, zoneadm boot
6. On partial failure: print what succeeded + cleanup commands

Zone Destruction (zmgr destroy <name>)

1. Load zone from registry
2. Require confirmation (type zone name, or --yes)
3. Step-by-step teardown with progress:
   • Halt zone
   • Uninstall zone
   • Delete zone configuration
   • Delete VNICs (one per net)
   • Remove registry entry

Zone Import (zmgr import)

1. zoneadm list -cp -> get system zones
2. Filter out already-registered and bhyve zones
3. zonecfg -z <name> info -> extract config (multiple nets)
4. Match brand -> template, IP -> pool, net names -> template net names
5. Write zone registry entry with current date

Validation (zmgr validate)

1. Parse all KDL files (config, templates, pools, zones)
2. Check referential integrity (template -> pool, config -> template)
3. Check pool sanity (gateway in network, range in network)
4. Check for duplicate IPs across zones
5. Warn on high pool utilization (>90%)

Output Modes

• Human (default): auto-sized tables, key-value detail views
• JSON (--json): structured output for scripting
• Dry-run (-n): shows commands without executing

Dependency Graph

main.rs
  ├── config.rs     <- kdl_util.rs, error.rs
  ├── template.rs   <- kdl_util.rs, error.rs
  ├── pool.rs       <- kdl_util.rs, error.rs
  ├── zone.rs       <- kdl_util.rs, error.rs
  ├── publisher.rs  <- kdl_util.rs, error.rs
  ├── exec.rs       <- error.rs
  ├── import.rs     <- exec.rs, pool.rs, template.rs, zone.rs
  └── validate.rs   <- config.rs, pool.rs, template.rs, zone.rs

Boundary with vm-manager

zmgr manages zone brands (ipkg, nlipkg, etc.) — native illumos zones. vm-manager manages bhyve brand zones — virtual machines. Import logic skips bhyve zones to avoid overlap.