본문으로 건너뛰기

Vault 설정

HashiCorp Vault를 사용한 시크릿 관리 및 Transit 암호화 엔진 설정입니다.

개요​

GenD는 Vault Transit 엔진으로 커넥터 비밀번호 등 민감 정보를 암호화할 수 있습니다. 로컬 개발에서는 Raft Storage 기반 Standalone 모드, 프로덕션에서는 3노드 HA 클러스터를 사용합니다.

:::warning Transit 암호화는 기본적으로 꺼져 있다

GEND_VAULT_ENABLED 의 기본값은 false 이고, 이 값이 꺼져 있으면 VaultClient.encrypt() 는 평문을 그대로 반환합니다(예외도 경고도 없습니다).

즉 아래 절차로 Transit 엔진과 키를 만들어 두어도, 애플리케이션에서 켜지 않으면 커넥터 비밀번호는 DB 에 평문으로 저장됩니다. 인프라를 구성했다는 사실은 암호화가 동작한다는 증거가 아닙니다.

확인 방법 — 저장된 값이 vault:v1: 로 시작하는지 봅니다:

SELECT count(*) FILTER (WHERE password LIKE 'vault:v%') AS encrypted,
       count(*) FILTER (WHERE password IS NOT NULL AND password <> ''
                          AND password NOT LIKE 'vault:v%') AS plaintext
FROM data_sources;

현재 상태와 조치는 #3210 을 참조하십시오. :::

배포 구성​

환경모드스토리지매니페스트
개발 (Kind)StandaloneRaft + PVCvault-standalone.yaml
프로덕션HA 3노드Raft + PVCha-raft.yaml

초기화 및 Unseal​

# Vault 초기화 (최초 1회)
kubectl exec -n gend vault-0 -- vault operator init \
  -key-shares=5 -key-threshold=3

# Unseal (3개 키 입력)
kubectl exec -n gend vault-0 -- vault operator unseal <KEY1>
kubectl exec -n gend vault-0 -- vault operator unseal <KEY2>
kubectl exec -n gend vault-0 -- vault operator unseal <KEY3>

자동 초기화를 위해 vault-init-job.yaml을 사용할 수 있습니다.

Transit 엔진 설정​

GenD API는 datax-connector Transit 키로 커넥터 비밀번호를 암호화합니다 — GEND_VAULT_ENABLED=true 일 때만.

vault secrets enable transit
vault write -f transit/keys/datax-connector

키 이름 datax-connector 는 애플리케이션 코드의 상수 (gend_api/services/vault_client.py 의 TRANSIT_KEY) 와 정확히 같아야 합니다. 소비자가 하드코딩 상수 하나이므로 이름이 어긋나면 암호화가 실패하고, VaultClient 는 fail-closed 라 커넥터 저장 자체가 막힙니다. CI 가드 scripts/test_vault_transit_key_names.py 가 이 일치를 강제합니다.

프로덕션 부트스트랩은 infra/vault/prod/scripts/05-enable-transit.sh 가 수행하며, datax-connector 에 90일 자동 회전(auto_rotate_period=2160h)까지 설정합니다.

API Pod 정책​

vault-policy-gend-api.hcl에서 최소 권한 원칙을 적용합니다.

경로권한용도
transit/encrypt/datax-connectorupdate비밀번호 암호화
transit/decrypt/datax-connectorupdate비밀번호 복호화
transit/keys/datax-connectorread키 메타데이터 조회

GenD API 연동​

GEND_VAULT_ENABLED=true
GEND_VAULT_ADDR=http://vault:8200
GEND_VAULT_TOKEN=<ROOT_TOKEN>   # 프로덕션: K8s Auth Method 사용

서비스 접근​

서비스포트용도
vault (ClusterIP)8200내부 API
vault-internal (Headless)8200/8201Raft 클러스터 통신
vault-nodeport31900UI 접근 (개발용)

관련 문서​