tfgrid/zosstorage
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine default orchestration flow and documentation

Browse Source 
- Document defaults-only configuration, kernel topology override, and deprecated CLI flags in README
- Mark schema doc as deprecated per ADR-0002
- Warn that --topology/--config are ignored; adjust loader/main/context flow
- Refactor orchestrator run() to auto-select mount/apply, reuse state when already provisioned, and serialize topology via Display
- Add Callgraph/FUNCTION_LIST/ADR docs tracking the new behavior
- Derive Eq for Topology to satisfy updated CLI handling
This commit is contained in:
Jan De Landtsheer
2025-10-09 16:51:12 +02:00
parent d374176c0b
commit c8b76a2a3d
11 changed files with 5405 additions and 297 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/adr/0002-defaults-only-no-external-config.md Normal file
View File

@@ -0,0 +1,109 @@
# ADR 0002: Defaults-Only Configuration; Remove External YAML Config
Status
- Accepted
- Date: 2025-10-06
Context
- Running from initramfs at first boot provides no reliable access to an on-disk configuration file (e.g., /etc/zosstorage/config.yaml). An external file cannot be assumed to exist or be mounted.
- The previous design added precedence and merge complexity across file, CLI, and kernel cmdline as documented in [docs/SCHEMA.md](../SCHEMA.md) and implemented via [fn load_and_merge()](../../src/config/loader.rs:1), increasing maintenance burden and risks of drift.
- YAML introduces misconfiguration risk in early boot, adds I/O, and complicates idempotency guarantees without meaningful benefits for the intended minimal-first initializer.
- The desired model is to ship with sane built-in defaults, selected automatically from detected hardware topology; optional kernel cmdline may override only the topology choice for VM/lab scenarios.
Decision
- Remove all dependency on an on-disk configuration file:
- Do not read /etc/zosstorage/config.yaml or any file-based config.
- Deprecate and ignore repository-local config files for runtime (e.g., config/zosstorage.yaml). The example file [config/zosstorage.example.yaml](../../config/zosstorage.example.yaml) remains as historical reference only and may be removed later.
- Deprecate the --config CLI flag in [struct Cli](../../src/cli/args.rs:1). If present, emit a deprecation warning and ignore it.
- Retain operational CLI flags and logging controls for usability:
- --apply, --show, --report PATH, --fstab, --log-level LEVEL, --log-to-file
- Replace the prior file/CLI/kernel precedence with a defaults-only policy plus a single optional kernel cmdline override:
- Recognized key: zosstorage.topology=VALUE
- The key may override only the topology selection; all other settings use built-in defaults.
- Topology defaults and override policy:
- 1 eligible disk:
- Default: btrfs_single
- Allowed cmdline overrides: btrfs_single, bcachefs_single
- 2 eligible disks:
- Default: dual_independent
- Allowed cmdline overrides: dual_independent, ssd_hdd_bcachefs, btrfs_raid1, bcachefs_2copy
- >2 eligible disks:
- Default: btrfs_raid1
- Allowed cmdline overrides: btrfs_raid1, bcachefs_2copy
- Accept both snake_case and hyphenated forms for VALUE; normalize to [enum Topology](../../src/types.rs:1):
- btrfs_single | btrfs-single
- bcachefs_single | bcachefs-single
- dual_independent | dual-independent
- ssd_hdd_bcachefs | ssd-hdd-bcachefs
- btrfs_raid1 | btrfs-raid1
- bcachefs_2copy | bcachefs-2copy
- Kernel cmdline parsing beyond topology is deferred; future extensions for VM workflows may be proposed separately.
Rationale
- Eliminates unreachable configuration paths at first boot and simplifies the mental model.
- Reduces maintenance overhead by removing schema and precedence logic.
- Minimizes early-boot I/O and failure modes while preserving a targeted override for lab/VMs.
- Keeps the tool safe-by-default and fully idempotent without depending on external files.
Consequences
- Documentation:
- Mark [docs/SCHEMA.md](../SCHEMA.md) as deprecated for runtime behavior; retain only as historical reference.
- Update [docs/ARCHITECTURE.md](../ARCHITECTURE.md) and [docs/SPECS.md](../SPECS.md) to reflect defaults-only configuration.
- Update [docs/API.md](../API.md) and [docs/API-SKELETONS.md](../API-SKELETONS.md) where they reference file-based config.
- CLI:
- [struct Cli](../../src/cli/args.rs:1) keeps operational flags; --config becomes a no-op with a deprecation warning.
- Code:
- Replace [fn load_and_merge()](../../src/config/loader.rs:1) with a minimal loader that:
- Builds a [struct Config](../../src/types.rs:1) entirely from baked-in defaults.
- Reads /proc/cmdline to optionally parse zosstorage.topology and normalize to [enum Topology](../../src/types.rs:1).
- Removes YAML parsing, file reads, and merge logic.
- Tests:
- Remove tests that depend on external YAML; add tests for cmdline override normalization and disk-count defaults.
Defaults (authoritative)
- Partitioning:
- GPT only, 1 MiB alignment, BIOS boot 1 MiB first unless UEFI detected via [fn is_efi_boot()](../../src/util/mod.rs:1).
- ESP 512 MiB labeled ZOSBOOT (GPT name: zosboot), data uses GPT name zosdata.
- Filesystems:
- ESP: vfat labeled ZOSBOOT
- Data: label ZOSDATA
- Backend per topology (btrfs for btrfs_*; bcachefs for ssd_hdd_bcachefs and bcachefs_2copy)
- Mount scheme:
- Root-mount all data filesystems under /var/mounts/{UUID}; final subvolume/subdir mounts from the primary data FS to /var/cache/{system,etc,modules,vm-meta}; fstab remains optional.
- Idempotency:
- Unchanged: already-provisioned signals exit success-without-changes via [fn detect_existing_state()](../../src/idempotency/mod.rs:1).
Implementation Plan
1) Introduce a minimal defaults loader in [src/config/loader.rs](../../src/config/loader.rs:1):
- new internal fn parse_topology_from_cmdline() -> Option<Topology>
- new internal fn normalize_topology(s: &str) -> Option<Topology>
- refactor load to construct Config from constants + optional topology override
2) CLI:
- Emit deprecation warning when --config is provided; ignore its value.
3) Docs:
- Add deprecation banner to [docs/SCHEMA.md](../SCHEMA.md).
- Adjust [README.md](../../README.md) to describe defaults and the zosstorage.topology override.
4) Tests:
- Add unit tests for normalization and disk-count policy; remove YAML-based tests.
Backward Compatibility
- External YAML configuration is no longer supported at runtime.
- Kernel cmdline key zosstorage.config= is removed. Only zosstorage.topology remains recognized.
- The JSON report, labels, GPT names, and mount behavior remain unchanged.
Security and Safety
- By eliminating external configuration input, we reduce attack surface and misconfiguration risk in early boot.
- The emptiness and idempotency checks continue to gate destructive operations.
Open Items
- Decide whether to accept additional synonyms (e.g., “bcachefs-raid1”) and map them to existing [enum Topology](../../src/types.rs:1) variants; default is to reject unknown values with a clear error.
- Potential future kernel cmdline keys (e.g., logging level) may be explored via a separate ADR.
Links
- Architecture: [docs/ARCHITECTURE.md](../ARCHITECTURE.md)
- API Index: [docs/API-SKELETONS.md](../API-SKELETONS.md)
- Specs: [docs/SPECS.md](../SPECS.md)
- CLI: [src/cli/args.rs](../../src/cli/args.rs)
- Config loader: [src/config/loader.rs](../../src/config/loader.rs)
- Types: [src/types.rs](../../src/types.rs)
- Util: [src/util/mod.rs](../../src/util/mod.rs)