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 privilegiadas en tus nodos de Autopilot. Almacenas estas listas de entidades permitidas en buckets de Cloud Storage. Este documento está destinado a 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 estar familiarizado con el control de admisión de cargas de trabajo privilegiadas en Autopilot.

Acerca de las cargas de trabajo privilegiadas 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 mediante la instalación de 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 de código abierto específicos.

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 WorkloadAllowlist de Kubernetes 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 buckets administrados por el cliente. Los administradores de clústeres pueden instalar estas listas de entidades permitidas para que las cargas de trabajo privilegiadas puedan ejecutarse 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 the 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 de este documento.

• Habilita la API de Cloud Storage.

  Roles necesarios para habilitar las APIs

  Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén 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 listas de entidades permitidas. También puedes crear un bucket para esta tarea.
• Abre el manifiesto YAML que define la carga de trabajo privilegiada 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:

• Almacena listas de entidades permitidas en tu bucket: Usuario de objetos de almacenamiento (roles/storage.objectUser)
• Otorga acceso al agente de servicio de GKE: Administrador de Storage (roles/storage.admin).

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 mediante roles personalizados o cualquier otro rol predefinido.

Crea y sube una WorkloadAllowlist

Las listas de entidades permitidas son recursos personalizados de WorkloadAllowlist que defines en archivos YAML. Los campos de la especificación de una WorkloadAllowlist son similares a los campos 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 privilegiada, GKE valida la especificación de la carga de trabajo privilegiada con 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 WorkloadAllowlist nueva y subirla a tu bucket de Cloud Storage, sigue estos pasos:

1. Identifica la carga de trabajo privilegiada para agregarla a 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 un 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 a tu 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 la WorkloadAllowlist generada.

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

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

   • Los 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 con 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 tú puedes usar, consulta la WorkloadAllowlist CustomResourceDefinition.

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 cómo instalar listas de entidades permitidas, consulta Controla la admisión de cargas de trabajo privilegiadas en modo Autopilot.

Configuración de ejemplo 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 WorkloadAllowlist CustomResourceDefinition es la fuente de información para todos los campos, valores y expresiones que puedes usar.

En esta sección, se muestra una lista de entidades permitidas de ejemplo 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 la WorkloadAllowlist de ejemplo:

   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
   

   Esta 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 infringirían las restricciones de Autopilot.

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

Cuando instalas esta WorkloadAllowlist de ejemplo 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 de clúster requiere los siguientes roles de IAM:

• Visualizador de buckets de Storage (roles/storage.bucketViewer)
• Visualizador de objetos de almacenamiento (roles/storage.objectViewer)

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 el rol 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: el nombre de tu bucket de Cloud Storage.
   • CLUSTER_PROJECT_NUMBER: el número de proyecto del proyecto de clúster, del resultado del paso anterior.
   • BUCKET_PROJECT_ID: el ID del proyecto que contiene tu bucket.

3. Otorga el rol 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?

• Agrega las rutas de acceso de tu lista de entidades permitidas a una política de la organización
• Configura clústeres e instala listas de entidades permitidas