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

Este documento mostra como criar listas de permissões que permitem implantar cargas de trabalho privilegiadas nos nós do Autopilot. Essas listas de permissões são armazenadas em buckets do Cloud Storage. Este documento é destinado a administradores e operadores de plataforma que querem isentar cargas de trabalho específicas de clientes 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 cargas de trabalho privilegiadas 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 a postura de segurança. É possível ignorar essas restrições para executar cargas de trabalho privilegiadas específicas instalando listas de permissões que correspondam a essas cargas de trabalho. Por padrão, qualquer cluster do Autopilot ou padrão permite instalar listas de permissões de parceiros do Autopilot e projetos específicos de código aberto.

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ões 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 essas listas de permissões e buckets gerenciados pelo cliente. Os administradores de cluster podem instalar essas listas de permissões para que as cargas de trabalho privilegiadas possam ser executadas no modo Autopilot.

Para mais informações sobre o processo e as pessoas envolvidas, consulte Como funciona o controle de admissão de cargas de trabalho privilegiadas 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, em seguida, 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 Cloud Storage.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. 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. Também é possível criar um cluster do Autopilot para essa tarefa.
  • Verifique se você tem um bucket do Cloud Storage que pode ser usado para armazenar arquivos de lista de permissões. Também é possível 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ões 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 receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Criar e fazer upload de uma WorkloadAllowlist

As listas de permissões são recursos personalizados do WorkloadAllowlist que você define em arquivos YAML. Os campos na especificação de uma WorkloadAllowlist são semelhantes aos campos em uma especificação de pod do Kubernetes. Ao instalar uma lista de permissões no cluster e implantar 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ó pode 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 para o bucket do Cloud Storage, siga estas etapas:

  1. Identifique a carga de trabalho privilegiada para a 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 seu 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://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

  4. Em um editor de texto, crie um arquivo YAML que contenha a WorkloadAllowlist gerada.

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

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

    • Campos específicos oferecem suporte a 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 valores adicionais 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 organização permitirem a instalação de listas de permissões do 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 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 de lista de permissões

O campo matchingCriteria em uma especificação 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 da 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 WorkloadAllowlist 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 as restrições. Outros campos na carga de trabalho, como o campo resources.requests, são ignorados.

Ao instalar 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 padrão que tem 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 listas de permissões do bucket em um cluster, o agente de serviço do GKE no projeto do cluster exige os 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 o 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