5. Migration Path
This section defines the migration path from the interim architecture to the target architecture defined in RFC-SECOPS-0001. The migration proceeds through three phases, each corresponding to infrastructure milestones.
5.1 Migration Phases Overview
| Phase | Name | Secret Store | Consumption Mechanism | Runtime |
|---|---|---|---|---|
| 0 | Interim (this RFC) | AWS Secrets Manager | AWS SDK via Secret Config Module | On-premises virtual machines |
| 1 | Kubernetes Adoption | AWS Secrets Manager | External Secrets Operator (ESO) | Kubernetes pods |
| 2 | Target State | HashiCorp Vault | External Secrets Operator (ESO) | Kubernetes pods |
Each phase transition has explicit prerequisites and completion criteria. No phase transition MAY occur until all prerequisites are satisfied.
5.2 Phase 0 — Current State (Secrets Manager + SDK)
This is the architecture defined by this RFC.
5.2.1 Characteristics
| Aspect | Value |
|---|---|
| Secret Store | AWS Secrets Manager |
| Consumption | AWS SDK via centralized Secret Config Module |
| Runtime | On-premises virtual machines |
| Population | Manual (AWS Console/CLI) |
| Rotation | Manual |
| Inventory | secrets-inventory.yaml in Git |
5.2.2 Exit Criteria
Phase 0 is complete when all of the following conditions are met:
| Criterion | Description |
|---|---|
| All secrets centralized | No application secret resides solely in .env files or environment variables |
| Inventory complete | secrets-inventory.yaml reflects all secrets in Secrets Manager |
| Naming conventions applied | All secret names follow platform-data/ and platform-config/ naming patterns |
| SDK centralized | Each application accesses secrets through a single module |
5.3 Phase 1 — Kubernetes Adoption (Secrets Manager + ESO)
Phase 1 begins when Kubernetes becomes available and applications migrate from on-premises infrastructure to Kubernetes pods.
5.3.1 Prerequisites
| Prerequisite | Description |
|---|---|
| Kubernetes cluster | Operational cluster (EKS or self-hosted) |
| External Secrets Operator | ESO deployed and configured |
| Secrets Manager SecretStore | ESO SecretStore resource configured for AWS Secrets Manager |
| Application containerization | Applications migrated from VMs and packaged as container images |
5.3.2 Migration Actions
| Action | Description |
|---|---|
| Deploy ESO SecretStore | Configure ESO to connect to AWS Secrets Manager |
| Create ExternalSecret resources | One per secret, mapping Secrets Manager secret names to Kubernetes Secrets |
| Replace Secret Config Module | Remove AWS SDK calls; consume Kubernetes Secrets (env vars or volume mounts) |
| Retire IAM credentials | Replace per-server IAM users with IRSA or pod identity |
5.3.3 What Changes
| Aspect | Phase 0 | Phase 1 |
|---|---|---|
| Secret retrieval | AWS SDK call at runtime | Kubernetes Secret mounted or injected |
| Authentication | IAM credentials | IRSA / pod identity |
| Application dependency | AWS SDK | None (secrets appear as env vars or files) |
| Secret refresh | Application restart | ESO refresh interval |
5.3.4 What Does Not Change
| Aspect | Reason |
|---|---|
| Secret store (Secrets Manager) | Vault is not yet available |
| Secret names | Naming convention is store-agnostic |
| Secret values | No re-creation needed; same values in same store |
| Inventory manifest | Same metadata; consumption mechanism column updates |
5.3.5 Completion Criteria
| Criterion | Description |
|---|---|
| All applications on Kubernetes | No application retrieves secrets via AWS SDK |
| All ExternalSecrets operational | ESO syncs all secrets from Secrets Manager to Kubernetes |
| IAM credentials retired | No long-lived IAM credentials on servers |
| Secret Config Modules removed | AWS SDK no longer a dependency for secret access |
5.4 Phase 2 — Target State (Vault + ESO)
Phase 2 begins when HashiCorp Vault becomes available. This phase implements the architecture defined in RFC-SECOPS-0001.
5.4.1 Prerequisites
| Prerequisite | Description |
|---|---|
| Phase 1 complete | All applications consume secrets via ESO + Kubernetes Secrets |
| HashiCorp Vault | Deployed, initialized, unsealed, and configured |
| Vault SecretStore | ESO SecretStore resource configured for Vault |
| Vault policies | Access policies defined per RFC-SECOPS-0001 |
5.4.2 Migration Actions
| Action | Description |
|---|---|
| Copy secrets to Vault | Migrate all secret values from Secrets Manager to Vault using the same names |
| Switch ESO SecretStore | Point ExternalSecret resources from Secrets Manager SecretStore to Vault SecretStore |
| Configure Vault paths | Secrets Manager names already match Vault path conventions; no remapping needed |
| Enable Vault features | Rotation automation, audit logging, dynamic secrets (as defined in SECOPS-0001) |
| Decommission Secrets Manager | Remove secrets from Secrets Manager after migration validation |
5.4.3 What Changes
| Aspect | Phase 1 | Phase 2 |
|---|---|---|
| Secret store | AWS Secrets Manager | HashiCorp Vault |
| ESO backend | Secrets Manager SecretStore | Vault SecretStore |
| Rotation | Manual | Automated (Vault) |
| Audit | AWS CloudTrail | Vault audit log |
| Policy | AWS IAM policies / resource-based policies | Vault policies |
5.4.4 What Does Not Change
| Aspect | Reason |
|---|---|
| Application code | Applications consume Kubernetes Secrets; backend is transparent |
| Secret names | Naming convention carries forward from Phase 0 |
| ExternalSecret resources | Only the SecretStore reference changes |
| Inventory manifest | Metadata remains valid; store column updates |
5.4.5 Completion Criteria
| Criterion | Description |
|---|---|
| All secrets in Vault | Every platform secret resides in Vault |
| ESO points to Vault | All ExternalSecret resources reference the Vault SecretStore |
| Secrets Manager decommissioned | No secrets remain in AWS Secrets Manager |
| RFC-SECOPS-0001 operational | Full Vault-first architecture is active |
| RFC-SECOPS-0002 superseded | This RFC transitions to Superseded status |
5.5 Naming Convention Continuity
The naming convention established in this RFC persists across all three phases:
| Phase | Store | Secret Name / Path |
|---|---|---|
| 0 | Secrets Manager | platform-data/postgres/my-app |
| 1 | Secrets Manager (via ESO) | platform-data/postgres/my-app |
| 2 | Vault | platform-data/postgres/my-app |
The segment structure is identical across all phases. AWS Secrets Manager
supports / as a path separator, so the naming convention is identical to
Vault from Phase 0 onward and no separator remapping is required.
This continuity is intentional and is enforced by Invariant 2. The
naming convention is defined by RFC-SECOPS-0001 Section 5a.5 and
adopted by this interim architecture to eliminate naming migration as
a migration cost.
5.6 Migration Risks
| Risk | Phase | Likelihood | Impact | Mitigation |
|---|---|---|---|---|
| Secret value mismatch during store migration | 2 | Low | High | Automated copy verification; dual-read validation period |
| Application downtime during ESO switchover | 1, 2 | Medium | Medium | Blue-green ExternalSecret deployment; verify sync before cutover |
| IAM credential leakage during Phase 0 | 0 | Medium | High | Least-privilege IAM policies; regular credential rotation |
| Inventory drift obscures missing secrets | 0, 1 | Medium | Low | Periodic automated reconciliation |
| Extended Phase 0 duration due to infrastructure delays | 0 | High | Medium | Accept risk; this RFC exists precisely for this scenario |