Jakob Rönnbäck
30cb05b0c9
- Add README with project overview, architecture, and roadmap - Set up Rust project with clap, toml, serde, tracing dependencies - Scaffold CLI with 6 commands (init, validate, diff, check, apply, rollback) - Create module structure for config, state, planner, executor, jail, vm, zfs - Create test directory structure for unit/integration/idempotency tests
3.2 KiB
3.2 KiB
Rostyr
A Rust-based configuration management tool for FreeBSD hosts, designed to configure workstations, servers, virtual machines, and jails using an idempotent, test-driven approach.
Overview
Rostyr rewrites and extends styr in Rust, bringing:
- Idempotency - All operations are safe to run repeatedly
- Testing first - Snapshot-based tests for every feature
- Safe rollbacks - ZFS snapshots before every apply
Architecture
| Component | Technology |
|---|---|
| Hosts | FreeBSD only |
| Service Isolation | FreeBSD Jails (primary) |
| Linux VMs | bhyve hypervisor |
| Filesystem | ZFS with snapshots |
| Config Format | TOML |
CLI Commands
rostyr init <hostname> # Scaffold new host config
rostyr validate # Validate all TOML configs
rostyr diff [--host H] # Show pending changes (dry-run)
rostyr check [--host H] # Detect current system state
rostyr apply [--host H] # Apply changes (creates ZFS snapshot first)
rostyr rollback # Revert to last ZFS snapshot
Idempotency Strategy
- Detect current state (jails, VMs, ZFS, users, packages)
- Diff desired vs actual state
- Plan minimal changes needed
- Execute only when state differs
- Snapshot ZFS before any apply
Testing Strategy
- Unit tests: Config parsing, state detection, diff logic
- Integration tests: CLI commands against isolated test VMs
- Idempotency tests: Run apply twice, verify no changes on second run (snapshot comparison)
- VMs for testing: All tests run in isolated bhyve VMs before production deployment
Project Structure
rostyr/
├── src/
│ ├── main.rs
│ ├── cli.rs # CLI argument handling
│ ├── config/ # TOML parsing & validation
│ ├── state/ # System state detection
│ ├── planner/ # Diff & idempotency logic
│ ├── executor/ # Command execution
│ ├── jail/ # Jail management
│ ├── vm/ # bhyve VM management
│ ├── zfs/ # ZFS snapshot/rollback
│ └── commands/ # init, validate, diff, apply, rollback
├── configs/
│ ├── hosts/ # Host TOML files
│ ├── users/ # User TOML files
│ └── services/ # Service definitions
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # CLI tests
│ └── idempotency/ # Snapshot-based tests
└── Cargo.toml
Phased Roadmap
Phase 1 - Core Foundation
- Project scaffolding (Rust, CLI framework)
- Config parsing (TOML)
- Basic state detection (host info, ZFS)
- init, validate commands
Phase 2 - Idempotent Apply
- Diff/planner logic
- Apply command with ZFS snapshot
- Rollback command
- check command
Phase 3 - Jails
- Jail creation/management
- Basic service jail templates
- User management inside jails
Phase 4 - bhyve VMs
- VM lifecycle management
- Linux VM templates
- Service deployment to VMs
Phase 5+ - Services
- Individual service implementations (from styr)
- Full port of styr functionality
License
Unlicense - see LICENSE file