보안 비밀을 Kubernetes 보안 비밀에 동기화

프리뷰

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 문서에서는 Secret Manager에 저장된 보안 비밀을 Google Kubernetes Engine (GKE) 클러스터 내 Kubernetes 보안 비밀과 동기화하는 방법을 설명합니다.

동기화 프로세스를 사용하면 GKE에서 실행되는 애플리케이션이 환경 변수 또는 볼륨 마운트와 같은 표준 Kubernetes 메서드를 사용하여 Secret Manager의 보안 비밀에 액세스할 수 있습니다. 이는 Secret Manager에 직접 액세스하도록 업데이트할 필요 없이 Kubernetes 보안 비밀 객체에서 보안 비밀을 읽도록 이미 설계된 애플리케이션에 유용합니다.

권장사항: 보안 비밀 동기화 기능은 보안 비밀을 메모리 내 파일로 포드에 직접 마운트하는 Secret Manager 부가기능의 대안입니다. 애플리케이션에서 지원하는 경우 Secret Manager 부가기능을 사용하세요. GKE에서 Secret Manager의 보안 비밀에 액세스하는 더 안전한 방법이기 때문입니다.

시작하기 전에

시크릿을 동기화하기 전에 다음 기본 요건을 완료하세요.

• Enable the Secret Manager and Google Kubernetes Engine APIs.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the APIs

• gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update 명령어를 실행하여 최신 버전을 가져옵니다.

• 실행 중인 GKE 클러스터가 있는지 확인합니다. 이 기능을 사용하려면 GKE 버전 1.34 이상이 필요합니다.

• GKE 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있는지 확인합니다. 이는 인증을 위해 필요합니다. GKE용 워크로드 아이덴티티 제휴는 기본적으로 Autopilot 클러스터에서 사용 설정됩니다.

• GKE 클러스터와 Secret Manager를 관리하는 데 필요한 Identity and Access Management 권한이 있는지 확인합니다.

GKE 클러스터에서 비밀 동기화 사용 설정

새 클러스터를 만들거나 기존 클러스터를 업데이트할 때 시크릿 동기화 기능을 사용 설정합니다. 이 기능은 Standard 및 Autopilot 클러스터 모두에서 사용할 수 있습니다.

새 클러스터에서 비밀 동기화 사용 설정

보안 비밀 동기화를 사용하여 새 클러스터를 만들려면 다음 gcloud CLI 명령어 중 하나를 사용하세요.

표준 클러스터

명령줄에서 Secret Manager를 사용하려면 먼저 Google Cloud CLI 버전 378.0.0 이상을 설치하거나 업그레이드합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

자동 순환 없이 보안 비밀 동기화를 사용 설정합니다.

gcloud beta container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync

자동 순환으로 보안 비밀 동기화를 사용 설정합니다. 기본 간격은 2분입니다.

gcloud beta container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync \
    --enable-secret-sync-rotation

맞춤 순환 간격으로 보안 비밀 동기화를 사용 설정합니다. 최소 간격은 1분입니다.

gcloud beta container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=1m

다음을 바꿉니다.

• CLUSTER_NAME: GKE 클러스터의 이름
• CONTROL_PLANE_LOCATION: 클러스터 컨트롤 플레인의 리전 또는 영역(예: us-central1 또는 us-east1-a)
• PROJECT_ID: Google Cloud 프로젝트 ID

Autopilot 클러스터

명령줄에서 Secret Manager를 사용하려면 먼저 Google Cloud CLI 버전 378.0.0 이상을 설치하거나 업그레이드합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

자동 순환 없이 보안 비밀 동기화를 사용 설정합니다.

gcloud beta container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync

자동 순환으로 보안 비밀 동기화를 사용 설정합니다. 기본 간격은 2분입니다.

gcloud beta container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync \
    --enable-secret-sync-rotation

맞춤 순환 간격으로 보안 비밀 동기화를 사용 설정합니다. 최소 간격은 1분입니다.

gcloud beta container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=1m

다음을 바꿉니다.

• CLUSTER_NAME: GKE 클러스터의 이름
• CONTROL_PLANE_LOCATION: 클러스터 컨트롤 플레인의 리전 또는 영역(예: us-central1 또는 us-east1-a)

기존 클러스터에서 비밀 동기화 사용 설정

비밀 동기화를 사용하여 기존 클러스터를 업데이트하려면 다음 gcloud CLI 명령어 중 하나를 사용하세요.

gcloud

명령줄에서 Secret Manager를 사용하려면 먼저 Google Cloud CLI 버전 378.0.0 이상을 설치하거나 업그레이드합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

기존 클러스터에서 비밀 동기화 사용 설정

gcloud beta container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync

맞춤 간격으로 회전 사용 설정

gcloud beta container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=5m

회전 사용 중지

gcloud beta container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-secret-sync-rotation

다음을 바꿉니다.

• CLUSTER_NAME: GKE 클러스터의 이름
• CONTROL_PLANE_LOCATION: 클러스터 컨트롤 플레인의 리전 또는 영역(예: us-central1 또는 us-east1-a)

보안 비밀 동기화 구성

보안 비밀을 동기화하려면 다음 단계를 완료하세요.

1. 다음 명령어를 사용하여 Kubernetes ServiceAccount를 만듭니다.

   kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
   

   다음을 바꿉니다.

   • KSA_NAME: Kubernetes ServiceAccount의 이름
   • NAMESPACE: ServiceAccount를 만들 Kubernetes 네임스페이스

2. 새 Kubernetes ServiceAccount를 참조하고 ServiceAccount에 보안 비밀에 액세스할 수 있는 권한을 부여하는 IAM 허용 정책을 만듭니다.

   gcloud

   명령줄에서 Secret Manager를 사용하려면 먼저 Google Cloud CLI 버전 378.0.0 이상을 설치하거나 업그레이드합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

   gcloud secrets add-iam-policy-binding SECRET_PROJECT_ID \
      --role=roles/secretmanager.secretAccessor \
      --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_IDsvc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME
   

   다음을 바꿉니다.

   • SECRET_PROJECT_ID: 보안 비밀이 저장된 프로젝트의 ID입니다. 비밀번호가 GKE 클러스터와 동일한 프로젝트에 저장된 경우 PROJECT_ID와 동일할 수 있습니다.
   • PROJECT_NUMBER: Google Cloud 프로젝트 번호
   • PROJECT_ID: Google Cloud 프로젝트 ID
   • NAMESPACE: Kubernetes 네임스페이스
   • KSA_NAME: Kubernetes ServiceAccount의 이름

3. YAML 매니페스트를 사용하여 SecretProviderClass 커스텀 리소스를 만듭니다. SecretProviderClass 리소스는 리소스 이름과 경로를 포함하여 Secret Manager에서 가져올 특정 보안 비밀을 정의합니다. Secret Manager 부가기능은 SecretProviderClass 리소스를 사용하여 마운트할 보안 비밀과 보안 비밀을 마운트할 파일 이름을 나열합니다.

   다음 콘텐츠로 spc.yaml 파일을 만듭니다.

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: SECRET_PROVIDER_CLASS_NAME
     namespace: NAMESPACE
   spec:
     provider: gke
     parameters:
       secrets: |
         -   resourceName: "projects/SECRET_PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION"
             path: "FILENAME.txt"
         -   resourceName: "projects/SECRET_PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION"
             path: "FILENAME1.txt"
   

   다음을 바꿉니다.

   • SECRET_PROVIDER_CLASS_NAME: SecretProviderClass 객체의 이름입니다.
   • NAMESPACE: 이 리소스를 만드는 Kubernetes 네임스페이스입니다.
   • resourceName: Secret Manager의 보안 비밀에 대한 전체 리소스 식별자입니다. 여기에는 프로젝트 ID, 보안 비밀 이름, 버전이 포함되어야 하며 형식은 projects/SECRET_PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION입니다.
     • SECRET_PROJECT_ID: 보안 비밀이 저장된 Google Cloud 프로젝트의 ID입니다. 보안 비밀이 GKE 클러스터와 동일한 프로젝트에 저장된 경우 PROJECT_ID와 동일할 수 있습니다.
     • SECRET_NAME: 보안 비밀 이름입니다.
     • SECRET_VERSION: 보안 비밀 버전입니다. 보안 비밀 버전은 클러스터와 동일한 리전에 있어야 합니다.
   • path: Kubernetes 환경 내에서 보안 비밀 값이 노출될 로컬 파일 이름 또는 별칭입니다. 특정 Secret Manager 버전을 클러스터에서 사용하는 로컬 표현에 연결하는 고유 식별자입니다. 보안 비밀이 SecretSync 리소스를 사용하여 Kubernetes 보안 비밀에 동기화되면 이 경로가 sourcePath 필드에 의해 참조되어 동기화할 보안 비밀 값을 찾습니다. resourceName로 정의된 여러 보안 비밀을 동일한 SecretProviderClass 내의 서로 다른 경로 이름에 매핑할 수 있습니다.

4. 매니페스트를 적용하려면 다음 명령어를 실행합니다.

   kubectl apply -f spc.yaml
   

5. YAML 매니페스트를 사용하여 SecretSync 커스텀 리소스를 만듭니다. 이 리소스는 동기화 컨트롤러에 SecretProviderClass에 정의된 콘텐츠를 기반으로 Kubernetes 보안 비밀을 만들거나 업데이트하도록 지시합니다.

   다음 콘텐츠로 secret-sync.yaml 파일을 만듭니다.

   apiVersion: secret-sync.gke.io/v1
   kind: SecretSync
   metadata:
     name: KUBERNETES_SECRET_NAME
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     secretProviderClassName: SECRET_PROVIDER_CLASS_NAME
     secretObject:
       type: KUBERNETES_SECRET_TYPE
       data:
         -   sourcePath: "FILENAME.txt"
             targetKey: "TARGET_KEY1"
         -   sourcePath: "FILENAME1.txt"
             targetKey: "TARGET_KEY2"
   

   다음을 바꿉니다.

   • KUBERNETES_SECRET_NAME: SecretSync 리소스에 의해 생성될 새 Kubernetes 보안 비밀에 지정할 이름입니다.
   • NAMESPACE: 새 리소스가 생성되는 Kubernetes 네임스페이스입니다. SecretProviderClass와 동일한 네임스페이스여야 합니다.
   • KSA_NAME: SecretSync 컨트롤러가 타겟 Kubernetes 보안 비밀을 생성하고 업데이트하는 데 사용하는 Kubernetes ServiceAccount의 이름입니다. 이 ServiceAccount에는 Secret Manager에서 외부 보안 비밀에 액세스하는 데 필요한 권한이 있어야 합니다.
   • SECRET_PROVIDER_CLASS_NAME: 이전 단계에서 만든 SecretProviderClass 객체의 이름입니다. SecretSync 리소스는 이를 사용하여 보안 비밀의 올바른 구성을 찾습니다.
   • KUBERNETES_SECRET_TYPE: 생성할 Kubernetes 보안 비밀의 유형입니다(예: Opaque, tls, docker-registry). 이는 Kubernetes가 보안 비밀의 데이터를 처리하는 방식을 결정합니다.
   • sourcePath: 가져올 보안 비밀 데이터를 식별하는 로컬 파일 이름 또는 별칭 (SecretProviderClass의 path 필드 값)입니다. SecretSync 컨트롤러는 이 sourcePath를 사용하여 특정 보안 비밀 콘텐츠를 요청하고 새 Kubernetes 보안 비밀로 변환합니다.
   • targetKey: 새로 생성되는 Kubernetes 보안 비밀의 data 섹션에서 사용될 키입니다. 이는 sourcePath를 사용하여 가져온 보안 비밀 콘텐츠가 최종 Kubernetes 보안 비밀 객체에서 이름이 지정되고 저장되는 방식을 정의합니다. 데이터 배열에 여러 항목을 사용하면 동일한 타겟 보안 비밀 내에서 여러 키-값 쌍을 정의할 수 있습니다.

6. 매니페스트를 적용하려면 다음 명령어를 실행합니다.

   kubectl apply -f secret-sync.yaml
   

   동기화 컨트롤러는 지정된 네임스페이스에 Kubernetes 보안 비밀을 만듭니다. 이 보안 비밀에는 Secret Manager에서 매핑된 데이터가 포함됩니다.

7. Kubernetes 보안 비밀이 생성되었는지 확인합니다.

   kubectl get secret KUBERNETES_SECRET_NAME -n NAMESPACE -o yaml
   

   다음을 바꿉니다.

   • KUBERNETES_SECRET_NAME: 새 Kubernetes 보안 비밀의 이름
   • NAMESPACE: 새 보안 비밀이 생성되는 Kubernetes 네임스페이스

8. 동기화 문제를 해결하려면 다음 명령어를 사용하세요.

   kubectl describe secretSync KUBERNETES_SECRET_NAME -n NAMESPACE
   

   다음을 바꿉니다.

   • KUBERNETES_SECRET_NAME: 새 Kubernetes 보안 비밀의 이름
   • NAMESPACE: 새 보안 비밀이 있어야 하는 Kubernetes 네임스페이스

보안 비밀 순환 관리

클러스터에서 --enable-secret-sync-rotation 플래그를 사용 설정하면 동기화 컨트롤러가 SecretProviderClass 리소스에 지정된 보안 비밀의 새 버전을 주기적으로 Secret Manager에서 확인합니다. --secret-sync-rotation-interval 플래그는 컨트롤러가 업데이트를 확인하는 빈도를 결정합니다.

컨트롤러가 Secret Manager에서 새 보안 비밀 버전을 감지하면 컨트롤러는 해당 Kubernetes 보안 비밀을 업데이트합니다. 컨트롤러는 보안 비밀 콘텐츠의 해시를 비교하여 변경사항이 발생한 경우에만 보안 비밀을 업데이트합니다.

이러한 보안 비밀을 사용하는 애플리케이션은 업데이트된 보안 비밀 값을 Kubernetes 보안 비밀에서 감지하고 다시 로드해야 합니다. 이러한 처리는 애플리케이션의 디자인에 따라 결정됩니다.

보안 비밀 동기화 사용 중지

보안 비밀 동기화를 사용 중지하려면 다음 gcloud CLI 명령어를 실행합니다.

gcloud

명령줄에서 Secret Manager를 사용하려면 먼저 Google Cloud CLI 버전 378.0.0 이상을 설치하거나 업그레이드합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

gcloud beta container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-secret-sync

다음을 바꿉니다.

• CLUSTER_NAME: GKE 클러스터의 이름
• CONTROL_PLANE_LOCATION: 클러스터 컨트롤 플레인의 리전 또는 영역(예: us-central1 또는 us-east1-a)

이 명령어는 동기화 컨트롤러를 중지합니다. 이미 생성된 Kubernetes 보안 비밀은 삭제되지 않습니다. 동기화된 Kubernetes 보안 비밀이 더 이상 필요하지 않으면 수동으로 삭제해야 합니다.

동기화된 보안 비밀 삭제

동기화된 Kubernetes 보안 비밀을 삭제하려면 다음 명령어를 사용하여 SecretSync 리소스를 삭제합니다.

    kubectl delete secretsync KUBERNETES_SECRET_NAME --namespace NAMESPACE

다음을 바꿉니다.

• KUBERNETES_SECRET_NAME: Kubernetes 보안 비밀 이름
• NAMESPACE: 보안 비밀이 있는 Kubernetes 네임스페이스

기존 Secrets Store CSI 드라이버에서 마이그레이션

기존 Secrets Store CSI 드라이버 설치에서 마이그레이션하는 경우 다음 단계를 따르세요.

1. SecretProviderClass에서 provider 필드를 gcp에서 gke로 업데이트합니다. 다음 예시에서는 provider 필드를 업데이트하는 방법을 보여줍니다.

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: app-secrets-gke
   spec:
     provider: gke
     parameters:
       secrets: |
         -   resourceName: "projects/87654321/secrets/api-key-secret/versions/2"
             path: "good1.txt"
   

2. SecretSync 리소스를 만듭니다. 다음 샘플 구성을 사용합니다.

   apiVersion: secret-sync.gke.io/v1
   kind: SecretSync
   metadata:
     name: my-kube-secret
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     secretProviderClassName: my-app-secrets
     secretObject:
       type: Opaque # Or other Kubernetes Secret types
       data:
         -   sourcePath: "my-secret.txt"
             targetKey: "USERNAME"
         -   sourcePath: "another-secret.txt"
             targetKey: "PASSWORD"
   

보안 고려사항

Secret Manager는 IAM을 사용한 액세스 제어, 고객 관리 암호화 키 (CMEK), 감사 로깅과 같은 보안 기능을 제공합니다. 보안 비밀은 Secret Manager 내에서 저장 시와 전송 시 암호화됩니다. 보안 비밀을 Kubernetes 보안 비밀에 동기화하면 클러스터 내 보안은 GKE 클러스터의 구성에 따라 달라집니다. 다음 사항을 고려하세요.

• 스토리지: Kubernetes 보안 비밀은 GKE의 기본 데이터 스토어인 etcd에 저장됩니다. 기본적으로 GKE는 저장 데이터를 암호화합니다. 보안을 강화하려면 Cloud Key Management Service(Cloud KMS)에서 관리하는 키를 사용하여 애플리케이션 레이어에서 Kubernetes 보안 비밀을 암호화하세요. 보안 비밀을 암호화하면 민감한 워크로드에 추가 보안 레이어가 제공됩니다.

• 액세스 제어: GKE는 역할 기반 액세스 제어 (RBAC)를 사용하여 프로젝트 및 클러스터 내의 리소스에 대한 액세스를 관리하는 여러 가지 옵션을 지원합니다. RBAC 권한이 너무 광범위하면 의도하지 않은 워크로드나 사용자에게 보안 비밀이 노출될 수 있습니다. 최소 권한의 원칙에 따라 액세스 권한을 부여하고 Secret Manager와 Kubernetes 보안 비밀에 대한 액세스 권한을 정기적으로 감사합니다.

• 환경 변수: 보안을 강화하려면 Kubernetes 보안 비밀을 환경 변수로 사용하는 대신 볼륨으로 마운트하세요. 이렇게 하면 실수로 로깅되거나 다른 프로세스에 노출될 위험이 줄어듭니다.

다음 단계

• Kubernetes 보안 비밀을 살펴봅니다.
• 워크로드 아이덴티티를 이해합니다.