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
105 lines
3.2 KiB
Markdown
105 lines
3.2 KiB
Markdown
# 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](https://gitea.rowanbrook.net/jakob/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
|
|
|
|
1. **Detect** current state (jails, VMs, ZFS, users, packages)
|
|
2. **Diff** desired vs actual state
|
|
3. **Plan** minimal changes needed
|
|
4. **Execute** only when state differs
|
|
5. **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
|