coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity
Files
7d453ac5a68df81f5de7d508b72a2719f380f250
orca/.ciagent/CA_MIGRATION_SPEC_v0.9.md
T
Jon Chery 437aab39b4 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---
2026-08-05 16:38:26 +00:00

4.5 KiB
Raw Blame History

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.

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 View Git Blame Copy Permalink