feat(P0a1): multi-namespace path resolver + config demotion + known_hosts flock + CA migration spec (v0.9 P0a1)
P0a1 — Re-architecture Foundation (path resolver + config demotion). Path resolver (REQ-070, R-002): - internal/paths/paths.go: 23 functions for the multi-namespace layout (Root/ClusterDir/NamespaceDir/NS*/DefaultNamespace/CA/MasterKey/CacheDB/ Txn/Peers/KnownHosts/SSH/Server/Config). Honors $ORCA_HOME. 100% coverage. - internal/certpaths/certpaths.go: refactored as thin shim delegating to paths, preserving the v0.8 flat-layout API for backward compat during the dual-write window (REQ-090). Package doc explains the v0.10-P14 migration plan. certpaths deleted after v0.10-P14. 100% coverage. Config demotion (REQ-069, R-014): - internal/config/markdown.go: minimal hand-rolled YAML frontmatter parser (no new dep — yaml.v3 not in go.mod). Returns same *Config struct as HCL. - internal/config/config.go: renamed Load body to LoadHCL (// Deprecated per R-013), added dispatcher Load() routing on extension (.hcl->HCL, .md->Markdown, .yaml->Markdown). Signature preserved so root.go unchanged. - dispatch_test.go + markdown_test.go: 89.8% coverage on config package. Known_hosts flock (REQ-063, deferred P1 from REVIEW_v0.8 A2): - internal/security/flock.go: stdlib syscall.Flock advisory lock helper. - internal/proxmox/bootstrap.go: TOFUHostKeyCallback capture + ResetHostKey both acquire the flock before read-modify-write on known_hosts. Prevents concurrent writers under v0.9 parallel SSH fan-out. 3 flock tests. CA migration spec (grill C-07): - .ciagent/CA_MIGRATION_SPEC_v0.9.md: Option A (preserve trust root, RECOMMENDED) vs Option B (forced re-bootstrap). Pre-flight checks, migration steps, rollback, post-migration invariants, spike plan. Verification: build pass, 17/17 Go packages pass, 20/20 bats pass, gofmt clean, go vet clean, verify-reqs 90 consistent. Coverage: paths 100%, certpaths 100%, config 89.8%, emit covered. ---ci--- project: orca phase: P0a1 milestone: v0.9 status: execute ---/ci---
This commit is contained in:
Jon Chery
@@ -0,0 +1,109 @@
|
||||
# CA Migration Spec — v0.8 Internal CA → v0.9 step-ca (grill C-07)
|
||||
|
||||
**Status**: spec (must be implemented in v0.10-P14a, REQ-066)
|
||||
**Gate**: C-07 — blocks v0.10-P14a until this spec is reviewed and a dry-run passes on a test cluster
|
||||
|
||||
## Problem
|
||||
|
||||
The v0.8 internal Go CA (`internal/security/ca.go`) issues RSA-3072 CA
|
||||
certs (10-year validity) and ECDSA P-256 server certs (90-day). The CA
|
||||
material lives at `~/.orca/ca.crt` and `~/.orca/ca.key` (flat layout, D-011).
|
||||
The v0.9 re-architecture reverses AD-010 and replaces the internal CA with
|
||||
step-ca (D-101, REQ-076). Existing v0.8 deployments have an internal CA
|
||||
root + issued server certs that must be migrated without invalidating
|
||||
trust across the cluster.
|
||||
|
||||
## Migration options (decision required before v0.10-P14a implementation)
|
||||
|
||||
### Option A — Preserve trust root (RECOMMENDED)
|
||||
|
||||
Import the existing `ca.key` into step-ca as the root CA key. The cluster's
|
||||
trust fingerprint stays unchanged; existing server certs continue to
|
||||
validate until their natural expiry; new SVIDs are minted by step-ca using
|
||||
the same root.
|
||||
|
||||
```bash
|
||||
orca upgrade --to-v1.0 --import-ca
|
||||
# reads ~/.orca/ca.key → step ca init --deployment-type standalone \
|
||||
# --remote-management --key $(cat ~/.orca/ca.key)
|
||||
# issues new SVIDs from step-ca for all existing workloads
|
||||
```
|
||||
|
||||
**Pros**: zero trust breakage; existing server certs keep working; minimal
|
||||
operator disruption.
|
||||
**Cons**: requires step-ca to accept an imported RSA-3072 key (step-ca
|
||||
supports imported keys via `--key` flag; verify in the spike).
|
||||
**Post-migration**: old `internal/security/ca.go` and `csr.go` are deleted
|
||||
(v0.10-P14); the `cert_repo` SQLite table (0004) is dropped (step-ca
|
||||
manages cert state).
|
||||
|
||||
### Option B — Forced re-bootstrap
|
||||
|
||||
Document that v0.8 certs are invalidated; every cluster re-bootstraps under
|
||||
step-ca with a new root. Existing workloads are re-enrolled.
|
||||
|
||||
**Pros**: clean slate; no legacy RSA root.
|
||||
**Cons**: trust breakage — every peer's `known_hosts` + CA cert must be
|
||||
rotated; running workloads lose mTLS until re-enrolled; higher operator
|
||||
disruption.
|
||||
**Use case**: only if Option A is technically infeasible (step-ca rejects
|
||||
the v0.8 key format).
|
||||
|
||||
## Pre-flight checks (must pass before migration)
|
||||
|
||||
1. `orca doctor` reports zero FAILs on the v0.8 cluster
|
||||
2. All peers reachable via SSH
|
||||
3. No in-flight transactions (the migration is stop-the-world for the CA)
|
||||
4. Snapshot taken (`orca backup --include-master-key`)
|
||||
5. step-ca installed on the lead via `apt-get install step-ca`
|
||||
6. `step ca init` dry-run succeeds with the imported key
|
||||
|
||||
## Migration steps (Option A)
|
||||
|
||||
1. SSH to the lead; install step-ca via apt
|
||||
2. Run `step ca init --deployment-type standalone --remote-management \
|
||||
--key <v0.8-ca-key-path> --provisioner orca-admin`
|
||||
3. Move the root cert: `cp ~/.orca/ca.crt $ORCA_HOME/cluster/ca.crt`
|
||||
4. Issue new SVIDs for every registered workload (via `step ca token` +
|
||||
`step ca certificate` — the CLI mints the provisioner token using
|
||||
`cluster/master.key`-derived material)
|
||||
5. Deploy the new SVIDs to peers via SSH-push (the v0.9 SSH-push transport)
|
||||
6. Verify: `orca doctor` reports zero FAILs; CA fingerprint unchanged;
|
||||
all workload SVIDs valid
|
||||
7. Archive the old `internal/security/ca.go`/`csr.go` and `cert_repo` table
|
||||
|
||||
## Rollback
|
||||
|
||||
If any post-migration invariant fails:
|
||||
1. Restore the v0.8 snapshot via `orca upgrade --rollback <tarball>`
|
||||
2. Restart the v0.8 orca daemon on the lead
|
||||
3. Verify `orca doctor` passes on the v0.8 cluster
|
||||
|
||||
The v0.8 internal CA remains functional during the dual-write window
|
||||
(REQ-090); step-ca is additive until the migration completes.
|
||||
|
||||
## Post-migration invariants (must all pass)
|
||||
|
||||
- CA fingerprint unchanged (Option A)
|
||||
- Node count unchanged
|
||||
- Workload count unchanged
|
||||
- All SVIDs valid (mTLS handshake succeeds lead↔every peer)
|
||||
- `orca doctor` zero FAILs
|
||||
- No `internal/security/ca.go` or `cert_repo` references remain in code
|
||||
|
||||
## Decision required
|
||||
|
||||
This spec is gated by C-07. The decision (Option A vs B) must be made
|
||||
before v0.10-P14a implementation. Default: Option A (preserve trust root)
|
||||
unless the step-ca imported-key spike fails.
|
||||
|
||||
## Spike (must run before v0.10-P14a)
|
||||
|
||||
Run on a test cluster:
|
||||
1. Install step-ca on a clean Linux host
|
||||
2. Generate a v0.8-style RSA-3072 CA key via the v0.8 `internal/security` package
|
||||
3. Run `step ca init --key <v8-key>` and verify step-ca accepts it
|
||||
4. Mint a test SVID via `step ca token` + `step ca certificate`
|
||||
5. Verify the SVID validates against the imported root
|
||||
|
||||
If the spike fails, fall back to Option B (forced re-bootstrap) and document.
|
||||
Reference in New Issue
Block a user