zosstorage/docs/adr/0002-defaults-only-no-external-config.md

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 and implemented via fn load_and_merge(), 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 remains as historical reference only and may be removed later.
• Deprecate the --config CLI flag in struct Cli. 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:
  • 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 as deprecated for runtime behavior; retain only as historical reference.
  • Update docs/ARCHITECTURE.md and docs/SPECS.md to reflect defaults-only configuration.
  • Update docs/API.md and docs/API-SKELETONS.md where they reference file-based config.
• CLI:
  • struct Cli keeps operational flags; --config becomes a no-op with a deprecation warning.
• Code:
  • Replace fn load_and_merge() with a minimal loader that:
    • Builds a struct Config entirely from baked-in defaults.
    • Reads /proc/cmdline to optionally parse zosstorage.topology and normalize to enum Topology.
    • 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().
  • 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().

Implementation Plan

1. Introduce a minimal defaults loader in src/config/loader.rs:
   • new internal fn parse_topology_from_cmdline() -> Option
   • new internal fn normalize_topology(s: &str) -> Option
   • 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.
   • Adjust 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 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
• API Index: docs/API-SKELETONS.md
• Specs: docs/SPECS.md
• CLI: src/cli/args.rs
• Config loader: src/config/loader.rs
• Types: src/types.rs
• Util: src/util/mod.rs