OCI Vault + ESO로 portfolio server 런타임 시크릿 관리 도입

[yw7148]

Summary

현재 OCI k3s + Argo CD 구조에서 portfolio server 런타임 시크릿을 Git 밖에서 관리하도록 전환한다.

필요한 런타임 시크릿:

• DB_URL
• DB_USER
• DB_PW
• JWT_SECRET

목표 구조:

OCI Vault / Secret Management -> External Secrets Operator (ESO) -> Kubernetes Secret -> Deployment

Argo CD는 실제 secret 값을 Git에 두지 않고, ClusterSecretStore / ExternalSecret 같은 참조 리소스만 sync한다.

Why

현재 리포의 설계 문서에서는 secret manager 도입이 범위 밖으로 되어 있지만, portfolio server는 이제 DB/JWT 관련 민감 값을 런타임에서 주입받아야 한다.

Git에 평문 secret을 넣지 않고, OCI 쪽에서 관리되는 secret을 Kubernetes Secret으로 동기화하는 방식으로 운영 경로를 정리할 필요가 있다.

Proposed Direction

• OCI Vault / Secret Management에 애플리케이션 시크릿을 저장한다.
• OCI k3s 클러스터에는 External Secrets Operator를 설치한다.
• 공용 backend 참조는 ClusterSecretStore로 둔다.
• portfolio namespace에는 ExternalSecret을 배포해서 Kubernetes Secret을 생성한다.
• portfolio server Deployment는 env.valueFrom.secretKeyRef로 secret 값을 주입받는다.
• Argo CD는 ESO 관련 리소스만 GitOps로 관리하고, 실제 secret 값은 OCI에만 둔다.

Authentication Choice

이 환경은 OKE가 아니라 OCI Compute 위 k3s 이므로, ESO의 OCI Oracle provider 인증은 InstancePrincipal을 우선 검토한다.

선택 이유:

• UserPrincipal은 private key / fingerprint를 다시 Kubernetes Secret에 넣어야 해서 운영상 덜 깔끔함
• Workload Identity는 OKE enhanced cluster 문맥이라 현재 k3s 구조와 맞지 않음
• InstancePrincipal이 현재 구조에서 가장 단순하고 운영 친화적임

Scope

1. Docs update

다음 문서를 secret externalization 기준으로 업데이트한다.

• docs/k3s-argocd-migration-design.md
• docs/oci-k3s-apply-guide.md
• 필요 시 apps/README.md

문서 반영 내용:

• secret manager 도입을 non-goal에서 제외 또는 별도 섹션으로 승격
• Base platform에 ESO 추가
• OCI Vault / ESO / Kubernetes Secret / Deployment 흐름 추가
• InstancePrincipal 기반 운영 방침 추가
• 검증 절차 추가

2. Platform manifests

clusters/oci-prod/ 아래에 ESO 및 store 리소스를 추가한다.

예상 항목:

• ESO 설치 리소스
• ClusterSecretStore for OCI Vault
• 필요 시 ESO namespace / RBAC 관련 리소스

3. App manifests

portfolio server가 secret을 주입받도록 매니페스트를 확장한다.

예상 항목:

• ExternalSecret 추가
• Deployment env에 아래 값 연결
  • DB_URL
  • DB_USER
  • DB_PW
  • JWT_SECRET

Acceptance Criteria

• 실제 secret 값은 Git repo에 저장되지 않는다.
• OCI Vault에 저장된 secret이 ESO를 통해 Kubernetes Secret으로 동기화된다.
• Argo CD는 ClusterSecretStore / ExternalSecret 등 참조 리소스를 정상 sync한다.
• portfolio server pod가 아래 env를 정상 주입받는다.
  • DB_URL
  • DB_USER
  • DB_PW
  • JWT_SECRET
• secret rotation 시 ESO refresh 정책에 따라 Kubernetes Secret이 갱신된다.

Implementation Notes

• OCI IAM 쪽에서 k3s 노드가 Vault secret을 읽을 수 있도록 dynamic group / policy 구성이 필요하다.
• 공통 backend 재사용을 위해 ClusterSecretStore를 우선 검토한다.
• secret 저장 방식은 아래 둘 중 하나로 결정한다.
  • secret 4개를 개별 plaintext로 저장
  • JSON 1개로 저장하고 ExternalSecret.dataFrom.extract 사용

TODO

• OCI Vault에 DB_URL, DB_USER, DB_PW, JWT_SECRET 저장
• OCI IAM dynamic group / policy 설계 및 적용
• ESO 설치 매니페스트 추가
• ClusterSecretStore 추가
• portfolio namespace용 ExternalSecret 추가
• portfolio server Deployment에 secretKeyRef env 연결
• 적용 가이드 / 운영 문서 업데이트
• 실제 동기화 및 롤링 업데이트 검증