VSO Vault 소스

VSO Vault 소스 (Vault as a secret source)

VSO가 소스로 사용하는 Vault의 시크릿 엔진, 인증 방식, 커스텀 리소스 정의를 다룹니다.

출처: 문서

본문

Vault Secrets Operator(VSO)는 Vault를 시크릿 소스로 지원해서 어떤 플랫폼에서 실행 중인 Vault 인스턴스와도 매끄럽게 통합할 수 있게 해 줍니다.

Vault Secrets Operator(VSO)는 HashiCorp Vault의 완전 지원되는 컴포넌트예요.

지원되는 Vault 플랫폼과 버전

플랫폼 버전
Vault Enterprise/Community 1.11+
HCP Vault Dedicated 1.11+

기능 (Features)

Vault Secrets Operator는 다음 Vault 기능을 지원해요.

지원되는 Vault 인증 방식

백엔드 설명
Kubernetes 수명이 짧은 쿠버네티스 ServiceAccount 토큰에 의존해 Vault 인증
JWT 정적 JWT 토큰 또는 수명이 짧은 쿠버네티스 ServiceAccount 토큰에 의존해 Vault 인증
AppRole 정적 AppRole 자격 증명에 의존해 Vault 인증
AWS AWS 자격 증명에 의존해 Vault 인증
GCP GCP 자격 증명에 의존해 Vault 인증

Vault 접근과 커스텀 리소스 정의

VaultConnection과 VaultAuth CRD는 오퍼레이터에게 Vault 연결·인증 구성 정보를 제공해요. VaultConnection과 VaultAuth를 모든 시크릿 복제 타입 리소스가 사용하는 기반(foundational) 리소스로 생각하면 됩니다.

VaultConnection 커스텀 리소스

단일 Vault 서버 인스턴스에 연결하는 데 필요한 구성 세부 정보를 제공해요.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultConnection
metadata:
  namespace: vso-example
  name: vault-connection
spec:
  # 필수 구성
  # Vault 서버 주소.
  address: http://vault.vault.svc.cluster.local:8200

  # 선택 구성
  # 모든 Vault 요청에 포함할 HTTP 헤더.
  # headers: []
  # TLS 연결의 SNI 호스트로 사용할 TLS 서버 이름.
  # tlsServerName: ""
  # Vault로의 TLS 연결에 대한 TLS 검증 건너뛰기.
  # skipTLSVerify: false
  # 쿠버네티스 시크릿에 저장된 신뢰하는 PEM 인코딩 CA 인증서 체인
  # caCertSecretRef: ""

VaultAuth 커스텀 리소스

VaultConnection 커스텀 리소스에 지정된 단일 Vault 서버 인스턴스에 오퍼레이터가 인증하는 데 필요한 구성을 제공해요.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
  namespace: vso-example
  name: vault-auth
spec:
  # 필수 구성
  # 해당 VaultConnection 커스텀 리소스의 VaultConnectionRef.
  # 값을 지정하지 않으면 오퍼레이터는 자신의 쿠버네티스 네임스페이스에 구성된 
  # `default` VaultConnection으로 기본 설정됩니다.
  vaultConnectionRef: vault-connection
  # Vault에 인증할 때 사용할 방식.
  method: kubernetes
  # 인증 방식에 인증할 때 사용할 마운트.
  mount: kubernetes
  # 쿠버네티스 전용 인증 구성. method를 kubernetes로 설정해야 함.
  kubernetes:
    # Vault에 인증할 때 사용할 역할
    role: example
    # Vault에 인증할 때 사용할 ServiceAccount
    # 항상 Pod/애플리케이션마다 고유한 serviceAccount를 제공하는 것을 권장
    serviceAccount: default

  # 선택 구성
  # 인증 백엔드가 마운트된 Vault 네임스페이스 (Vault Enterprise 필요)
  # namespace: ""
  # Vault에 인증할 때 사용할 Params
  # params: []
  # 모든 Vault 인증 요청에 포함할 HTTP 헤더.
  # headers: []

VaultAuthGlobal 커스텀 리소스

기능 가용성: VSO v0.8.0

여러 VaultAuth 커스텀 리소스가 상속할 수 있는 공유 Vault 인증 구성을 제공하는 네임스페이스 리소스예요. 여러 인증 방식을 지원하고, 개별 VaultAuth 커스텀 리소스가 오버라이드할 수 있는 기본 인증 방식을 정의할 수 있습니다. 자세한 내용은 VaultAuth spec의 vaultAuthGlobalRef를 참고하세요. VaultAuthGlobal 커스텀 리소스는 선택 사항이며, 구성 중복을 줄여 여러 VaultAuth 커스텀 리소스의 구성을 단순화하는 데 사용할 수 있어요. 다른 네임스페이스 VSO 커스텀 리소스처럼, 단일 쿠버네티스 클러스터에 많은 VaultAuthGlobal 리소스를 구성할 수 있습니다.

VaultAuthGlobal을 워크플로에 통합하는 방법에 대한 자세한 내용은 자세한 Authentication 문서를 참고하세요.

팁: VaultAuthGlobal 리소스는 VaultAuth 커스텀 리소스와 많은 필드를 공유하지만 직접 인증에는 사용할 수 없어요. 쿠버네티스 클러스터 안에서 공유 Vault 인증 구성을 정의하는 데만 사용됩니다.

아래 예제는 기본 인증 방식이 kubernetes인 VaultAuthGlobal 커스텀 리소스와, 그 전역 구성을 상속하는 VaultAuth 커스텀 리소스를 정의하는 방법을 보여줘요.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuthGlobal
metadata:
  namespace: vso-example
  name: vault-auth-global
spec:
  defaultAuthMethod: kubernetes
  kubernetes:
    audiences:
    - vault
    mount: kubernetes
    namespace: example-ns
    role: auth-role
    serviceAccount: default
    tokenExpirationSeconds: 600
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
  namespace: vso-example
  name: vault-auth
spec:
  vaultAuthGlobalRef:
    name: vault-auth-global
  kubernetes:
    role: local-role

설명

  • VaultAuthGlobal 커스텀 리소스가 defaultAuthMethod 필드로 기본 인증 방식을 kubernetes로 정의해요.
  • VaultAuth 커스텀 리소스가 vaultAuthGlobalRef 필드로 VaultAuthGlobal 커스텀 리소스를 참조해 전역 구성을 상속해요.
  • VaultAuth 커스텀 리소스 스펙의 kubernetes.role 필드가 VaultAuthGlobal 커스텀 리소스의 해당 필드 값을 오버라이드해요. 다른 모든 필드는 VaultAuthGlobal 커스텀 리소스의 spec.kubernetes 필드(예: audiences, mount, serviceAccount, namespace 등)에서 상속됩니다.

Vault 시크릿 커스텀 리소스 정의

오퍼레이터가 단일 Vault 시크릿을 단일 쿠버네티스 시크릿으로 복제하는 데 필요한 구성을 제공해요. 각 지원 CRD는 아래에 문서화된 Vault 시크릿의 한 클래스 에 특화되어 있습니다.

VaultStaticSecret 커스텀 리소스

오퍼레이터가 단일 Vault 정적 시크릿을 단일 쿠버네티스 시크릿으로 동기화하는 데 필요한 구성을 제공해요. 지원 시크릿 엔진: kv-v2, kv-v1

KV 버전 1 시크릿 예제

KV 시크릿 엔진의 kvv1 마운트 경로는 VaultStaticSecret 커스텀 리소스의 spec.mount 아래에 지정돼요. KV 시크릿 엔진 버전 1 구성은 KV Secrets Engine - Version 1 - Setup을 참고하세요. 다음은 시크릿을 가져오기 위해 http://127.0.0.1:8200/v1/kvv1/eng/apikey/google에 요청하게 됩니다.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  namespace: vso-example
  name: vault-static-secret-v1
spec:
  vaultAuthRef: vault-auth
  mount: kvv1
  type: kv-v1
  path: eng/apikey/google
  refreshAfter: 60s
  destination:
    create: true
    name: static-secret1

KV 버전 2 시크릿 예제

VaultStaticSecret 커스텀 리소스의 spec.mount 파라미터로 KV 시크릿 엔진(kvv2) 마운트 경로를 설정해요. 더 고급 KV 시크릿 엔진 버전 2 구성 옵션은 KV Secrets Engine - Version 2 - Setup 가이드를 참고하세요.

예를 들어 http://127.0.0.1:8200/v1/kvv2/eng/apikey/google에 요청해 시크릿을 가져오려면:

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  namespace: vso-example
  name: vault-static-secret-v2
spec:
  vaultAuthRef: vault-auth
  mount: kvv2
  type: kv-v2
  path: eng/apikey/google
  version: 2
  refreshAfter: 60s
  destination:
    create: true
    name: static-secret2

VaultPKISecret 커스텀 리소스

오퍼레이터가 단일 Vault PKI 시크릿을 단일 쿠버네티스 시크릿으로 동기화하는 데 필요한 구성을 제공해요. 지원 시크릿 엔진: pki

PKI 시크릿 엔진의 마운트 경로는 VaultPKISecret 커스텀 리소스의 spec.mount 아래에 지정돼요. PKI 시크릿 엔진 구성은 PKI Secrets Engine - Setup and Usage을 참고하세요. 다음은 TLS 인증서를 생성하기 위해 http://127.0.0.1:8200/v1/pki/issue/default에 요청하게 됩니다.

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultPKISecret
metadata:
  namespace: vso-example
  name: vault-pki
spec:
  vaultAuthRef: vault-auth
  mount: pki
  role: default
  commonName: example.com
  format: pem
  expiryOffset: 1s
  ttl: 60s
  namespace: tenant-1
  destination:
    create: true
    name: pki1

VaultDynamicSecret 커스텀 리소스

오퍼레이터가 단일 Vault 동적 시크릿을 단일 쿠버네티스 시크릿으로 동기화하는 데 필요한 구성을 제공해요. 지원 시크릿 엔진 비완전 목록: databases, aws, azure, gcp, ...

데이터베이스 시크릿 예제

VaultDynamicSecret 커스텀 리소스의 spec.mount로 데이터베이스 시크릿 엔진 마운트 경로(db)를 설정해요. 더 고급 데이터베이스 시크릿 엔진 구성 옵션은 Database Secrets Engine - Setup 가이드를 참고하세요.

예를 들어 새 자격 증명을 생성하기 위해 http://127.0.0.1:8200/v1/db/creds/my-postgresql-role에 요청하려면:

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  namespace: vso-example
  name: vault-dynamic-secret-db
spec:
  vaultAuthRef: vault-auth
  mount: db
  path: creds/my-postgresql-role
  destination:
    create: true
    name: dynamic-db

AWS 시크릿 예제

VaultDynamicSecret 커스텀 리소스의 spec.mount 파라미터로 AWS 시크릿 엔진 마운트 경로(aws)를 설정해요. 더 고급 AWS 시크릿 엔진 구성 옵션은 AWS Secrets Engine - Setup 가이드를 참고하세요.

예를 들어 새 IAM 자격 증명을 생성하기 위해 http://127.0.0.1:8200/v1/aws/creds/my-iam-role에 요청하려면:

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  namespace: vso-example
  name: vault-dynamic-secret-aws-iam
spec:
  vaultAuthRef: vault-auth
  mount: aws
  path: creds/my-iam-role
  destination:
    create: true
    name: dynamic-aws-iam

새 STS 자격 증명을 생성하기 위해 http://127.0.0.1:8200/v1/aws/sts/my-sts-role에 요청하려면:

---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  namespace: vso-example
  name: vault-dynamic-secret-aws-sts
spec:
  vaultAuthRef: vault-auth
  mount: aws
  path: sts/my-sts-role
  destination:
    create: true
    name: dynamic-aws-sts

여기에 언급된 커스텀 리소스에 대한 자세한 내용은 api-reference를 참고하세요.

Vault 클라이언트 캐시

Vault Secrets Operator는 Vault 토큰·리스 같은 Vault 클라이언트 정보를 자신의 네임스페이스의 쿠버네티스 시크릿에 선택적으로 캐시할 수 있어요. 클라이언트 캐시는 리더십 변경을 거쳐도 Vault 토큰과 동적 시크릿 리스를 계속 추적·갱신할 수 있어서 끊김 없는 업그레이드를 지원합니다. 클라이언트 캐시 영속화·암호화는 추가 구성과 Vault 서버 설정이 필요하기 때문에 기본으로 활성화되지 않아요. VSO는 Vault 서버의 transit 시크릿 엔진으로 클라이언트 캐시 암호화를 지원합니다.

암호화된 클라이언트 캐시 가이드가 클라이언트 캐시 암호화를 활성화·구성하는 단계를 안내해요.

즉시 업데이트 (Instant updates)

Enterprise에요. 기능 가용성: VSO v0.8.0

Vault Secrets Operator는 변경 알림용 Vault Events를 구독해 Vault에서 변경이 생기면 쿠버네티스 시크릿을 즉시 업데이트할 수 있어요. 이벤트 메시지 전달이 보장되지 않으므로 갱신 간격(예: refreshAfter) 설정은 여전히 권장됩니다.

지원되는 시크릿 타입:

Vault Enterprise 1.16.3+ 필요. 즉시 업데이트 옵션은 Vault Event Notifications을 사용하기 때문에 Vault Enterprise 1.16.3+가 필요합니다.

즉시 업데이트 가이드가 VaultStaticSecret에 대해 즉시 업데이트를 활성화하는 단계를 안내해요.

튜토리얼

Vault Secrets Operator를 사용하는 종단 간 워크플로를 배우려면 Vault Secrets Operator on Kubernetes 튜토리얼을 참고하세요.

더 알아보기 (Learn more)