Vault 순환 종속성 부트스트랩

이 페이지는 2026년 1월 13일 Vault 복구 순서에 대한 사고 회고입니다. 중요한 부트스트랩 실패 모드, 제대로 작동한 복구 순서, 현재 저장소가 이미 다른 안정된 상태로 이동한 위치를 기록합니다.

실패한 것

주요 중단은 폐쇄형 부트스트랩 종속성이었습니다.

대표적인 형태:

Vault -> PostgreSQL -> ExternalSecrets -> Vault

Vault에는 PostgreSQL이 필요했고, PostgreSQL 자격 증명은 externalSecrets를 통해 제공되었으며, Vault가 정상 상태가 될 때까지 externalSecrets를 조정할 수 없었습니다. Vault가 완전히 시작을 중지하면 스택에 콜드 스타트 경로가 없습니다.

동일한 작업 창에서는 네 가지 관련 오류도 노출되었습니다.

필수 Vault 스토리지 테이블 없이 PostgreSQL 지원 Vault HA 마이그레이션이 시도되었습니다.
vault operator init가 다시 실행되어 이전 잠금해제 키와 루트 토큰을 사용할 수 없게 만들고 백업에서 수동 비밀 복원을 강제했습니다.
구성된 user_claim에서 ID 토큰에 더 이상 존재하지 않는 preferred_username를 예상했기 때문에 Authelia에 대한 Vault OIDC 로그인이 실패했습니다.
포트 80 및 443에 대한 광범위한 마스터 노드 DNAT 규칙은 클러스터 내 Kubernetes API 트래픽을 가로채서 ClusterSecretStore가 InvalidProviderConfig를 보고하도록 했습니다.

확인된 원인

부트스트랩 그래프는 순환적이었습니다. 궁극적으로 Vault에 의존하는 자격 증명이 없으면 Vault가 나타날 수 없습니다.
PostgreSQL 스토리지에는 사전 생성된 vault_kv_store 및 vault_ha_locks 테이블이 필요합니다. Vault는 실패한 마이그레이션 시도 중에 해당 스키마를 자동으로 생성하지 않았습니다.
vault operator init를 다시 실행하면 새로운 초기화 상태가 생성되고 이전에 저장된 데이터에 대한 액세스가 중단되므로 실제로는 파괴적이었습니다.
Authelia의 클레임 동작이 변경되어 preferred_username에 의존하는 Vault 역할이 일치하지 않습니다.
마스터 노드의 호스트 수준 DNAT가 너무 광범위하고 클러스터 서비스 네트워크 내부에 있어야 하는 트래픽을 리디렉션했습니다.

해결 순서

Vault를 비순환 저장소 경로로 이동하여 Vault가 외부 비밀을 기다리지 않고 시작할 수 있도록 하여 부트스트랩 주기를 중단합니다.
다운스트림 비밀 소비자에게 필요한 Vault 인증 및 KV 마운트를 다시 생성합니다.
백업 자료에서 20개 이상의 비밀을 수동으로 복원합니다.
로그인이 더 이상 누락된 Authelia 클레임에 의존하지 않도록 Vault OIDC 역할 매핑을 변경합니다.
클러스터 내 클라이언트의 Kubernetes API 호출이 API 서버에서 리디렉션되는 것을 중지하도록 광범위한 NAT 동작을 제거합니다.

중요한 교훈은 정확성뿐만 아니라 질서였습니다. Vault가 독립적으로 시작될 때까지 모든 다운스트림 비밀 소비자는 차단된 상태로 유지되었습니다.

현재 저장소가 여전히 증명하는 것

체크인된 Vault 계약은 더 이상 사고에 대한 임시 해결 방법이 아닙니다. 현재 저장소에는 외부 구성 비밀이 차트에 마운트된 독립형 Vault가 표시됩니다.

server:
  standalone:
    enabled: true
  ha:
    enabled: false
  extraArgs: "-config=/vault/userconfig/extraconfig-from-values.hcl"

출처: lumie-infra/bootstrap/vault/helm-values.yaml

현재 저장소는 또한 Vault OIDC가 Helm 값이 아닌 런타임 절차로 남아 있음을 보여줍니다.

lumie-infra/bootstrap/vault/OIDC-SETUP.md
lumie-infra/security/keycloak/common-values.yaml
lumie-infra/security/teleport/agent/helm-values.yaml

주의할 점

2026년 1월 사고 기록에는 주기를 깨기 위해 임시 파일 백엔드 복구가 기록되어 있습니다. 현재 저장소는 더 이상 정확한 상태를 유지하지 않습니다. 이제 vault-config-secret에서 주입된 구성을 사용하여 독립형 Vault를 문서화하고 OIDC 설정 가이드는 Authelia 시대의 클레임 해결 방법이 아닌 최신 Keycloak 기반 흐름을 위해 작성되었습니다.

해당 드리프트는 실제이므로 명시적으로 호출해야 합니다.

사건 페이지는 무엇이 실패했고 어떻게 복구가 지시되었는지에 대한 진실의 원천입니다.
체크인된 매니페스트는 이후의 정상 상태 계약에 대한 진실의 원천입니다.

지속적인 교훈

비밀 저장소, 데이터베이스 및 비밀 렌더러 간의 부트스트랩 종속성을 방향성 그래프로 처리합니다. 그래프에 사이클이 포함되어 있으면 콜드 스타트가 이미 중단된 것입니다.
vault operator init를 백업 및 동료 검토를 통해 일회성 작업으로 처리합니다. 안전한 재시도 버튼이 아닙니다.
클러스터 내부 트래픽이 실수로 일치하지 않도록 호스트 수준 DNAT 규칙을 충분히 좁게 유지합니다.
버전 범프가 사소해 보이는 경우에도 IDP를 업그레이드할 때마다 OIDC 클레임 매핑을 다시 확인하세요.
백업과 복원은 모두 자동화되어야 합니다. 수동 복구는 데이터 모델을 재구성할 수 있음을 입증했을 뿐 복구 경로가 안전하다는 것을 입증하지 못했습니다.

확인

cd Lumie
rg -n "standalone:|ha:|vault-config-secret|extraArgs" \
  lumie-infra/bootstrap/vault/helm-values.yaml
rg -n "vault-backend|ClusterSecretStore|vault.vault.svc.cluster.local" \
  lumie-infra/bootstrap/vault/common-values.yaml
rg -n "auth/oidc|preferred_username|groups_claim|default_role" \
  lumie-infra/bootstrap/vault/OIDC-SETUP.md

성공은 저장소가 독립 실행형 Vault, 저장소 관리형 Vault 인증 표면 및 Helm 값과 별도의 런타임 OIDC 절차를 계속 표시한다는 것을 의미합니다. 이는 현재 계약을 확인하고 역사적 드리프트를 가시화합니다.

실패한 것​

확인된 원인​

해결 순서​

현재 저장소가 여전히 증명하는 것​

주의할 점​

지속적인 교훈​

확인​