mirror of
https://github.com/CloudNebulaProject/zmgr.git
synced 2026-04-10 13:10:42 +00:00
49b4847715
Refresh architecture, implementation-state, and gap-analysis docs to reflect all DX changes: validate, completions, JSON output, boot/halt, auto-width tables, confirmation flow, progress output, and partial failure handling. Move resolved gaps to the Resolved section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
# 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.
|