Google Kubernetes Engine에서 Secret Manager 부가기능 사용

Secret Manager와 Google Kubernetes Engine(GKE) 간의 통합을 통해 GKE 클러스터에서 사용하는 비밀번호 및 인증서와 같은 민감한 정보를 Secret Manager에 보안 비밀로 저장할 수 있습니다.

이 페이지에서는 Secret Manager 부가기능을 사용하여 Secret Manager에 저장된 보안 비밀을 Kubernetes 포드에 마운트된 볼륨으로 액세스하는 방법을 설명합니다.

이 프로세스는 다음과 같은 단계로 진행됩니다.

새 GKE 클러스터 또는 기존 GKE 클러스터에 Secret Manager 부가기능을 사용 설정합니다.
Secret Manager API에 인증하도록 애플리케이션을 구성합니다.
SecretProviderClass YAML 파일을 사용하여 Kubernetes 포드에 마운트할 보안 비밀을 정의합니다.
보안 비밀을 마운트할 볼륨을 만듭니다. 볼륨이 연결된 후에는 컨테이너의 애플리케이션이 컨테이너 파일 시스템의 데이터에 액세스할 수 있습니다.

Secret Manager 부가기능은 오픈소스 Kubernetes Secrets Store CSI 드라이버 및 Google Secret Manager 제공업체에서 파생됩니다. 오픈소스 Secrets Store CSI 드라이버를 사용하여 보안 비밀에 액세스하는 경우 Secret Manager 부가기능으로 마이그레이션할 수 있습니다. 자세한 내용은 기존 Secrets Store CSI 드라이버에서 마이그레이션을 참조하세요.

이점

Secret Manager 부가기능은 다음과 같은 이점을 제공합니다.

완전 관리형 지원 솔루션을 사용하면 운영 오버헤드 없이 GKE 내에서 Secret Manager 보안 비밀에 액세스할 수 있습니다.
Secret Manager에 저장된 보안 비밀에 액세스하기 위해 커스텀 코드를 작성할 필요가 없습니다.
Secret Manager에서 모든 보안 비밀을 중앙 집중적으로 저장하고 관리하고 Secret Manager 부가기능을 사용하여 GKE 포드에서 선택적으로 보안 비밀에 액세스할 수 있습니다. 이를 통해 CMEK 암호화, 세분화된 액세스 제어, 관리형 순환, 수명 주기 관리, 감사 로그와 같은 Secret Manager에서 제공하는 기능을 사용할 수 있으며, 마운트된 볼륨 형태로 컨테이너에 보안 비밀을 전달하는 등의 Kubernetes 기능을 함께 사용할 수 있습니다.
Secret Manager 부가기능은 Standard 클러스터 및 Autopilot 클러스터 모두에서 지원됩니다.
Secret Manager 부가기능은 Container-Optimized OS 또는 Ubuntu 노드 이미지를 사용하는 노드를 지원합니다.

제한사항

Secret Manager 부가기능에는 다음과 같은 제한사항이 있습니다.

Secret Manager 부가기능은 오픈소스 Secrets Store CSI 드라이버에서 제공되는 다음 기능을 지원하지 않습니다.
- 보안 비밀 자동 순환
- Kubernetes 보안 비밀로 동기화
Secret Manager 부가기능은 Windows Server 노드를 지원하지 않습니다.

시작하기 전에

Enable the Secret Manager and Google Kubernetes Engine APIs.
Enable the APIs
이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update 명령어를 실행하여 최신 버전을 가져옵니다.

Google Cloud SDK 또는 Google Cloud 콘솔을 사용하여 Secret Manager 부가기능을 수동으로 설정할 수 없습니다.

참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region, --location] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.
클러스터가 Linux 노드 이미지와 함께 GKE 버전 1.27.14-gke.1042001 이상을 실행하는지 확인합니다.
GKE Standard 클러스터를 사용하는 경우 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있는지 확인합니다. GKE용 워크로드 아이덴티티 제휴는 기본적으로 Autopilot 클러스터에서 사용 설정됩니다. Kubernetes 포드는 GKE용 워크로드 아이덴티티 제휴를 사용해서 Secret Manager API에 인증합니다.

Secret Manager 부가기능 사용 설정

Standard 클러스터와 Autopilot 클러스터 모두에 Secret Manager 부가기능을 사용 설정할 수 있습니다.

새 GKE 클러스터에서 Secret Manager 부가기능 사용 설정

클러스터를 만들 때 Secret Manager 부가기능을 사용 설정하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
만들기를 클릭합니다.
클러스터 만들기 대화상자에서 구성을 클릭합니다.
탐색 메뉴의 클러스터 섹션에서 보안을 클릭합니다.
Secret Manager 사용 설정 체크박스를 선택합니다.
워크로드 아이덴티티 사용 체크박스를 선택합니다.
계속해서 클러스터를 구성한 다음 만들기를 클릭합니다.

gcloud

{ Standard 클러스터}

새 Standard 클러스터에서 Secret Manager 부가기능을 사용 설정하려면 다음 명령어를 실행합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
LOCATION: 클러스터의 Compute Engine 리전입니다(예: us-central1).
VERSION: 사용하려는 특정 GKE 버전입니다. 클러스터가 GKE 버전 1.27.14-gke.1042001 이상을 실행하는지 확인합니다. 기본 출시 채널에 이 버전이 포함되지 않은 경우 --release-channel 플래그를 사용하여 이 버전이 포함된 출시 채널을 선택합니다.
PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud container clusters create CLUSTER_NAME \
    --enable-secret-manager \
    --location=LOCATION \
    --cluster-version=VERSION \
    --workload-pool=PROJECT_ID.svc.id.goog

Windows(PowerShell)

gcloud container clusters create CLUSTER_NAME `
    --enable-secret-manager `
    --location=LOCATION `
    --cluster-version=VERSION `
    --workload-pool=PROJECT_ID.svc.id.goog

Windows(cmd.exe)

gcloud container clusters create CLUSTER_NAME ^
    --enable-secret-manager ^
    --location=LOCATION ^
    --cluster-version=VERSION ^
    --workload-pool=PROJECT_ID.svc.id.goog

{ Autopilot 클러스터}

새 Autopilot 클러스터에서 Secret Manager 부가기능을 사용 설정하려면 다음 명령어를 실행합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
VERSION: 사용하려는 특정 GKE 버전입니다. 클러스터가 GKE 버전 1.27.14-gke.1042001 이상을 실행하는지 확인합니다. 특정 버전을 설정하려면 새 Autopilot 클러스터의 버전 및 출시 채널 설정을 참조하세요.
LOCATION: 클러스터의 Compute Engine 리전입니다(예: us-central1).

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud container clusters create-auto CLUSTER_NAME \
    --enable-secret-manager \
    --cluster-version=VERSION \
    --location=LOCATION

Windows(PowerShell)

gcloud container clusters create-auto CLUSTER_NAME `
    --enable-secret-manager `
    --cluster-version=VERSION `
    --location=LOCATION

Windows(cmd.exe)

gcloud container clusters create-auto CLUSTER_NAME ^
    --enable-secret-manager ^
    --cluster-version=VERSION ^
    --location=LOCATION

Secret Manager 부가기능을 사용 설정한 후에는 드라이버 및 프로비저닝 도구 이름 secrets-store-gke.csi.k8s.io를 사용하여 Kubernetes 볼륨에서 Secrets Store CSI 드라이버를 사용할 수 있습니다.

기존 GKE 클러스터에서 Secret Manager 부가기능 사용 설정

기존 클러스터에서 Secret Manager 부가기능을 사용 설정하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 클러스터 이름을 클릭합니다.
클러스터 세부정보 페이지의 보안 섹션에서 Secret Manager를 클릭합니다.
Secret Manager 수정 대화상자에서 Secret Manager 사용 설정 체크박스를 선택합니다.
변경사항 저장을 클릭합니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
LOCATION: 클러스터의 Compute Engine 리전입니다(예: us-central1).

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud container clusters update CLUSTER_NAME \
    --enable-secret-manager \
    --location=LOCATION \

Windows(PowerShell)

gcloud container clusters update CLUSTER_NAME `
    --enable-secret-manager `
    --location=LOCATION `

Windows(cmd.exe)

gcloud container clusters update CLUSTER_NAME ^
    --enable-secret-manager ^
    --location=LOCATION ^

Secret Manager 부가기능 설치 확인

Secret Manager 부가기능이 Kubernetes 클러스터에 설치되었는지 확인하려면 다음 명령어를 실행합니다.

  gcloud container clusters describe CLUSTER_NAME --location LOCATION | grep secretManagerConfig -A 1

다음을 바꿉니다.

CLUSTER_NAME: 클러스터의 이름입니다.
LOCATION: 클러스터의 위치입니다(예: us-central1).

애플리케이션을 구성하여 Secret Manager API에 인증

Google Secret Manager 제공업체는 Secret Manager API에 인증할 때 보안 비밀이 마운트된 포드의 워크로드 아이덴티티를 사용합니다. GKE용 워크로드 아이덴티티 제휴를 사용하여 애플리케이션이 Secret Manager API에 인증하도록 허용하려면 다음 단계를 수행합니다.

새 Kubernetes ServiceAccount를 만들거나 보안 비밀을 마운트하려는 포드와 동일한 네임스페이스에서 기존 Kubernetes ServiceAccount를 사용합니다.
Secret Manager에서 보안 비밀에 대한 Identity and Access Management(IAM) 허용 정책을 만듭니다.

구성된 Kubernetes ServiceAccount를 사용하는 포드는 Secret Manager API에 액세스할 때 Kubernetes ServiceAccount에 해당하는 IAM 주 구성원 식별자로 자동 인증됩니다.

새 Kubernetes ServiceAccount 만들기

다음 매니페스트를 service-account.yaml로 저장합니다.
```
apiVersion: v1
kind: ServiceAccount
metadata:
  name: KSA_NAME
  namespace: NAMESPACE
```
다음을 바꿉니다.
- KSA_NAME: 새 Kubernetes ServiceAccount의 이름
- NAMESPACE: ServiceAccount의 Kubernetes 네임스페이스 이름
매니페스트를 적용합니다.
```
kubectl apply -f service-account.yaml
```
새 Kubernetes ServiceAccount를 참조하고 보안 비밀에 액세스할 수 있는 권한을 부여하는 IAM 허용 정책을 만듭니다.
```
gcloud secrets add-iam-policy-binding SECRET_NAME \
    --role=roles/secretmanager.secretAccessor \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME
```
다음을 바꿉니다.
- SECRET_NAME: Secret Manager의 보안 비밀 이름
- PROJECT_NUMBER: 숫자형 Google Cloud 프로젝트 번호
- PROJECT_ID: GKE 클러스터가 포함된 Google Cloud 프로젝트의 프로젝트 ID
- NAMESPACE: ServiceAccount의 Kubernetes 네임스페이스 이름
- KSA_NAME: 기존 Kubernetes ServiceAccount의 이름

기존 Kubernetes ServiceAccount 사용

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

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

다음을 바꿉니다.

SECRET_NAME: Secret Manager의 보안 비밀 이름
PROJECT_NUMBER: 숫자형 Google Cloud 프로젝트 번호
PROJECT_ID: GKE 클러스터가 포함된 Google Cloud 프로젝트의 프로젝트 ID
NAMESPACE: ServiceAccount의 Kubernetes 네임스페이스 이름
KSA_NAME: 기존 Kubernetes ServiceAccount의 이름

마운트할 보안 비밀 정의

Kubernetes 포드에 파일로 마운트할 보안 비밀을 지정하려면 SecretProviderClass YAML 매니페스트를 만들고 마운트할 보안 비밀과 보안 비밀을 마운트할 파일 이름을 나열합니다. 다음 단계를 따르세요.

다음 매니페스트를 app-secrets.yaml로 저장합니다.
```
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: SECRET_PROVIDER_CLASS_NAME
spec:
  provider: gke
  parameters:
    secrets: |
      - resourceName: "projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION"
        path: "FILENAME.txt"
```
다음을 바꿉니다.
- SECRET_PROVIDER_CLASS_NAME: SecretProviderClass 객체 이름입니다.
- PROJECT_ID: 프로젝트 ID입니다.
- SECRET_NAME: 보안 비밀 이름입니다.
- SECRET_VERSION: 보안 비밀 버전입니다.
- FILENAME.txt: 보안 비밀 값이 마운트될 파일 이름입니다. resourceName 및 path 변수를 사용하여 여러 파일을 만들 수 있습니다.
매니페스트를 적용합니다.
```
kubectl apply -f app-secrets.yaml
```
SecretProviderClass 객체가 생성되었는지 확인합니다.
```
kubectl get SecretProviderClasses
```

보안 비밀을 마운트할 볼륨 구성

다음 구성을 my-pod.yaml로 저장합니다.

apiVersion: v1
kind: Pod
metadata:
  name: POD_NAME
  namespace: NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  containers:
  - image: IMAGE_NAME
    imagePullPolicy: IfNotPresent
    name: POD_NAME
    resources:
      requests:
        cpu: 100m
    stdin: true
    stdinOnce: true
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    tty: true
    volumeMounts:
      - mountPath: "/var/secrets"
        name: mysecret
  volumes:
  - name: mysecret
    csi:
      driver: secrets-store-gke.csi.k8s.io
      readOnly: true
      volumeAttributes:
        secretProviderClass: SECRET_PROVIDER_CLASS_NAME

다음을 바꿉니다.

POD_NAME: 보안 비밀이 마운트되는 Kubernetes 포드의 이름입니다.
NAMESPACE: ServiceAccount의 Kubernetes 네임스페이스 이름
KSA_NAME: 애플리케이션을 구성하여 Secret Manager API에 인증 단계에서 설정한 Kubernetes ServiceAccount입니다.
IMAGE_NAME: 컨테이너 이미지의 이름입니다.
SECRET_PROVIDER_CLASS_NAME: SecretProviderClass 객체 이름입니다.

Standard 클러스터에서만 다음을 template.spec 필드에 추가하여 GKE용 워크로드 아이덴티티 제휴를 사용하는 노드 풀에 포드를 배치합니다.

모든 노드가 GKE용 워크로드 아이덴티티 제휴를 사용하므로 이 nodeSelector를 거부하는 Autopilot 클러스터에서 이 단계를 건너뜁니다.
```
spec:
  nodeSelector:
    iam.gke.io/gke-metadata-server-enabled: "true"
```
클러스터에 구성을 적용합니다.
```
kubectl apply -f my-pod.yaml
```

이 단계에서는 CSI 드라이버(secrets-store-gke.csi.k8s.io)를 사용하여 /var/secrets에 볼륨 mysecret을 마운트합니다. 이 볼륨은 제공업체 역할을 하는 SecretProviderClass 객체를 참조합니다.

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

기존 Secrets Store CSI 드라이버 설치에서 Secret Manager 부가기능으로 마이그레이션하는 경우 다음과 같이 포드 매니페스트를 업데이트합니다.

다음 매니페스트에 설명된 대로 SecretProviderClass 및 provider의 이름을 업데이트합니다.

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: app-secrets-gke
spec:
  provider: gke
  parameters:
    secrets: |
      - resourceName: "projects/<project_id>/secrets/<secret_name>/versions/<secret_version>"
        path: "good1.txt"

다음 매니페스트에 설명된 대로 Kubernetes 볼륨의 driver 및 secretProviderClass를 업데이트합니다.

volumes:
  - name: mysecret
    csi:
      driver: secrets-store-gke.csi.k8s.io
      readOnly: true
      volumeAttributes:
        secretProviderClass: "app-secrets-gke"

Secret Manager 부가기능 사용 중지

기존 Standard 클러스터 또는 Autopilot 클러스터에서 Secret Manager 부가기능을 사용 중지하려면 다음 명령어를 실행합니다.

콘솔

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 수정하려는 클러스터 이름을 클릭합니다.
클러스터 세부정보 페이지의 보안 섹션에서 Secret Manager를 클릭합니다.
Secret Manager 수정 대화상자에서 Secret Manager 사용 설정 체크박스를 선택 취소합니다.
변경사항 저장을 클릭합니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
REGION: 클러스터의 Compute Engine 리전입니다(예: us-central1).

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud container clusters update CLUSTER_NAME \
    --no-enable-secret-manager \
    --region=REGION \

Windows(PowerShell)

gcloud container clusters update CLUSTER_NAME `
    --no-enable-secret-manager `
    --region=REGION `

Windows(cmd.exe)

gcloud container clusters update CLUSTER_NAME ^
    --no-enable-secret-manager ^
    --region=REGION ^