Criar listas de permissões para cargas de trabalho privilegiadas no Autopilot

Neste documento, mostramos como criar listas de permissão que permitem implantar cargas de trabalho privilegiadas nos nós do Autopilot. Você armazena essas listas de permissão em buckets do Cloud Storage. Este documento é destinado a administradores e operadores de plataforma que querem isentar cargas de trabalho específicas de propriedade do cliente das restrições de segurança padrão do Autopilot para cargas de trabalho específicas do Kubernetes. Você já precisa estar familiarizado com o controle de admissão de carga de trabalho privilegiada no Autopilot.

Sobre cargas de trabalho privilegiadas no Autopilot

O modo Autopilot aplica um conjunto padrão de restrições às cargas de trabalho para melhorar sua postura de segurança. É possível ignorar essas restrições para executar cargas de trabalho privilegiadas específicas instalando listas de permissão correspondentes a essas cargas de trabalho. Por padrão, qualquer cluster do Autopilot ou Standard permite instalar listas de permissões de parceiros do Autopilot e projetos de código aberto específicos.

Os clientes qualificados do GKE podem criar e gerenciar listas de permissões para as próprias cargas de trabalho privilegiadas que não são compatíveis com as restrições padrão do Autopilot. Essas listas de permissão são recursos personalizados do Kubernetes WorkloadAllowlist que você define em arquivos YAML e armazena em buckets do Cloud Storage. Os administradores de identidade e conta usam políticas da organização para permitir que você configure seus clusters para reconhecer as listas de permissão e os buckets gerenciados pelo cliente. Os administradores de cluster podem instalar essas listas de permissão para que as cargas de trabalho privilegiadas sejam executadas no modo Autopilot.

Para mais informações sobre o processo e as pessoas envolvidas, consulte Como funciona o controle de admissão de carga de trabalho privilegiada do Autopilot.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ative a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.

  • Ative a API Storage do Cloud Storage, se ela ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  • Verifique se você tem um cluster do GKE que executa a versão 1.35 ou mais recente. Você também pode criar um cluster do Autopilot para essa tarefa.
  • Verifique se você tem um bucket do Cloud Storage que pode usar para armazenar arquivos de lista de permissões. Você também pode criar um bucket para essa tarefa.
  • Abra o manifesto YAML que define a carga de trabalho privilegiada que você quer executar no Autopilot.

Funções exigidas

Para receber as permissões necessárias para armazenar listas de permissão no Cloud Storage e configurar a sincronização, peça ao administrador para conceder a você os seguintes papéis do IAM no bucket:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar e fazer upload de uma WorkloadAllowlist

As listas de permissões são recursos personalizados WorkloadAllowlist definidos em arquivos YAML. Os campos na especificação de uma WorkloadAllowlist são semelhantes aos campos em uma especificação de pod do Kubernetes. Quando você instala uma lista de permissões no cluster e implanta uma carga de trabalho privilegiada, o GKE valida a especificação da carga de trabalho privilegiada em relação à lista de permissões instalada. A carga de trabalho só poderá ser executada se todos os campos na especificação da lista de permissões corresponderem aos campos correspondentes na especificação da carga de trabalho.

Para criar uma nova WorkloadAllowlist e fazer upload dela no bucket do Cloud Storage, siga estas etapas:

  1. Identifique a carga de trabalho privilegiada para adicionar à lista de permissões.

  2. Adicione a seguinte anotação ao campo metadata.annotations na especificação do pod:

    cloud.google.com/generate-allowlist: "true"

    Para pods gerenciados por um controlador, como um DaemonSet ou uma implantação, adicione a anotação ao campo spec.template.metadata.annotations.

  3. Tente criar a carga de trabalho privilegiada no cluster:

    kubectl apply -f WORKLOAD_FILE_PATH

    Substitua WORKLOAD_FILE_PATH pelo caminho para o arquivo de manifesto da carga de trabalho. O GKE rejeita a carga de trabalho com uma mensagem de erro que inclui um manifesto WorkloadAllowlist. O resultado será o seguinte:

    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://docs.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://docs.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

  4. Em um editor de texto, crie um arquivo YAML que contenha o WorkloadAllowlist gerado.

  5. Defina o campo metadata.name da lista de permissões.

  6. Opcional: generalizar a WorkloadAllowlist para que ela possa isentar cargas de trabalho semelhantes. Use um dos seguintes métodos:

    • Alguns campos específicos aceitam expressões regulares, como matchingCriteria.containers[*].image e matchingCriteria.containers[*].args. Use uma expressão regular que corresponda a vários valores em diferentes cargas de trabalho.

    • Campos específicos, como matchingCriteria.containers e matchingCriteria.securityContext.capabilities.add, correspondem a qualquer carga de trabalho com um subconjunto dos valores da WorkloadAllowlist. Na WorkloadAllowlist, especifique outros valores para corresponder a outras cargas de trabalho.

    Para mais informações sobre todos os campos e valores compatíveis que você pode usar, consulte a WorkloadAllowlist CustomResourceDefinition.

  7. Faça upload do arquivo de manifesto para o bucket do Cloud Storage.

Se as políticas da sua organização permitirem a instalação de listas de permissão do seu bucket em clusters, os administradores de cluster poderão fazer o seguinte:

  1. Adicione os caminhos da lista de permissões a um cluster.
  2. Crie um AllowlistSynchronizer para instalar as listas de permissões do seu bucket.

Para mais informações sobre como configurar um cluster e instalar listas de permissões, consulte Controlar a admissão de cargas de trabalho privilegiadas no modo Autopilot.

Exemplo de configuração da lista de permissões

O campo matchingCriteria em uma especificação de WorkloadAllowlist tem uma estrutura semelhante à especificação de pod do Kubernetes. A WorkloadAllowlist CustomResourceDefinition é a fonte da verdade para todos os campos, valores e expressões que você pode usar.

Esta seção mostra um exemplo de lista de permissões que corresponde a uma carga de trabalho com as seguintes propriedades:

  • O contêiner container-1 na carga de trabalho é executado no modo privilegiado.
  • A carga de trabalho monta o diretório /var/log/ do sistema de arquivos do nó no modo de gravação.

  1. Revise o exemplo de carga de trabalho:

    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

    Por padrão, o Autopilot rejeita essa carga de trabalho.

  2. Revise o exemplo de 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

    Essa lista de permissões de carga de trabalho tem as seguintes propriedades:

    • Os valores no campo exemptions especificam as restrições do Autopilot que a lista de permissões ignora.
    • Os valores no campo matchingCriteria especificam os contêineres que a carga de trabalho de exemplo usa e os campos que normalmente violariam as restrições do Autopilot.

    A lista de permissões tem apenas os valores dos campos que violam restrições. Outros campos na carga de trabalho, como resources.requests, são ignorados.

Quando você instala esse exemplo de WorkloadAllowlist em um cluster, o GKE permite que a carga de trabalho privilegiada seja executada nesse cluster. Por exemplo, em um cluster Standard com nós do Autopilot, a instalação dessa WorkloadAllowlist permite que a carga de trabalho privilegiada seja executada nos nós do Autopilot.

Conceder acesso ao agente de serviço do GKE

Para sincronizar as listas de permissões do bucket em um cluster, o agente de serviço do GKE no projeto do cluster precisa dos seguintes papéis do IAM:

Para conceder esses papéis ao agente de serviço, siga estas etapas:

  1. Encontre o número do projeto do cluster:

    gcloud projects describe CLUSTER_PROJECT_ID \
    --format='value(projectNumber)'

  2. Conceda o papel roles/storage.bucketViewer:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:service-CLUSTER_PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com \
    --project=BUCKET_PROJECT_ID \
    --role=roles/storage.bucketViewer

    Substitua:

    • BUCKET_NAME: o nome do bucket do Cloud Storage.
    • CLUSTER_PROJECT_NUMBER: o número do projeto do cluster, da saída da etapa anterior.
    • BUCKET_PROJECT_ID: o ID do projeto que contém seu bucket.

  3. Conceda o papel roles/storage.objectViewer:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:service-CLUSTER_PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com \
    --project=BUCKET_PROJECT_ID \
    --role=roles/storage.objectViewer

A seguir