Autenticación en las APIs de Google Cloud desde GKE

En esta página, se muestra cómo acceder de manera más segura a las APIs de Google Cloud desde las cargas de trabajo que se ejecutan en clústeres de Google Kubernetes Engine (GKE) mediante Workload Identity Federation for GKE. Si deseas obtener más información, consulta Acerca de la federación de identidades para cargas de trabajo para GKE.

Esta página está destinada a administradores de identidades y cuentas, operadores y desarrolladores que crean y administran políticas relacionadas con los permisos de los usuarios. Para obtener más información sobre los roles comunes y las tareas de ejemplo a las que hacemos referencia en el contenido de Google Cloud, consulta Tareas y roles comunes de los usuarios de GKE Enterprise.

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 gcloud components update para obtener la versión más reciente.

Habilita la federación de identidades para cargas de trabajo para GKE en clústeres y grupos de nodos.

En Autopilot, Workload Identity Federation for GKE siempre está habilitada. Ve a la sección Configura aplicaciones para usar la federación de identidades para cargas de trabajo para GKE.

En Standard, debes habilitar la federación de identidades para cargas de trabajo para GKE en clústeres y grupos de nodos mediante Google Cloud CLI o la consola de Google Cloud. La federación de identidades para cargas de trabajo para GKE debe habilitarse a nivel de clúster antes de poder habilitar la federación de identidades para cargas de trabajo para GKE en grupos de nodos.

Crea un clúster nuevo

Puedes habilitar la federación de identidades para cargas de trabajo para GKE en un clúster estándar nuevo mediante gcloud CLI o la consola de Google Cloud.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Para habilitar la federación de identidades para cargas de trabajo para GKE en un clúster nuevo, ejecuta el siguiente comando:

    gcloud container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

    Reemplaza lo siguiente:

    • CLUSTER_NAME: Es el nombre del clúster nuevo.
    • LOCATION: la ubicación de Compute Engine para el clúster.
    • PROJECT_ID: tu ID del proyecto de Google Cloud.

Console

Para habilitar la federación de identidades para cargas de trabajo para GKE en un clúster nuevo, haz lo siguiente:

  1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

    Ir a Google Kubernetes Engine

  2. Haz clic en Crear.

  3. En el diálogo Crear clúster, para GKE Standard, haz clic en Configurar.

  4. En el menú de navegación, en la sección Clúster, haz clic en Seguridad.

  5. Selecciona la casilla de verificación Habilitar Workload Identity.

  6. Continúa con la configuración del clúster y, luego, haz clic en Crear.

Actualiza un clúster existente

Puedes habilitar la federación de identidades para cargas de trabajo para GKE en un clúster estándar existente con gcloud CLI o la consola de Google Cloud. Los grupos de nodos existentes no se verán afectados, pero todos los grupos de nodos nuevos en el clúster usarán la federación de identidades para cargas de trabajo para GKE.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Para habilitar la federación de identidades para cargas de trabajo para GKE en un clúster existente, ejecuta el siguiente comando:

    gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

    Reemplaza lo siguiente:

    • CLUSTER_NAME: Es el nombre del clúster existente.
    • LOCATION: La ubicación de Compute Engine del clúster.
    • PROJECT_ID: tu ID del proyecto de Google Cloud.

Console

Para habilitar la federación de identidades para cargas de trabajo para GKE en un clúster existente, haz lo siguiente:

  1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud:

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. En la página de detalles del clúster, en la sección Seguridad, haz clic en Editar Workload Identity.

  4. En el cuadro de diálogo Editar Workload Identity, selecciona la casilla de verificación Habilitar Workload Identity.

  5. Haz clic en Guardar cambios.

Migra las cargas de trabajo existentes a la federación de identidades para cargas de trabajo para GKE

Después de habilitar la federación de identidades para cargas de trabajo para GKE en un clúster existente, es posible que desees migrar tus cargas de trabajo en ejecución para usar la federación de identidades para cargas de trabajo para GKE. Selecciona la estrategia de migración ideal para tu entorno. Puedes crear grupos de nodos nuevos con la federación de identidades para cargas de trabajo para GKE habilitada o actualizar los grupos de nodos existentes para habilitar la federación de identidades para cargas de trabajo para GKE.

Te recomendamos crear grupos de nodos nuevos si también necesitas modificar tus aplicaciones a fin de que sean compatibles con la federación de identidades para cargas de trabajo para GKE.

Todos los grupos de nodos nuevos que crees de forma predeterminada usarán la federación de identidades para cargas de trabajo para GKE si el clúster tiene habilitada la federación de identidades para cargas de trabajo para GKE. Para crear un grupo de nodos nuevo con la federación de identidades para cargas de trabajo para GKE habilitada, ejecuta el siguiente comando:

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --workload-metadata=GKE_METADATA

Reemplaza lo siguiente:

  • NODEPOOL_NAME: el nombre del grupo de nodos nuevo
  • CLUSTER_NAME: El nombre del clúster existente que tiene habilitada la federación de identidades para cargas de trabajo para GKE.

La marca --workload-metadata=GKE_METADATA configura el grupo de nodos para usar el servidor de metadatos de GKE. Te recomendamos que incluyas la marca a fin de que la creación del grupo de nodos falle si la federación de identidades para cargas de trabajo para GKE no está habilitada en el clúster.

Actualiza un grupo de nodos existente

Puedes habilitar de forma manual la federación de identidades para cargas de trabajo para GKE en los grupos de nodos existentes después de habilitar la federación de identidades para cargas de trabajo para GKE en el clúster.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Para modificar un grupo de nodos existente para usar la federación de identidades para cargas de trabajo para GKE, ejecuta el siguiente comando:

    gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --workload-metadata=GKE_METADATA

    Si un clúster tiene habilitada la federación de identidades para cargas de trabajo para GKE, puedes inhabilitarla de forma selectiva en un grupo de nodos en particular si especificas --workload-metadata=GCE_METADATA explícitamente. Para obtener más información, consulta Protege metadatos del clúster.

Console

Para modificar un grupo de nodos existente para usar la federación de identidades para cargas de trabajo para GKE, sigue estos pasos:

  1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud:

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. Haz clic en la pestaña Nodos.

  4. En la sección Grupos de nodos, haz clic en el nombre del grupo de nodos al que quieres modificar.

  5. En la página Detalles del grupo de nodos, haz clic en Editar.

  6. En la página Editar grupo de nodos, en la sección Seguridad, selecciona la casilla de verificación Habilitar servidor de metadatos de GKE.

  7. Haz clic en Guardar.

Configura aplicaciones a fin de usar la federación de identidades para cargas de trabajo para GKE

Para permitir que tus aplicaciones de GKE se autentiquen en las API de Google Cloud mediante la federación de identidades para cargas de trabajo para GKE, crea políticas de IAM para las APIs específicas. El principal en estas políticas es un identificador de principal de IAM que corresponde a las cargas de trabajo, los espacios de nombres o las cuentas de servicio.

Configura la autorización y las principales

  1. Obtén credenciales para el clúster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    Reemplaza lo siguiente:

    • CLUSTER_NAME: el nombre del clúster que tiene habilitada la federación de identidades para cargas de trabajo para GKE.
    • LOCATION: Es la ubicación de tu clúster.

  2. Crea un espacio de nombres para usar en la cuenta de servicio de Kubernetes. También puedes usar el espacio de nombres predeterminado default o cualquier espacio de nombres existente.

    kubectl create namespace NAMESPACE

  3. Crea una cuenta de servicio de Kubernetes para que tu aplicación use: También puedes usar cualquier ServiceAccount de Kubernetes existente en cualquier espacio de nombres. Si no asignas una ServiceAccount a tu carga de trabajo, Kubernetes asigna la ServiceAccount default en el espacio de nombres.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Reemplaza lo siguiente:

    • KSA_NAME: Es el nombre de tu ServiceAccount de Kubernetes nueva.
    • NAMESPACE es el nombre del espacio de nombres de Kubernetes para la ServiceAccount.

  4. Crea una política de permisos de IAM que haga referencia a la ServiceAccount de Kubernetes. Como práctica recomendada, otorga permisos a recursos específicos de Google Cloud a los que necesita acceder la aplicación. Debes tener permisos de IAM relevantes para crear políticas de permisos en tu proyecto.

    Por ejemplo, el siguiente comando otorga el rol de visualizador de clústeres de Kubernetes Engine (roles/container.clusterViewer) a la cuenta de servicio que creaste:

    gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/container.clusterViewer \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
    --condition=None

    Reemplaza lo siguiente:

    • PROJECT_ID: tu ID del proyecto de Google Cloud.
    • PROJECT_NUMBER: el número de proyecto numérico de Google Cloud.

    Puedes otorgar roles en cualquier recurso de Google Cloud que admita políticas de permisos de IAM. La sintaxis del identificador principal depende del recurso de Kubernetes. Si deseas obtener una lista de identificadores compatibles, consulta Identificadores principales para la federación de identidades para cargas de trabajo para GKE.

Verifica la configuración de la federación de identidades para cargas de trabajo para GKE

En esta sección, crearás un bucket de Cloud Storage y otorgarás acceso de lectura en el bucket a la cuenta de servicio de Kubernetes que creaste en la sección anterior. Luego, implementarás una carga de trabajo y probarás que el contenedor pueda enumerar clústeres en el proyecto.

  1. Crea un bucket de Cloud Storage vacío:

    gcloud storage buckets create gs://BUCKET

    Reemplaza BUCKET por un nombre para el bucket nuevo.

  2. Otorga el rol de visualizador de objetos de almacenamiento (roles/storage.objectViewer) a la cuenta de servicio que creaste:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET \
    --role=roles/storage.objectViewer \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
    --condition=None

    Reemplaza lo siguiente:

    • PROJECT_ID: tu ID del proyecto de Google Cloud.
    • PROJECT_NUMBER: el número de proyecto numérico de Google Cloud.
    • NAMESPACE: El espacio de nombres de Kubernetes que contiene la ServiceAccount.
    • KSA_NAME: el nombre de la ServiceAccount

  3. Guarda el siguiente manifiesto como test-app.yaml:

    apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  containers:
  - name: test-pod
    image: google/cloud-sdk:slim
    command: ["sleep","infinity"]
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
        ephemeral-storage: 10Mi

  4. Solo en clústeres estándar, agrega lo siguiente al campo template.spec para colocar los Pods en grupos de nodos que usan la federación de identidades para cargas de trabajo para GKE.

    Omite este paso en los clústeres de Autopilot, que rechazan este nodeSelector porque cada nodo usa la federación de identidades para cargas de trabajo para GKE.

    spec:
  nodeSelector:
    iam.gke.io/gke-metadata-server-enabled: "true"

  5. Aplica la configuración a tu clúster:

    kubectl apply -f test-app.yaml

  6. Espera a que el Pod esté listo. Para comprobar el estado del Pod, ejecuta el siguiente comando:

    kubectl get pods --namespace=NAMESPACE

    Cuando el Pod está listo, el resultado es similar al siguiente:

    NAME       READY   STATUS    RESTARTS   AGE
test-pod   1/1     Running   0          5m27s

  7. Abre una sesión de shell en el Pod:

    kubectl exec -it pods/test-pod --namespace=NAMESPACE -- /bin/bash

  8. Obtén una lista de objetos en el bucket:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET/o"

    Esta es la salida:

    {
  "kind": "storage#objects"
}

    En este resultado, se muestra que tu Pod puede acceder a los objetos en el bucket.

Alternativa: vincula las cuentas de servicio de Kubernetes a IAM

Te recomendamos que uses identificadores principales de IAM para configurar la federación de identidades para cargas de trabajo para GKE. Sin embargo, esta identidad federada tiene limitaciones específicas para cada API de Google Cloud compatible. Para obtener una lista de limitaciones, consulta Productos admitidos y limitaciones.

Si estas limitaciones se aplican a tu caso, sigue estos pasos para configurar el acceso a esas APIs desde tus cargas de trabajo de GKE:

  1. Crea un espacio de nombres de Kubernetes:

    kubectl create namespace NAMESPACE

  2. Crea una ServiceAccount de Kubernetes:

    kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE

  3. Crea una cuenta de servicio de IAM. También puedes usar cualquier cuenta de servicio de IAM existente en cualquier proyecto de tu organización.

    gcloud iam service-accounts create IAM_SA_NAME \
    --project=IAM_SA_PROJECT_ID

    Reemplaza lo siguiente:

    • IAM_SA_NAME: Un nombre para tu cuenta de servicio de IAM nueva.
    • IAM_SA_PROJECT_ID: El ID del proyecto de tu cuenta de servicio de IAM.

    Para obtener información sobre la autorización de cuentas de servicio de IAM a fin de acceder a las APIs de Google Cloud, consulta la página Comprende las cuentas de servicio.

  4. Otorga a tu cuenta de servicio de IAM los roles que necesita en APIs específicas de Google Cloud:

    gcloud projects add-iam-policy-binding IAM_SA_PROJECT_ID \
    --member "serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com" \
    --role "ROLE_NAME"

    Reemplaza ROLE_NAME por el nombre del rol, como roles/spanner.viewer.

  5. Crea una política de permisos de IAM que otorgue a la cuenta de servicio de Kubernetes acceso para actuar en nombre de la cuenta de servicio de IAM:

    gcloud iam service-accounts add-iam-policy-binding IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

    El nombre del miembro debe incluir el espacio de nombres y el nombre de la cuenta de servicio de Kubernetes. Por ejemplo, serviceAccount:example-project.svc.id.goog[example-namespace/example-serviceaccount].

  6. Anota la cuenta de servicio de Kubernetes para que GKE vea el vínculo entre las cuentas de servicio:

    kubectl annotate serviceaccount KSA_NAME \
    --namespace NAMESPACE \
    iam.gke.io/gcp-service-account=IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com

Usa la federación de identidades para cargas de trabajo para GKE desde tu código

La autenticación en los servicios de Google Cloud desde tu código es el mismo proceso que la autenticación mediante el servidor de metadatos de Compute Engine. Cuando usas la federación de identidades para cargas de trabajo para GKE, las solicitudes al servidor de metadatos de la instancia se enrutan al servidor de metadatos de GKE. El código existente que se autentica mediante el servidor de metadatos de la instancia (como el código que usa las bibliotecas cliente de Google Cloud) debería funcionar sin modificaciones.

Usa la cuota de un proyecto diferente con la federación de identidades para cargas de trabajo para GKE

En los clústeres que ejecutan la versión 1.24 o posterior de GKE, puedes configurar tu cuenta de servicio de Kubernetes para que use la cuota de un proyecto diferente de Google Cloud cuando se realicen llamadas a los métodos GenerateAccessToken y GenerateIdToken. API de Service Account Credentials de IAM. Esto te permite evitar el uso de la cuota completa en tu proyecto principal y, en su lugar, usar la cuota de otros proyectos para estos servicios en tu clúster.

Para configurar un proyecto de cuota con la federación de identidades para cargas de trabajo para GKE, haz lo siguiente:

  1. Otorga el permiso serviceusage.services.use en el proyecto de cuota a la cuenta de servicio de Kubernetes.

    gcloud projects add-iam-policy-binding QUOTA_PROJECT_ID \
    --role=roles/serviceusage.serviceUsageConsumer \
    --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \

    Reemplaza QUOTA_PROJECT_ID por el ID del proyecto de cuota.

  2. Anota la cuenta de servicio de Kubernetes con el proyecto de cuota:

    kubectl annotate serviceaccount KSA_NAME \
    --namespace NAMESPACE \
    iam.gke.io/credential-quota-project=QUOTA_PROJECT_ID

Para verificar que la configuración funcione correctamente, haz lo siguiente:

  1. Crea un Pod y, luego, inicia una sesión de shell. Consulta la documentación de Kubernetes para obtener una shell para un contenedor en ejecución.

  2. Realiza una solicitud al servidor de metadatos:

    curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token

  3. Ve a la página API de Service Account Credentials de IAM en la consola de Google Cloud para ver el proyecto de cuota:

    Ir a las API

  4. Verifica los cambios en el tráfico.

Limpia

Si deseas dejar de usar la federación de identidades para cargas de trabajo para GKE, revoca el acceso a la cuenta de servicio de IAM y, luego, inhabilita la federación de identidades para cargas de trabajo para GKE en el clúster.

Revocar acceso

Para revocar el acceso al principal, quita la política de permisos de IAM que creaste en la sección Configura aplicaciones a fin de usar la federación de identidades para cargas de trabajo para GKE.

Por ejemplo, para revocar el acceso a un repositorio de Artifact Registry, ejecuta el siguiente comando:

gcloud artifacts repositories remove-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
    --role='roles/artifactregistry.reader' \
    --all

Inhabilita la federación de identidades para cargas de trabajo para GKE

Solo puedes inhabilitar la federación de identidades para cargas de trabajo para GKE en los clústeres estándar.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Inhabilita la federación de identidades para cargas de trabajo para GKE en cada grupo de nodos:

    gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --workload-metadata=GCE_METADATA

    Repite este comando para cada grupo de nodos del clúster.

  3. Inhabilita la federación de identidades para cargas de trabajo para GKE en el clúster:

    gcloud container clusters update CLUSTER_NAME \
    --disable-workload-identity

Console

  1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. Haz clic en la pestaña Nodos.

  4. Para inhabilitar la federación de identidades para cargas de trabajo para GKE en cada grupo de nodos, haz lo siguiente para cada grupo de nodos en la sección Grupos de nodos:

    1. Haz clic en el nombre del grupo de nodos que deseas modificar.
    2. En la página Detalles del grupo de nodos, haz clic en Editar.
    3. En la página Editar grupo de nodos, en la sección Seguridad, desmarca la selección de la casilla de verificación Habilitar servidor de metadatos de GKE.
    4. Haz clic en Guardar.

  5. Para inhabilitar la federación de identidades para cargas de trabajo para GKE en el clúster, haz lo siguiente:

    1. Haz clic en la pestaña Detalles.
    2. En la sección Seguridad, junto a Workload Identity, haz clic en Editar.
    3. En el cuadro de diálogo Editar Workload Identity, desmarca la casilla de verificación Habilitar Workload Identity.
    4. Haz clic en Guardar cambios.

Inhabilita la federación de identidades para cargas de trabajo para GKE en la organización

Desde la perspectiva de seguridad, la federación de identidades para cargas de trabajo para GKE permite confirmar las identidades de las cuentas de servicio de Kubernetes que se pueden autenticar y autorizar en los recursos de Google Cloud. Si eres administrador y realizaste acciones para aislar las cargas de trabajo de los recursos de Google Cloud, como inhabilitar la creación de cuentas de servicio o inhabilitar la creación de claves de cuentas de servicio, también puedes inhabilitar la federación de identidades para cargas de trabajo para GKE en tu organización.

Consulta estas instrucciones a fin de inhabilitar la federación de identidades para cargas de trabajo para GKE en tu organización.

Soluciona problemas

Si deseas obtener información sobre la solución de problemas, consulta Soluciona problemas de la federación de identidades para cargas de trabajo para GKE.

¿Qué sigue?