# Terraform state migration to three Vault states

새 클러스터에는 이 runbook이 필요하지 않습니다. Legacy `vault-core` 또는
더 오래된 `provider-foundation`, `workload-foundation`, `workload-config`,
`database-config` state가 실제로 존재할 때만 사용합니다.

> 2026-07-26 리팩터링에서는 이 절차를 실제 backend나 cluster에 실행하지
> 않았습니다. Maintenance window, 독립 backup과 승인 없이 시작하지
> 않습니다.

State 이동은 live object 삭제보다 위험할 수 있습니다. State split,
Terraform module refactor, Vault KV path/namespace cutover를 한 apply에
섞지 않습니다.

## 목표 ownership

| Legacy ownership | 목표 state |
|---|---|
| `vault-core`의 mounts/auth/delegation 객체 | `vault-foundation` |
| `vault-core` 또는 `workload-config`의 workload policy/role와 Transit key | `vault-workloads` |
| `vault-database` 또는 `database-config`의 auth-system connection과 migration role | `vault-database` |
| 별도 same-cluster Transit provider Vault | State archive 후 별도 decommission 절차 |

목표 backend key는 각각 달라야 합니다.

```text
dev-k3s/vault-foundation.tfstate
dev-k3s/vault-workloads.tfstate
dev-k3s/vault-database.tfstate
```

동일 Vault API path가 두 state에 동시에 남아 있으면 cutover가 끝난 것이
아닙니다. State끼리 `terraform_remote_state`를 추가하지 않습니다.

## 1. Freeze, inventory, backup

모든 Terraform apply와 관련 image/config promotion을 중단합니다.
ApplicationSet의 injector, `auth-system`, `auth-server`, `api-server`
autoSync gate도 닫습니다. 이 gate는 Argo의 자동 sync만 멈추며 이미 실행
중인 Pod의 재시작, node drain 또는 controller 동작을 막지 않습니다.
Migration 중 legacy path를 병행 유지하고, 완전한 quiesce가 필요하면
workload별 scale/maintenance 절차를 별도로 승인합니다.

각 legacy backend에서 다음을 확보합니다.

- `terraform state pull` 원본
- state checksum
- `terraform state list`
- 이동할 각 address의 `terraform state show`
- 현재 Vault object ID/path와 provider version

Backup에는 credential과 secret data가 포함될 수 있으므로 encrypted
offline custody에 보관합니다. Backend lock이 작동하는지 확인하고 source
state를 수정할 runner를 하나로 제한합니다.

## 2. Migration code 준비

먼저 실제로 배포된 legacy Git revision에서 임시 migration branch를
만듭니다. 그 revision의 policy 문서, namespace binding, role payload를
그대로 유지한 `vault-workloads` root와 import block만 추가합니다. 현재
branch의 새 KV path와 `auth-system-dev` binding을 이 단계에 복사하면
ownership 이동과 live policy 변경이 섞이므로 사용할 수 없습니다.

Source와 destination은 같은 legacy object payload를 선언해야 합니다.
실제 import ID는 backup의 `state show`로 확정하며 이름을 추측하지
않습니다. Ownership split이 양쪽 no-op으로 끝난 뒤에만 현재 desired
revision을 별도 path/namespace cutover PR로 적용합니다.

일반적인 import ID 형식은 다음과 같습니다.

```text
vault_policy                         <policy-name>
vault_kubernetes_auth_backend_role  auth/kubernetes/role/<role-name>
vault_transit_secret_backend_key    transit/keys/project-auth-jwt
```

Legacy core/foundation source에는 이동 대상별 `removed` block을 둡니다.

```hcl
removed {
  from = module.workload_policies

  lifecycle {
    destroy = false
  }
}

removed {
  from = module.workload_roles

  lifecycle {
    destroy = false
  }
}

removed {
  from = vault_transit_secret_backend_key.project_auth_jwt

  lifecycle {
    destroy = false
  }
}
```

실제 address가 다르면 현재 state list를 사용합니다. 위 예를 그대로
복사하지 않습니다.

Module 구조 개선은 아직 하지 않습니다. 우선 기존 address/선언으로
ownership만 옮기고 후속 PR에서 `moved` block을 사용합니다.

## 3. 양쪽 plan 검토

Source와 destination을 같은 revision에서 plan합니다.

| Plan | 허용 결과 |
|---|---|
| Source core/foundation | 대상 object를 state에서만 제거, live destroy `0` |
| Destination workloads | 기존 live object import, create/change/destroy `0` |

둘 중 하나라도 live create, update, delete를 제안하면 중단합니다. Policy
내용이나 Vault path rename은 이 단계에 포함하지 않습니다.

## 4. Workload ownership split

승인된 maintenance window에서 다음 순서로 진행합니다.

1. Source의 `removed { destroy = false }` apply
2. 즉시 destination import apply
3. 양쪽 `state list`에서 object가 정확히 한 번만 나타나는지 확인
4. 양쪽 plan이 no-op인지 확인

Manual remote `state push`나 offline `state mv -state/-state-out`을 primary
절차로 사용하지 않습니다. Source 제거와 destination import 사이에 문제가
생기면 다른 apply를 진행하지 말고 backup과 승인된 rollback 절차를
사용합니다.

## 5. Foundation backend key 전환

Workload object를 분리한 뒤 남은 legacy `vault-core` state 전체를
`vault-foundation` backend key로 `terraform init -migrate-state` 합니다.
Migration 전후의 state list와 serial/lineage, checksum을 기록합니다.

`vault-database`의 state 경계는 유지하지만 connection address와 live
object 이름은 모두 바뀝니다.

```text
vault_database_secret_backend_connection.platform_postgres
  -> vault_database_secret_backend_connection.auth_system_postgres

database/config/platform-postgres-dev
  -> database/config/auth-system-postgres-dev
```

Checked-in `moved` block은 Terraform address만 이관합니다. Vault connection
이름 변경은 replacement이며 `create_before_destroy`도 생성/삭제 사이에
operator 승인 대기 시간을 만들지 않습니다. 기존 cluster에서는 final
configuration을 바로 apply하지 말고 별도 blue/green cutover를 준비합니다.

1. 임시 migration revision에서 old connection을 유지하고 new connection을
   별도 resource로 추가합니다.
2. Database runner policy가 maintenance window 동안 old/new 두 exact
   `database/config` path를 모두 허용하게 합니다.
3. New connection 검증 뒤 `auth-db-migration-dev` role을 new connection으로
   전환하고 credential issue/revoke를 시험합니다.
4. Old connection에 연결된 lease를 inventory하고 만료 또는 명시적 revoke를
   확인합니다.
5. 후속 승인에서 old connection과 임시 policy path를 제거합니다.

기존 이름이 `database-config`이거나 backend key가 다를 때는 이 cutover와
분리해 `vault-database` backend key로 migration합니다.

Database object를 새로 import해야 하는 경우의 target address와 ID는
다음과 같습니다.

```text
vault_database_secret_backend_connection.auth_system_postgres
  database/config/auth-system-postgres-dev
vault_database_secret_backend_role.auth_db_migration
  database/roles/auth-db-migration-dev
```

이미 다른 state에 address가 있으면 import하지 말고 ownership을 먼저
이동합니다.

## 6. Retired broad/unused access

다음 legacy object는 새 state의 desired ownership이 아닙니다.

- Broad `platform-admin-dev` policy와 이를 사용한 `vault-operator-dev` role
- Legacy 단일 `project-gitops-dev` CI JWT role
- 미사용 `keycloak-operator-dev`, `postgres-operator-dev` policies
- 미사용 `database/roles/postgres-operator-dev` dynamic role

State split 중 자동 destroy하지 않습니다. 우선 `removed { destroy = false }`
로 legacy source ownership에서 분리하고, Vault audit/consumer inventory로
사용자가 없음을 확인합니다. Token/lease revoke와 live object 삭제는
별도 보안 decommission 승인으로 수행합니다.

기존 `jwt-ci` auth mount가 state에 있으면 ownership 이동 동안 실제
issuer/discovery 입력을 유지합니다. 입력을 누락해 `count = 0`이 되어도
`prevent_destroy`가 mount 삭제를 차단해야 합니다. Mount와 그 하위 role을
제거할 때만 token/accessor와 consumer를 확인한 별도 decommission
revision에서 명시적으로 보호를 해제합니다.

## 7. Vault path와 namespace cutover

State split이 no-op인 것을 확인한 뒤 별도 PR/maintenance window에서
다음 legacy path를 새 owner path로 이관합니다.

```text
kv/dev/platform/postgres/*  -> kv/dev/systems/auth-system/postgres/*
kv/dev/platform/keycloak/bootstrap-admin
                             -> kv/dev/systems/auth-system/keycloak/bootstrap-admin
kv/dev/platform/keycloak/client-auth-server
                             -> kv/dev/workloads/auth-server/keycloak-client
```

KV payload는 Terraform으로 이동하지 않습니다. 승인된 operator가 값을
노출하지 않는 secret procedure로 새 path에 기록하고 metadata/version을
확인합니다. Policy, Kubernetes role, Agent annotation, namespace/DNS
변경을 render와 Vault capability test로 검증합니다.

`platform`에서 `auth-system-dev`로의 live namespace 이동은 Kubernetes
state/data migration입니다. Terraform state split과 별도로 backup,
non-cascading ownership transfer, rollback 계획을 가져야 합니다.

새 consumer가 정상 동작하고 rollback 기간이 끝날 때까지 legacy KV value와
policy를 삭제하지 않습니다. 삭제는 별도 승인 작업입니다.

## 8. 완료 조건

- `vault-foundation`, `vault-workloads`, `vault-database`가 서로 다른 remote
  backend와 lock을 사용
- 각 Vault API path가 정확히 한 state list에만 존재
- 세 plan에 예상하지 않은 create/change/delete가 없음
- Delegated state가 자신의 automation policy/login role을 소유하지 않음
- Workload/database identity의 허용·거부 capability test 통과
- Legacy state와 backup이 immutable archive에 있음
- Repository와 runner working directory에 local state, plan, provider
  directory가 없음
- New KV path와 `auth-system-dev` cutover 전에는 관련 autoSync gate가 닫힘

검증이 끝나기 전 legacy backend, Vault path, namespace 또는 PVC를
삭제하지 않습니다.