Skip to main content

​
Agent Settings — Vault CA

경로: Admin → Agent Settings → VAULT CA 탭

​
개요

에이전트가 HashiCorp Vault 에서 비밀값 (API Token·DB Password·Cert 등) 을 안전하게 받아오도록 하는 설정입니다. Vault 서버와의 TLS 검증을 위해 CA 인증서가 K8s ConfigMap 에서 Pod 로 마운트됩니다.

​
필드

필드설명예시
Vault CA EnabledVault CA 인증서 마운트 활성/비활성 토글Enabled / Disabled
Vault CA NamespaceCA 인증서가 저장된 K8s 네임스페이스seahorse-cloud-eks
Vault CA ConfigMap NameCA 인증서를 담은 ConfigMap 이름vault-tls-ca
Vault AddressHashiCorp Vault 서버 주소https://10.1.1.162:8200 / https://vault.example.com
Vault Role에이전트가 인증할 Vault role 이름seahorse-agent

​
동작 흐름

1

1. CA 인증서 준비

Vault 서버의 루트 CA 를 K8s ConfigMap 으로 저장:
kubectl create configmap vault-tls-ca \
  -n seahorse-cloud-eks \
  --from-file=ca.crt=/path/to/vault-ca.crt
2

2. Vault 측 Role 구성

Vault 에서 Kubernetes Auth Method 활성화 및 seahorse-agent role 생성. 역할에 에이전트가 읽을 수 있는 secret path 정책 을 바인딩.
3

3. UI 에서 필드 입력

위 4개 필드를 Agent Settings → Vault CA 탭에 입력하고 Enabled 토글 ON.
4

4. 에이전트 배포

신규 에이전트 Pod 은 자동으로:
  • CA 인증서를 /etc/vault-ca/ 경로로 마운트
  • Vault Address 로 TLS 연결
  • Vault Role 로 JWT 기반 인증 → 단기 토큰 발급
5

5. Secret 참조

도구·Endpoint 환경변수에서 valueSource: vault 지정 시 해당 토큰으로 secret path 조회. 자세한 내용은 도구 생성 → env valueSource

​
활성화 조건

Vault CA 를 사용하려면 아래가 모두 준비 되어야 합니다:
  1. Vault 서버가 운영 중 (클러스터 접근 가능)
  2. Kubernetes Auth Method 가 Vault 에 구성됨
  3. 에이전트용 role(seahorse-agent) 과 secret 정책 설정됨
  4. CA 인증서 ConfigMap 이 해당 namespace 에 존재

​
비활성화 시 영향

  • 에이전트가 secret 을 받아오려면 환경변수에 평문 또는 system_default 사용
  • 자동 회전·감사 로그 연계 등 Vault 의 이점 없음
  • 소규모·PoC 환경에서는 Disabled 로 운영 가능

​
트러블슈팅

  • 에이전트 Pod 이 CrashLoopBackOff — ConfigMap 이름/네임스페이스 오타 확인
  • x509: certificate signed by unknown authority — CA 인증서가 실제 Vault 의 체인과 일치하지 않음
  • permission denied from Vault — role 의 policy 가 secret path 를 읽지 못함. vault policy read {policy} 로 확인
  • 토큰 만료 관련 5xx — role TTL 설정 점검

​
관련 문서