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

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

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

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

새 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 부가기능은 linux/arm64 및 linux/amd64 배포를 지원합니다.

제한사항

Secret Manager 부가기능의 이 프리뷰 출시 버전은 오픈소스 Secrets Store CSI 드라이버에서 사용할 수 있는 다음 기능을 지원하지 않습니다.

시작하기 전에

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

참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region, --location] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.
클러스터가 Linux 노드 이미지로 GKE 버전 1.29 이상을 실행하는지 확인합니다. Secret Manager 부가기능은 Windows Server 노드를 지원하지 않습니다.

Secret Manager 부가기능 설치

Standard 클러스터와 Autopilot 클러스터 모두에 Secret Manager 부가기능을 설치할 수 있습니다. Standard 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있는지 확인합니다. GKE용 워크로드 아이덴티티 제휴는 기본적으로 Autopilot 클러스터에서 사용 설정됩니다. Kubernetes 포드는 워크로드 아이덴티티를 사용하여 Secret Manager API에 인증합니다.

새 GKE 클러스터에 Secret Manager 부가기능 설치

클러스터를 만들 때 Secret Manager 부가기능을 설치하려면 다음 단계를 따르세요.

표준 클러스터

새 Standard 클러스터에서 Secret Manager 부가기능을 사용 설정하려면 다음 명령어를 실행합니다.
```
gcloud beta container clusters create CLUSTER_NAME \
    --enable-secret-manager \
    --location=LOCATION \
    --cluster-version=VERSION \
    --workload-pool=PROJECT_ID.svc.id.goog
```
다음을 바꿉니다.
- CLUSTER_NAME: 클러스터의 이름입니다.
- LOCATION: 클러스터의 Compute Engine 리전 또는 영역입니다.
- VERSION: 사용할 특정 GKE 버전입니다. 클러스터가 GKE 버전 1.29 이상을 실행하는지 확인합니다. 기본 출시 채널에 이 버전이 포함되어 있지 않으면 --release-channel 플래그를 사용하여 포함된 출시 채널을 선택합니다.
- PROJECT_ID: Google Cloud 프로젝트의 ID

Autopilot 클러스터

새 Autopilot 클러스터에서 Secret Manager 부가기능을 사용 설정하려면 다음 명령어를 실행합니다.
```
gcloud beta container clusters create-auto CLUSTER_NAME \
    --enable-secret-manager \
    --cluster-version=VERSION \
    --location=LOCATION
```
다음을 바꿉니다.
- CLUSTER_NAME: 클러스터 이름
- VERSION: 사용할 특정 GKE 버전입니다. 클러스터가 GKE 버전 1.29 이상을 실행하는지 확인합니다. 기본 출시 채널에 이 버전이 포함되어 있지 않으면 --release-channel 플래그를 사용하여 포함된 출시 채널을 선택합니다.
- LOCATION: 클러스터에 사용할 리전입니다(예: us-central1).

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

기존 GKE 클러스터에 Secret Manager 부가기능 설치

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

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

다음을 바꿉니다.

CLUSTER_NAME: 기존 클러스터의 이름입니다.
LOCATION: 클러스터에 사용할 리전입니다(예: us-central1).

Secret Manager API에 인증하도록 애플리케이션 구성

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

Identity and Access Management(IAM) 정책을 사용하여 IAM 서비스 계정을 Kubernetes ServiceAccount에 바인딩합니다. 새 Kubernetes ServiceAccount를 만들거나 기존 Kubernetes ServiceAccount를 사용할 수 있으며 기본 Kubernetes ServiceAccount를 포함하여 모든 네임스페이스에서 가능합니다.
IAM 바인딩을 사용하여 IAM 서비스 계정에 Secret Manager의 보안 비밀에 대한 액세스 권한을 부여합니다.

구성된 Kubernetes ServiceAccount를 사용하는 포드는 Secret Manager API에 액세스할 때 자동으로 IAM 서비스 계정으로 인증됩니다.

Kubernetes ServiceAccount를 IAM 서비스 계정에 바인딩

두 서비스 계정 간에 IAM 정책 바인딩을 추가하여 Kubernetes ServiceAccount가 IAM 서비스 계정을 가장할 수 있도록 허용합니다.

새 Kubernetes ServiceAccount 사용

다음 매니페스트를 service-account.yaml로 저장합니다.
```
apiVersion: v1
kind: ServiceAccount
metadata:
  name: KSA_NAME
  namespace: NAMESPACE
  annotations:
    iam.gke.io/gcp-service-account: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
```
다음을 바꿉니다.
- KSA_NAME: 새 Kubernetes ServiceAccount의 이름
- NAMESPACE: ServiceAccount의 Kubernetes 네임스페이스 이름
- GSA_NAME: IAM 서비스 계정의 이름
- PROJECT_ID: IAM 서비스 계정의 Google Cloud 프로젝트 ID
매니페스트를 적용합니다.
```
kubectl apply -f service-account.yaml
```

IAM 서비스 계정을 새 Kubernetes ServiceAccount에 바인딩하려면 다음 명령어를 실행합니다.

gcloud iam service-accounts add-iam-policy-binding \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]" \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

기존 Kubernetes ServiceAccount 사용

IAM 서비스 계정을 기존 Kubernetes ServiceAccount에 바인딩하려면 다음 명령어를 실행합니다.

gcloud iam service-accounts add-iam-policy-binding \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]" \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

다음을 바꿉니다.

KSA_NAME: 기존 Kubernetes ServiceAccount의 이름
NAMESPACE: ServiceAccount의 Kubernetes 네임스페이스 이름
GSA_NAME: IAM 서비스 계정의 이름
PROJECT_ID: IAM 서비스 계정의 Google Cloud 프로젝트 ID

IAM 서비스 계정에 보안 비밀에 액세스할 수 있는 권한 부여

보안 비밀에 액세스하기 위한 권한을 서비스 계정에 부여하려면 다음 명령어를 실행하세요.

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member=serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/secretmanager.secretAccessor

다음을 바꿉니다.

SECRET_NAME: Secret Manager의 보안 비밀 이름
GSA_NAME: IAM 서비스 계정의 이름
PROJECT_ID: IAM 서비스 계정의 Google Cloud 프로젝트 ID

마운트할 보안 비밀 정의

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: default
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 포드의 이름입니다.
KSA_NAME: 워크로드 아이덴티티 서비스 계정 설정 단계에서 설정한 Kubernetes ServiceAccount입니다.
IMAGE_NAME: 컨테이너 이미지의 이름입니다.
SECRET_PROVIDER_CLASS_NAME: SecretProviderClass 객체의 이름입니다.

클러스터에 구성을 적용합니다.
```
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 부가기능을 사용 중지하려면 다음 명령어를 실행하세요.

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

다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름
REGION: 클러스터의 리전(예: us-central1)