외부 보안 비밀 운영자 사용

이 페이지에서는 외부 보안 비밀 연산자 (ESO)를 사용하여 Secret Manager의 보안 비밀을 Google Distributed Cloud Connected Clusters에 동기화하는 방법을 설명합니다.

외부 보안 비밀 연산자는 외부 보안 비밀 관리 시스템을 통합하는 오픈소스 Kubernetes 연산자입니다. 연산자는 외부 API에서 정보를 읽고 값을 Kubernetes 보안 비밀에 자동으로 삽입합니다.

기본 요건

외부 보안 비밀 연산자를 사용하려면 다음을 수행해야 합니다.

  • 작동하는 Distributed Cloud Connected Clusters를 만듭니다.
  • 프로젝트에서 다음 API가 사용 설정되어 있는지 확인합니다. Google Cloud API 사용 설정에 관한 자세한 내용은 서비스 사용 설정을 참조하세요.
    • secretmanager.googleapis.com
    • iamcredentials.googleapis.com

  • 다음 명령줄 도구가 설치되었는지 확인합니다.

    • 와 상호작용하는 명령줄 도구인 gcloud가 포함된 최신 버전의 Google Cloud CLI Google Cloud
    • kubectl

    와의 상호작용을 위해 Cloud Shell을 셸 환경으로 사용하는 경우 Google Cloud이러한 도구가 자동으로 설치됩니다.

  • 프로젝트에 사용할 수 있도록 gcloud CLI를 초기화했는지 확인합니다.

  • 클러스터에서 워크로드 아이덴티티 제휴를 사용 설정합니다. 워크로드 아이덴티티 풀은 자동으로 사용할 수 있으며 PROJECT_ID.svc.id.goog 형식을 따릅니다.

  • 클러스터에 외부 보안 비밀 연산자를 설치합니다. 설치 안내는 외부 보안 비밀 연산자 문서를 참조하세요. 연산자를 external-secrets와 같은 전용 네임스페이스에 설치하는 것이 좋습니다. kube-system 또는 gke-system과 같은 시스템 관리 네임스페이스에는 설치하지 마세요.

Distributed Cloud Connected Clusters는 생성된 프로젝트의 Fleet에 자동으로 등록됩니다.

인증

외부 보안 비밀 연산자는 Secret Manager에 액세스하기 위해 인증이 필요합니다. Distributed Cloud Connected는 Fleet 워크로드 아이덴티티 제휴를 사용하여 워크로드가 Google Cloud API에 인증할 수 있도록 합니다.

외부 보안 비밀 연산자의 인증을 구성하려면 다음 안내를 따르세요.

  1. 워크로드 아이덴티티 클러스터 인증의 안내에 따라 클러스터와 Google Cloud 간에 트러스트 관계를 설정합니다.
  2. 외부 보안 비밀 연산자가 사용하는 Google 서비스 계정에 액세스하려는 보안 비밀에 대한 Secret Manager 보안 비밀 접근자(roles/secretmanager.secretAccessor) 역할이 있는지 확인합니다.

  3. 워크로드 구성 안내에 따라 워크로드 아이덴티티 제휴를 사용하도록 외부 보안 비밀 연산자 포드를 구성합니다.

    대부분의 고객은 인증에 워크로드 아이덴티티 제휴를 사용합니다. 워크로드 아이덴티티 제휴를 구성하려면 연산자가 사용하는 Kubernetes ServiceAccount에 Google 서비스 계정으로 주석을 추가해야 합니다. 이 주석을 추가하려면 kubectl annotate 명령어를 실행합니다.

    kubectl annotate serviceaccount KSA_NAME \
    --namespace OPERATOR_NAMESPACE \
    iam.gke.io/gcp-service-account=GSA_EMAIL

    또는 ServiceAccount YAML에 주석을 추가할 수 있습니다.

    apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    iam.gke.io/gcp-service-account: GSA_EMAIL
  name: KSA_NAME
  namespace: OPERATOR_NAMESPACE

    다음 값을 바꿉니다.

    • KSA_NAME: 연산자가 사용하는 Kubernetes ServiceAccount의 이름
    • OPERATOR_NAMESPACE: 연산자를 설치한 네임스페이스
    • GSA_EMAIL: Google 서비스 계정의 이메일 주소

  4. 연산자 포드에 사용자 인증 정보 구성 파일을 제공합니다. 자세한 내용은 다음에서 확인하세요. 워크로드 구성

보안 비밀을 동기화하는 ESO 리소스 만들기

인증을 구성한 후 외부 보안 비밀 연산자 리소스를 만들어 보안 비밀을 동기화할 수 있습니다.

SecretStore 만들기

SecretStore는 외부 보안 비밀 관리 시스템에 액세스하는 방법을 지정합니다. 외부 보안 비밀 연산자와 동일한 네임스페이스 또는 애플리케이션 네임스페이스에서 SecretStore 리소스를 만들 수 있습니다. 자세한 내용은 SecretStore의 SecretStore를 참조하세요.

  1. 다음 콘텐츠로 secret-store.yaml이라는 파일을 만듭니다.

    apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: gcp-store
  namespace: NAMESPACE
spec:
  provider:
    gcpsm:
      projectID: PROJECT_ID

    다음 값을 바꿉니다.

    • NAMESPACE: SecretStore를 만들 네임스페이스
    • PROJECT_ID: 보안 비밀이 저장된 Google Cloud 프로젝트 ID

  2. kubectl apply 명령어를 사용하여 매니페스트를 적용합니다.

    kubectl apply -f secret-store.yaml

ClusterSecretStore 만들기

ClusterSecretStore는 ExternalSecret 리소스가 모든 네임스페이스에서 사용할 수 있는 클러스터 범위 리소스입니다. 자세한 내용은 Kubernetes 문서의 ClusterSecretStore 를 참조하세요.

  1. 다음 콘텐츠로 cluster-secret-store.yaml이라는 파일을 만듭니다.

    apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: gcp-cluster-store
spec:
  provider:
    gcpsm:
      projectID: PROJECT_ID

    PROJECT_ID를 보안 비밀이 저장된 Google Cloud 프로젝트 ID로 바꿉니다.

  2. 매니페스트를 적용합니다.

    kubectl apply -f cluster-secret-store.yaml

ExternalSecret 만들기

ExternalSecret는 가져올 데이터와 클러스터에 저장할 위치를 선언합니다. 애플리케이션 포드가 결과 Kubernetes 보안 비밀을 사용하는 네임스페이스에서 ExternalSecret 리소스를 만듭니다. 자세한 내용은 Kubernetes 문서의 ExternalSecret 를 참조하세요.

  1. 다음 콘텐츠로 external-secret.yaml이라는 파일을 만듭니다.

    apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: EXTERNAL_SECRET
  namespace: NAMESPACE
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: gcp-store
  target:
    name: K8S_SECRET_NAME
    creationPolicy: Owner
  data:
  - secretKey: K8S_SECRET_KEY
    remoteRef:
      key: SECRET_NAME

    다음 값을 바꿉니다.

    • EXTERNAL_SECRET: ExternalSecret 리소스의 이름
    • NAMESPACE: SecretStore를 만든 네임스페이스
    • K8S_SECRET_NAME: ESO에서 만들 Kubernetes 보안 비밀의 이름
    • K8S_SECRET_KEY: Kubernetes 보안 비밀 데이터의 키
    • SECRET_NAME:Google Cloud Secret Manager의 보안 비밀 이름

    ClusterSecretStore를 사용하는 경우 kind: ClusterSecretStore를 설정하고 name를 secretStoreRef에서 업데이트합니다.

  2. 매니페스트를 적용합니다.

    kubectl apply -f external-secret.yaml

JSON 보안 비밀에서 여러 키 동기화

Secret Manager의 보안 비밀에 JSON 문자열이 포함되어 있는 경우 모든 키를 Kubernetes 보안 비밀의 개별 항목으로 추출할 수 있습니다.

  1. 다음 콘텐츠로 external-secret-json.yaml이라는 파일을 만듭니다.

    apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: EXTERNAL_SECRET
  namespace: NAMESPACE
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: gcp-store
  target:
    name: K8S_SECRET_NAME
    creationPolicy: Owner
  dataFrom:
  - extract:
      key: SECRET_NAME

  2. 매니페스트를 적용합니다.

    kubectl apply -f external-secret-json.yaml

JSON 보안 비밀의 각 키-값 쌍은 결과 Kubernetes 보안 비밀의 키-값 쌍에 매핑됩니다.

문제 해결

보안 비밀이 동기화되지 않으면 다음 단계에 따라 문제를 해결합니다.

  1. kubectl get 명령어를 사용하여 ExternalSecret 리소스의 상태를 확인합니다.

    kubectl get externalsecret EXTERNAL_SECRET -n NAMESPACE -o yaml

    오류 메시지 또는 실패한 조건이 있는지 status 섹션을 검사합니다.

  2. kubectl logs 명령어를 사용하여 외부 보안 비밀 연산자 컨트롤러 포드의 로그를 확인합니다.

    kubectl logs -l app.kubernetes.io/name=external-secrets -n OPERATOR_NAMESPACE

  3. 연산자가 사용하는 Kubernetes ServiceAccount에 Google 서비스 계정 이메일로 올바르게 주석이 추가되어 있는지 확인합니다. 자세한 내용은 클러스터의 워크로드 아이덴티티 제휴를 참조하세요.

  4. Google 서비스 계정에 필요한 권한이 있고 워크로드 아이덴티티 제휴가 올바르게 구성되어 있는지 확인합니다. 자세한 내용은 클러스터의 워크로드 아이덴티티 제휴를 참조하세요.

다음 단계