이 문서에서는 Autopilot 노드에 권한이 있는 워크로드를 배포할 수 있는 허용 목록을 만드는 방법을 보여줍니다. 이러한 허용 목록은 Cloud Storage 버킷에 저장됩니다. 이 문서는 특정 Kubernetes 워크로드에 대해 기본 Autopilot 보안 제약 조건에서 특정 고객 소유 워크로드를 제외하려는 플랫폼 관리자와 운영자를 대상으로 합니다. 이미 Autopilot의 권한이 있는 워크로드 승인 제어에 대해 잘 알고 있어야 합니다.
Autopilot의 권한이 있는 워크로드 정보
Autopilot 모드는 보안 상태를 개선하기 위해 워크로드에 기본 제약 조건 집합을 적용합니다. 이러한 제약 조건을 우회하여 특정 권한 워크로드를 실행하려면 해당 워크로드에 해당하는 허용 목록을 설치하면 됩니다. 기본적으로 모든 Autopilot 또는 Standard 클러스터에서는 Autopilot 파트너 및 특정 오픈소스 프로젝트의 허용 목록을 설치할 수 있습니다.
자격 요건을 충족하는 GKE 고객은 기본 Autopilot 제약 조건과 호환되지 않는 자체 권한이 있는 워크로드의 허용 목록을 만들고 관리할 수 있습니다. 이러한 허용 목록은 YAML 파일에서 정의하고 Cloud Storage 버킷에 저장하는 WorkloadAllowlist Kubernetes 커스텀 리소스입니다. ID 및 계정 관리자는 조직 정책을 사용하여 이러한 고객 관리 허용 목록 및 버킷을 인식하도록 클러스터를 구성할 수 있습니다. 클러스터 관리자는 권한이 있는 워크로드가 Autopilot 모드에서 실행될 수 있도록 이러한 허용 목록을 설치할 수 있습니다.
프로세스 및 관련 인력에 대한 자세한 내용은 권한이 있는 Autopilot 워크로드 승인 제어 작동 방식을 참고하세요.
시작하기 전에
시작하기 전에 다음 태스크를 수행했는지 확인합니다.
- Google Kubernetes Engine API를 사용 설정합니다. Google Kubernetes Engine API 사용 설정
- 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치했으면
gcloud components update명령어를 실행하여 최신 버전을 가져옵니다. 이전 gcloud CLI 버전에서는 이 문서의 명령어를 실행하지 못할 수 있습니다.
-
Enable the Cloud Storage API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. - 버전 1.35 이상을 실행하는 GKE 클러스터가 있는지 확인합니다. 이 작업을 위해 Autopilot 클러스터를 만들 수도 있습니다.
- 허용 목록 파일을 저장하는 데 사용할 수 있는 Cloud Storage 버킷이 있는지 확인합니다. 이 작업을 위해 버킷을 만들 수도 있습니다.
- Autopilot에서 실행하려는 권한이 있는 워크로드를 정의하는 YAML 매니페스트를 엽니다.
필요한 역할
Cloud Storage에 허용 목록을 저장하고 동기화를 구성하는 데 필요한 권한을 얻으려면 관리자에게 버킷에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
버킷에 허용 목록 저장:
스토리지 객체 사용자 (
roles/storage.objectUser) -
GKE 서비스 에이전트에 액세스 권한 부여:
스토리지 관리자 (
roles/storage.admin)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
WorkloadAllowlist 만들기 및 업로드
허용 목록은 YAML 파일에 정의하는 WorkloadAllowlist 커스텀 리소스입니다. WorkloadAllowlist 사양의 필드는 Kubernetes 포드 사양의 필드와 유사합니다. 클러스터에 허용 목록을 설치하고 권한이 있는 워크로드를 배포하면 GKE에서 설치된 허용 목록에 대해 권한이 있는 워크로드 사양을 검증합니다. 워크로드는 허용 목록 사양의 모든 필드가 워크로드 사양의 해당 필드와 일치하는 경우에만 실행할 수 있습니다.
새 WorkloadAllowlist를 만들고 Cloud Storage 버킷에 업로드하려면 다음 단계를 따르세요.
- 허용 목록에 추가할 권한이 있는 워크로드를 식별합니다.
다음 주석을 포드 사양의
metadata.annotations필드에 추가합니다.cloud.google.com/generate-allowlist: "true"DaemonSet 또는 Deployment와 같은 컨트롤러로 관리되는 포드의 경우
spec.template.metadata.annotations필드에 라벨을 추가합니다.클러스터에서 권한이 있는 워크로드를 만들려고 시도합니다.
kubectl apply -f WORKLOAD_FILE_PATHWORKLOAD_FILE_PATH을 워크로드 매니페스트 파일의 경로로 바꿉니다. GKE에서 WorkloadAllowlist 매니페스트가 포함된 오류 메시지와 함께 워크로드를 거부합니다. 출력은 다음과 비슷합니다.
This workload can be enabled using the following Custom Resource. To be used in-cluster, the WorkloadAllowlist must be uploaded to Google Cloud Storage and then installed using an AllowlistSynchronizer. Refer to https://cloud.google.com/kubernetes-engine/docs/how-to/autopilot-privileged-allowlists. Note that many common partner workloads are already allowlisted. These can be installed directly using an AllowlistSynchronizer. Refer to https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-partners. --- apiVersion: auto.gke.io/v1 kind: WorkloadAllowlist metadata: name: test-pod-allowlist-2025-09-11t22-40-37 annotations: autopilot.gke.io/no-connect: "true" exemptions: - autogke-disallow-privilege matchingCriteria: containers: - name: pause-container2 image: k8s.gcr.io/pause2 securityContext: privileged: true텍스트 편집기에서 생성된 WorkloadAllowlist가 포함된 YAML 파일을 만듭니다.
허용 목록의
metadata.name필드를 설정합니다.선택사항: 유사한 워크로드를 제외할 수 있도록 WorkloadAllowlist를 일반화합니다. 다음 방법 중 하나를 사용하세요.
matchingCriteria.containers[*].image,matchingCriteria.containers[*].args과 같은 특정 필드는 정규 표현식을 지원합니다. 여러 워크로드에서 여러 값과 일치하는 정규 표현식을 사용합니다.matchingCriteria.containers및matchingCriteria.securityContext.capabilities.add과 같은 특정 필드는 WorkloadAllowlist의 값 하위 집합이 있는 워크로드와 일치합니다. WorkloadAllowlist에서 다른 워크로드와 일치하는 값을 추가로 지정합니다.
사용할 수 있는 지원되는 모든 필드와 값에 대한 자세한 내용은 WorkloadAllowlist CustomResourceDefinition을 참고하세요.
조직 정책에서 클러스터의 버킷에서 허용 목록을 설치하도록 허용하는 경우 클러스터 관리자는 다음 작업을 할 수 있습니다.
- 허용 목록 경로를 클러스터에 추가합니다.
- 버킷에서 허용 목록을 설치할 AllowlistSynchronizer를 만듭니다.
클러스터를 구성하고 허용 목록을 설치하는 방법에 관한 자세한 내용은 Autopilot 모드에서 권한이 있는 워크로드 승인 제어를 참고하세요.
허용 목록 구성 예시
WorkloadAllowlist 사양의 matchingCriteria 필드는 Kubernetes 포드 사양과 구조가 비슷합니다. WorkloadAllowlist CustomResourceDefinition은 사용할 수 있는 모든 필드, 값, 표현식의 정보 소스입니다.
이 섹션에서는 다음 속성이 있는 워크로드와 일치하는 허용 목록의 예를 보여줍니다.
- 워크로드의
container-1컨테이너가 권한 모드에서 실행됩니다. - 워크로드가 노드 파일 시스템의
/var/log/디렉터리를 쓰기 모드로 마운트합니다.
예시 워크로드를 검토합니다.
apiVersion: apps/v1 kind: Deployment metadata: name: example-privileged-workload labels: env: dev spec: selector: matchLabels: env: dev template: metadata: labels: env: dev spec: containers: - name: container-1 image: example-image-1 resources: requests: cpu: "400m" memory: "4Gi" # Run the container in privileged mode securityContext: privileged: true - name: container-2 image: example-image-2 volumeMounts: - name: write-varlog mountPath: /logs readOnly: false # Mount a host directory volumes: - name: write-varlog hostPath: path: /var/log type: Directory기본적으로 Autopilot은 이 워크로드를 거부합니다.
예시 WorkloadAllowlist를 검토합니다.
apiVersion: auto.gke.io/v1 kind: WorkloadAllowlist minGKEVersion: 1.32.0-gke.1000000 metadata: name: example-privileged-workload annotations: autopilot.gke.io/no-connect: "true" # List of constraints that the allowlist modifies exemptions: - autogke-disallow-privilege - autogke-no-write-mode-hostpath matchingCriteria: containers: - name: container-1 image: example-image-1 securityContext: privileged: true - name: container-2 image: example-image-2 volumeMounts: - name: write-varlog mountPath: /logs readOnly: false volumes: - name: write-varlog hostPath: path: /var/log이 WorkloadAllowlist에는 다음과 같은 속성이 있습니다.
exemptions필드의 값은 허용 목록에서 우회하는 Autopilot 제약 조건을 지정합니다.matchingCriteria필드의 값은 예시 워크로드가 사용하는 컨테이너와 일반적으로 Autopilot 제약 조건을 위반하는 필드를 지정합니다.
허용 목록에는 제약 조건을 위반하는 필드의 값만 있습니다.
resources.requests필드와 같은 워크로드의 다른 필드는 무시됩니다.
클러스터에 이 예시 WorkloadAllowlist를 설치하면 GKE에서 권한이 있는 워크로드가 해당 클러스터에서 실행되도록 허용합니다. 예를 들어 Autopilot 노드가 있는 Standard 클러스터에서 이 WorkloadAllowlist를 설치하면 권한이 있는 워크로드가 Autopilot 노드에서 실행될 수 있습니다.
GKE 서비스 에이전트에 액세스 권한 부여
클러스터의 버킷에서 허용 목록을 동기화하려면 클러스터 프로젝트의 GKE 서비스 에이전트에 다음 IAM 역할이 필요합니다.
- 스토리지 버킷 뷰어 (
roles/storage.bucketViewer) - 스토리지 객체 뷰어 (
roles/storage.objectViewer)
서비스 에이전트에 이러한 역할을 부여하려면 다음 단계를 따르세요.
클러스터 프로젝트의 프로젝트 번호를 확인합니다.
gcloud projects describe CLUSTER_PROJECT_ID \ --format='value(projectNumber)'roles/storage.bucketViewer역할을 부여합니다.gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME --member=serviceAccount:service-CLUSTER_PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com \ --project=BUCKET_PROJECT_ID \ --role=roles/storage.bucketViewer다음을 바꿉니다.
BUCKET_NAME: Cloud Storage 버킷의 이름입니다.CLUSTER_PROJECT_NUMBER: 이전 단계의 출력에서 가져온 클러스터 프로젝트의 프로젝트 번호입니다.BUCKET_PROJECT_ID: 버킷이 포함된 프로젝트의 ID입니다.
roles/storage.objectViewer역할을 부여합니다.gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME --member=serviceAccount:service-CLUSTER_PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com \ --project=BUCKET_PROJECT_ID \ --role=roles/storage.objectViewer