Crea listas de entidades permitidas para cargas de trabajo con privilegios en Autopilot

En este documento, se muestra cómo crear listas de entidades permitidas que te permiten implementar cargas de trabajo con privilegios en tus nodos de Autopilot. Almacenas estas listas de entidades permitidas en buckets de Cloud Storage. Este documento está dirigido a los administradores y operadores de plataformas que desean eximir cargas de trabajo específicas propiedad del cliente de las restricciones de seguridad predeterminadas de Autopilot para cargas de trabajo específicas de Kubernetes. Ya debes conocer el control de admisión de cargas de trabajo con privilegios en Autopilot.

Acerca de las cargas de trabajo con privilegios en Autopilot

El modo Autopilot aplica un conjunto predeterminado de restricciones a las cargas de trabajo para mejorar tu postura de seguridad. Puedes omitir estas restricciones para ejecutar cargas de trabajo privilegiadas específicas. Para ello, instala listas de entidades permitidas que correspondan a esas cargas de trabajo. De forma predeterminada, cualquier clúster de Autopilot o Standard te permite instalar listas de entidades permitidas de socios de Autopilot y proyectos específicos de código abierto.

Los clientes aptos de GKE pueden crear y administrar listas de entidades permitidas para sus propias cargas de trabajo privilegiadas que no son compatibles con las restricciones predeterminadas de Autopilot. Estas listas de entidades permitidas son recursos personalizados de Kubernetes WorkloadAllowlist que defines en archivos YAML y almacenas en buckets de Cloud Storage. Los administradores de identidades y cuentas usan políticas de la organización para permitirte configurar tus clústeres de modo que reconozcan estas listas de entidades permitidas y estos buckets administrados por el cliente. Los administradores de clústeres pueden instalar estas listas de entidades permitidas para que las cargas de trabajo privilegiadas se puedan ejecutar en modo Autopilot.

Para obtener más información sobre el proceso y las personas involucradas, consulta Cómo funciona el control de admisión de cargas de trabajo privilegiadas de Autopilot.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

  • Habilita la API de Google Kubernetes Engine.
    • Habilitar la API de Google Kubernetes Engine
  • Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos que se indican en este documento.

  • Habilita la API de Cloud Storage.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar la API

  • Asegúrate de tener un clúster de GKE que ejecute la versión 1.35 o posterior. También puedes crear un clúster de Autopilot para esta tarea.
  • Verifica que tengas un bucket de Cloud Storage que puedas usar para almacenar archivos de la lista de entidades permitidas. También puedes crear un bucket para esta tarea.
  • Abre el manifiesto YAML que define la carga de trabajo con privilegios que deseas ejecutar en Autopilot.

Roles obligatorios

Para obtener los permisos que necesitas para almacenar listas de entidades permitidas en Cloud Storage y configurar la sincronización, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu bucket:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Crea y sube una WorkloadAllowlist

Las listas de entidades permitidas son recursos personalizados de WorkloadAllowlist que se definen en archivos YAML. Los campos de la especificación de un WorkloadAllowlist son similares a los de una especificación de Pod de Kubernetes. Cuando instalas una lista de entidades permitidas en tu clúster y, luego, implementas una carga de trabajo con privilegios, GKE valida la especificación de la carga de trabajo con privilegios en función de la lista de entidades permitidas instalada. La carga de trabajo solo se puede ejecutar si todos los campos de la especificación de la lista de entidades permitidas coinciden con los campos correspondientes de la especificación de la carga de trabajo.

Para crear una nueva WorkloadAllowlist y subirla a tu bucket de Cloud Storage, sigue estos pasos:

  1. Identifica la carga de trabajo con privilegios que se incluirá en la lista de entidades permitidas.

  2. Agrega la siguiente anotación al campo metadata.annotations en la especificación del Pod:

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

    Para los Pods que administra un controlador, como un DaemonSet o una Deployment, agrega la anotación al campo spec.template.metadata.annotations.

  3. Intenta crear la carga de trabajo privilegiada en tu clúster:

    kubectl apply -f WORKLOAD_FILE_PATH

    Reemplaza WORKLOAD_FILE_PATH por la ruta de acceso al archivo de manifiesto de la carga de trabajo. GKE rechaza la carga de trabajo con un mensaje de error que incluye un manifiesto de WorkloadAllowlist. El resultado es similar a lo siguiente:

    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. En un editor de texto, crea un archivo YAML que contenga el WorkloadAllowlist generado.

  5. Establece el campo metadata.name de la lista de entidades permitidas.

  6. Opcional: Generaliza WorkloadAllowlist para que pueda eximir cargas de trabajo similares. Usa uno de los siguientes métodos:

    • Algunos campos específicos admiten expresiones regulares, como matchingCriteria.containers[*].image y matchingCriteria.containers[*].args. Usa una expresión regular que coincida con varios valores en diferentes cargas de trabajo.

    • Los campos específicos, como matchingCriteria.containers y matchingCriteria.securityContext.capabilities.add, coinciden con cualquier carga de trabajo que tenga un subconjunto de los valores de WorkloadAllowlist. En WorkloadAllowlist, especifica valores adicionales para que coincidan con otras cargas de trabajo.

    Para obtener más información sobre todos los campos y valores admitidos que puedes usar, consulta la CustomResourceDefinition de WorkloadAllowlist.

  7. Sube el archivo de manifiesto a tu bucket de Cloud Storage.

Si las políticas de tu organización permiten la instalación de listas de entidades permitidas desde tu bucket en clústeres, los administradores de clústeres pueden hacer lo siguiente:

  1. Agrega las rutas de acceso de tu lista de entidades permitidas a un clúster.
  2. Crea un AllowlistSynchronizer para instalar las listas de entidades permitidas desde tu bucket.

Para obtener más información sobre cómo configurar un clúster y, luego, instalar listas de entidades permitidas, consulta Controla la admisión de cargas de trabajo privilegiadas en el modo Autopilot.

Ejemplo de configuración de la lista de entidades permitidas

El campo matchingCriteria en una especificación de WorkloadAllowlist tiene una estructura similar a la especificación de Pod de Kubernetes. La CustomResourceDefinition de WorkloadAllowlist es la fuente de información para todos los campos, valores y expresiones que puedes usar.

En esta sección, se muestra un ejemplo de lista de entidades permitidas que coincide con una carga de trabajo que tiene las siguientes propiedades:

  • El contenedor container-1 de la carga de trabajo se ejecuta en modo privilegiado.
  • La carga de trabajo activa el directorio /var/log/ del sistema de archivos del nodo en modo de escritura.

  1. Revisa la carga de trabajo de ejemplo:

    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

    De forma predeterminada, Autopilot rechaza esta carga de trabajo.

  2. Revisa el ejemplo 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

    Este WorkloadAllowlist tiene las siguientes propiedades:

    • Los valores del campo exemptions especifican las restricciones de Autopilot que omite la lista de entidades permitidas.
    • Los valores del campo matchingCriteria especifican los contenedores que usa la carga de trabajo de ejemplo y los campos que normalmente incumplirían las restricciones de Autopilot.

    La lista de entidades permitidas solo tiene los valores de los campos que incumplen las restricciones. Se ignoran otros campos de la carga de trabajo, como el campo resources.requests.

Cuando instalas este ejemplo de WorkloadAllowlist en un clúster, GKE permite que la carga de trabajo privilegiada se ejecute en ese clúster. Por ejemplo, en un clúster Standard que tiene nodos de Autopilot, la instalación de esta WorkloadAllowlist permite que la carga de trabajo privilegiada se ejecute en los nodos de Autopilot.

Otorga acceso al agente de servicio de GKE

Para sincronizar las listas de entidades permitidas de tu bucket en un clúster, el agente de servicio de GKE en el proyecto del clúster requiere los siguientes roles de IAM:

Para otorgar estos roles al agente de servicio, sigue estos pasos:

  1. Busca el número de proyecto de tu proyecto de clúster:

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

  2. Otorga la función 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

    Reemplaza lo siguiente:

    • BUCKET_NAME: Es el nombre de tu bucket de Cloud Storage.
    • CLUSTER_PROJECT_NUMBER: Es el número del proyecto del clúster, que se obtiene del resultado del paso anterior.
    • BUCKET_PROJECT_ID: Es el ID del proyecto que contiene tu bucket.

  3. Otorga la función 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

¿Qué sigue?