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.