Vault KMS 구성

Vault KMS 구성 (KMS configuration)

vault-kube-kms 프로세스가 KMS v2 gRPC 엔드포인트를 노출하고 Vault에 연결하는 방식을 구성하는 파라미터들을 다룹니다.

출처: 문서

본문

베타 기능이에요. 베타 기능은 안정적이지만 아직 불완전할 수 있고 변경될 수 있어요. 프로덕션 Vault 배포에 베타 기능을 쓰는 것은 권장하지 않습니다.

vault-kube-kms 프로세스를 구성해 KMS v2 gRPC 엔드포인트를 쿠버네티스에 노출하는 방식, Vault 연결·인증 방식, Transit 키 선택, 로그·메트릭 출력 방식을 제어해요.

vault-kube-kms 프로세스는 시작 시 명령줄 플래그로 구성을 읽고 검증합니다. 필수 파라미터가 없거나 잘못되면 프로세스는 오류와 함께 종료돼요.

연결 파라미터 (Connection parameters)

--listen-address (string : "unix:///tmp/vault-kube-kms.socket") — vault-kube-kms 프로세스가 쿠버네티스 API 서버의 요청을 수신하는 유닉스 도메인 소켓 주소. kube-apiserver 프로세스는 vault-kube-kms 프로세스와 통신하려면 이 소켓에 대한 파일시스템 접근이 있어야 해요. 환경 변수: VAULT_KUBE_KMS_LISTEN_ADDRESS
--vault-address (string : <필수>) — vault-kube-kms 프로세스가 Vault 서버에 도달해 Transit 플러그인으로 인증·암호화 작업을 수행할 수 있는 HTTP(S) 주소. 환경 변수: VAULT_KUBE_KMS_VAULT_ADDRESS
--vault-namespace (string : "") — Transit 플러그인이 마운트된 Vault 네임스페이스. 루트 네임스페이스에 플러그인을 마운트했다면 vault-namespace는 설정하지 않아도 돼요. Vault 배포에서 네임스페이스를 사용한다면 마운트 경로에 넣지 말고 vault-namespace로 플러그인 네임스페이스를 제공해야 해요. 환경 변수: VAULT_KUBE_KMS_VAULT_NAMESPACE
--transit-mount (string: "transit") — Vault Transit 플러그인으로 가는 마운트 경로. vault-kube-kms 프로세스는 DEK(데이터 암호화 키)를 암호화·복호화하는 Vault 요청을 만들 때 transit-mount를 사용해요. 환경 변수: VAULT_KUBE_KMS_TRANSIT_MOUNT
--transit-key (string: <필수>) — DEK 암호화·복호화 중 Vault에 요청을 만들 때 vault-kube-kms 프로세스가 사용해야 하는 Transit 플러그인의 기존 키 이름. vault-kube-kms 프로세스가 지정한 키에 접근할 권한을 부여하는 Vault 정책을 구성해야 해요. 환경 변수: VAULT_KUBE_KMS_TRANSIT_KEY
--tls-ca-file (string: "") — vault-kube-kms 프로세스가 Vault가 사용하는 TLS 인증서를 검증하는 데 쓸 수 있는 CA 인증서 파일 경로. 시스템 신뢰 저장소를 사용하려면 tls-ca-file을 설정하지 않아도 돼요. 환경 변수: VAULT_KUBE_KMS_TLS_CA_FILE
--tls-skip-verify (bool: false) — 비프로덕션 환경에서 Vault에 연결할 때 TLS 인증서 검증을 건너뛰도록 vault-kube-kms 프로세스에 알려요. 환경 변수: VAULT_KUBE_KMS_TLS_SKIP_VERIFY
--tls-sni (string: "") — vault-kube-kms 프로세스가 TLS로 Vault에 연결할 때 사용하는 SNI(서버 이름 표시). 환경 변수: VAULT_KUBE_KMS_TLS_SNI
--vault-connection-timeout (string: "30s") — 지속 시간 표기(예: '15s', '30s')로 Vault에 연결을 설정하는 타임아웃. 환경 변수: VAULT_KUBE_KMS_VAULT_CONNECTION_TIMEOUT

인증 파라미터 (Authentication parameters)

vault-kube-kms 프로세스는 현재 AppRole 인증만 지원해요.

AppRole 파라미터

AppRole 인증에는 다음 파라미터를 포함해야 해요.

--auth-mount (string: "approle") — vault-kube-kms 프로세스가 Vault에 인증할 때 사용하는 Vault 인증 방식 플러그인의 마운트 경로. 필수. 환경 변수: VAULT_KUBE_KMS_AUTH_MOUNT
--approle-role-id (string: <필수>) — Vault에 인증할 때 vault-kube-kms 프로세스가 자신을 식별하는 데 사용하는 비민감 AppRole 역할 ID. 환경 변수: VAULT_KUBE_KMS_APPROLE_ROLE_ID
--approle-secret-id-path (string: <필수>) — approle-role-id와 연결된 민감한 AppRole 시크릿 ID가 담긴 파일의 파일시스템 경로. 대상 파일은 항상 적절한 파일시스템 권한으로 보호해요. vault-kube-kms 프로세스는 시작 시 approle-secret-id-path에서 시크릿 ID를 읽습니다. 환경 변수: VAULT_KUBE_KMS_APPROLE_SECRET_ID_PATH

로깅, 메트릭, 텔레메트리 파라미터

--zap-log-level (string: "info") — 로그 세부 수준. 'debug', 'info', 'error', 'panic' 중 하나이거나, 커스텀 세부 수준을 위한 특정 정수 값일 수 있어요. 자세한 내용은 controller-runtime zap 패키지 문서를 참고하세요.
- debug — 세부 수준이 높은 개발 모드 로깅
- info — 일반 운영 맥락의 프로덕션 모드 로깅 (기본값)
- error — 오류와 심각한 실패만 로깅
- panic — panic 수준 이벤트만 로깅
- 4 — 경고 수준 로깅
- 5 — 디버그 수준 로깅
- 6 — 추적 수준 로깅 (가장 상세)
--metrics-port (int: 9090) — Prometheus 호환 /metrics 엔드포인트를 노출하는 vault-kube-kms 프로세스 로컬 TCP 포트. 엔드포인트는 localhost에 바인딩돼요. 0이나 음수로 설정하면 메트릭 엔드포인트가 비활성화됩니다. 환경 변수: VAULT_KUBE_KMS_METRICS_PORT
--disable-runtime-metrics (bool: false) — /metrics 엔드포인트에서 Go 런타임과 프로세스 수준 메트릭을 비활성화하도록 vault-kube-kms 프로세스에 알려요. false(기본값)로 설정하면 가비지 컬렉션 통계, 고루틴 수, 메모리 사용량을 포함한 런타임 메트릭이 노출됩니다. 환경 변수: VAULT_KUBE_KMS_DISABLE_RUNTIME_METRICS

최소 구성 예제

기본 예제 ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: vault-kms-config
data:
  listen-address:         "/var/run/kms/vault-kms.sock"
  vault-address:          "https://vault.example.com:8200"
  transit-mount:          "transit"
  transit-key:            "kubernetes-etcd"
  approle-role-id:        "example-role-id"
  approle-secret-id-path: "/var/run/secrets/vault/secret-id"