Vault

목적

Vault는 Lumie의 공유 시크릿 저장소이고, Vault Secrets Operator(VSO)는 Vault KV 데이터를 Kubernetes Secret으로 투영하는 기본 인클러스터 경로입니다. 저장소에는 과거 External Secrets 사용을 위한 소량의 레거시 호환 scaffolding도 남아 있지만, 새 매니페스트는 VaultStaticSecret을 사용해야 합니다.

이 페이지는 시크릿 projection, 부트스트랩 인증, GitOps가 관리하는 Vault 리소스와 수동 Vault 런타임 설정 사이의 경계를 변경하는 개발자를 위한 reference 문서입니다.

소스 경로

경로	역할
lumie-infra/bootstrap/vault/argocd.yaml	Vault, VSO, 공통 wrapper chart, 로컬 auth 매니페스트를 설치하는 Argo CD 애플리케이션
lumie-infra/bootstrap/vault/helm-values.yaml	Vault 서버 구성, probe, service, 리소스 설정
lumie-infra/bootstrap/vault/vso-helm-values.yaml	Vault Secrets Operator controller 구성
lumie-infra/bootstrap/vault/common-values.yaml	공유 RBAC와 레거시 clusterSecretStore 호환 블록
lumie-infra/bootstrap/vault/manifests/vault-auth.yaml	공유 VaultConnection과 VaultAuth 리소스
lumie-infra/charts/common/templates/vault-static-secrets.yaml	앱 values에서 VaultStaticSecret 리소스를 투영하는 재사용 템플릿
lumie-infra/provision/ansible/roles/argocd-bootstrap/tasks/main.yml	Argo CD가 제어권을 넘겨받기 전에 vault-config-secret 생성
lumie-infra/bootstrap/vault/OIDC-SETUP.md	Vault OIDC auth mount를 위한 수동 비 GitOps 설정

퍼블릭 표면

표면	계약
Vault 서비스	vault 네임스페이스의 포트 8200 ClusterIP 서비스
UI	활성화되어 있지만, 검사한 저장소에는 ingress가 없고 외부 접근은 Teleport를 통해 이뤄질 것으로 예상
공유 VSO auth	VaultConnection vault-connection + VaultAuth vault-auth
Projection 템플릿	앱 팀이 common.vaultStaticSecrets를 선언하면 charts/common이 VaultStaticSecret CR을 렌더링

런타임 흐름

공유 인증 계약

공유 auth 표면은 작지만 중요합니다.

kind: VaultAuth
metadata:
  name: vault-auth
  namespace: vault
spec:
  allowedNamespaces:
    - "*"
  kubernetes:
    role: vault-secrets-operator
    serviceAccount: default

검사한 소스에서 중요한 세부 사항은 다음과 같습니다.

• vault-auth는 allowedNamespaces: ["*"]를 통해 네임스페이스 간에 공유됩니다.
• allowedNamespaces 버그를 우회하기 위한 vault 네임스페이스 전용 vault-auth-local이 존재합니다.
• charts/common/templates/vault-static-secrets.yaml은 기본 vaultAuthRef를 vault/vault-auth로 설정하므로, 대부분의 앱 values 파일은 이 연결을 반복해서 적지 않습니다.
• 부트스트랩 Ansible은 Vault의 스토리지 백엔드를 MinIO vault 버킷으로 가리키는 vault-config-secret을 생성합니다.

부트스트랩 및 런타임 경계

책임	소유자
vault-config-secret, 초기 네임스페이스 생성, 첫 Argo CD 설치	Ansible bootstrap role
Vault 서버 배포와 VSO controller	bootstrap/vault/argocd.yaml와 Helm values
워크로드로의 시크릿 projection	직접 선언되거나 charts/common에서 렌더링된 VaultStaticSecret 리소스
Vault 초기화, unseal, OIDC auth mount	bootstrap/vault/OIDC-SETUP.md와 Ansible task 노트의 수동 런타임 절차

Vault는 완전한 self-bootstrapping이 아닙니다. 새 클러스터는 여전히 GitOps 매니페스트 밖에서 vault operator init, unseal, OIDC auth 설정이 필요합니다.

변경을 수반하는 bootstrap 작업은 이 reference 페이지의 의도적 범위 밖입니다. 초기화, unseal, 런타임 auth 연결이 필요하면 lumie-infra/bootstrap/vault/OIDC-SETUP.md와 Ansible bootstrap role을 핸드오프 표면으로 사용하세요.

장애 지점 및 드리프트

장애 지점	동작
Vault가 seal 상태이거나 초기화되지 않음	VSO가 대상 Secret을 갱신할 수 없음
vault-config-secret 누락	Vault 서버가 MinIO 기반 구성을 마운트할 수 없음
VaultStaticSecret projection 누락	워크로드가 환경 변수나 Secret 마운트 부족으로 실패
필요한 곳에 rolloutRestartTargets 누락	시작 시 env var만 읽는 pod가 시크릿 갱신 후 자동 재시작되지 않음

검사한 소스는 레거시 시크릿 관리 방식에 대해서도 서로 다릅니다.

소스	주장
lumie-infra/AGENTS.md	SealedSecrets와 ExternalSecrets는 금지되며 Vault 전용이 규칙이라고 설명
bootstrap/vault/common-values.yaml	ESO에서 VSO로 이행하는 동안 호환 clusterSecretStore가 남아 있다고 설명하며 실제로 렌더링함
lumie-infra/README.md	아직 시크릿 계층을 HashiCorp Vault + External Secrets Operator로 설명

활성 계약은 VSO + VaultStaticSecret입니다. 호환 블록과 README 문구는 레거시 드리프트로 취급하세요.

검증

cd lumie-infra
rg -n "VaultStaticSecret|vault-auth|vault-connection|clusterSecretStore|vault-config-secret" \
  bootstrap/vault charts/common provision/ansible applications platform security storage

kubectl get vaultconnections,vaultauth,vaultstaticsecrets -A
kubectl get application vault -n argocd -o yaml
kubectl get statefulset,svc,secret -n vault
kubectl port-forward -n vault svc/vault 8200:8200
curl -sS -o /dev/null -w "%{http_code}\n" \
  "http://127.0.0.1:8200/v1/sys/health?standbyok=true&sealedcode=204&uninitcode=204"

성공 신호:

• vault Argo CD 애플리케이션이 Healthy 및 Synced 상태입니다.
• vault 네임스페이스에 VaultConnection vault-connection과 VaultAuth vault-auth가 존재합니다.
• vault-config-secret 부트스트랩 시크릿이 존재하고 vault StatefulSet이 존재합니다.
• 헬스 프로브는 차트가 명시적으로 허용하는 pre-init 또는 sealed bootstrap 상태에서는 204, 활성 노드에서는 200을 반환합니다.