Autenticarse en las APIs de Google Cloud desde cargas de trabajo de GKE

En esta página se muestra cómo acceder de forma más segura a las APIs desde las cargas de trabajo que se ejecutan en clústeres de Google Kubernetes Engine (GKE) mediante Federación de Workload Identity para GKE. Google Cloud

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

Antes de leer esta página, asegúrate de que conoces los conceptos de Workload Identity Federation para GKE.

Antes de empezar

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

  • Habilita la API de Google Kubernetes Engine.
    • Habilitar la API de Google Kubernetes Engine
  • Si quieres usar Google Cloud CLI para esta tarea, instálala y, a continuación, inicialízala. Si ya has instalado la gcloud CLI, obtén la versión más reciente ejecutando gcloud components update.

Habilitar Workload Identity Federation para GKE en clústeres y grupos de nodos

En Autopilot, Workload Identity Federation for GKE siempre está habilitado. Vaya a la sección Configurar aplicaciones para usar Workload Identity Federation for GKE.

En Estándar, puedes habilitar Workload Identity Federation para GKE en clústeres y grupos de nodos mediante la CLI de Google Cloud o la Google Cloud consola. Workload Identity Federation para GKE debe habilitarse a nivel del clúster antes de poder habilitarlo en los grupos de nodos.

Puedes habilitar Workload Identity Federation para GKE en un clúster estándar que ya tengas mediante la CLI de gcloud o la Google Cloud consola. Los grupos de nodos que ya tengas no se verán afectados, pero los grupos de nodos nuevos del clúster usarán Workload Identity Federation 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 Workload Identity Federation for GKE en un clúster, ejecuta el siguiente comando:

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

    Haz los cambios siguientes:

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

    3. Consola

    Para habilitar Workload Identity Federation for GKE en un clúster, sigue estos pasos:

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

      Ir a Google Kubernetes Engine

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

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

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

    5. Haz clic en Guardar cambios.

Migrar cargas de trabajo a Workload Identity Federation para GKE

Después de habilitar Workload Identity Federation para GKE en un clúster, puede que quieras migrar tus cargas de trabajo en ejecución para usar Workload Identity Federation para GKE. Selecciona la estrategia de migración que sea ideal para tu entorno. Puedes crear grupos de nodos con Workload Identity Federation para GKE habilitado o actualizar grupos de nodos para habilitar Workload Identity Federation para GKE.

Solo puedes habilitar Workload Identity Federation para GKE en un grupo de nodos si Workload Identity Federation para GKE está habilitado en el clúster.

Práctica recomendada:

Crea grupos de nodos si también necesitas modificar tus aplicaciones para que sean compatibles con Workload Identity Federation para GKE.

Todos los grupos de nodos que crees usarán de forma predeterminada Workload Identity Federation para GKE si el clúster tiene habilitada esta función. Para crear un grupo de nodos con Workload Identity Federation for GKE habilitado, ejecuta el siguiente comando:

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-metadata=GKE_METADATA

Haz los cambios siguientes:

  • NODEPOOL_NAME: el nombre del nuevo grupo de nodos.
  • CLUSTER_NAME: el nombre del clúster que tiene habilitada la federación de identidades de carga de trabajo para GKE.
  • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.

La marca --workload-metadata=GKE_METADATA configura el grupo de nodos para que use el servidor de metadatos de GKE.

Práctica recomendada:

Incluye la marca para que se produzca un error al crear el grupo de nodos si Workload Identity Federation para GKE no está habilitado en el clúster.

Actualizar un grupo de nodos

Puedes habilitar manualmente Workload Identity Federation para GKE en grupos de nodos que ya tengas después de habilitar Workload Identity Federation 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 para que use Workload Identity Federation for GKE, ejecuta el siguiente comando:

    gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-metadata=GKE_METADATA

    Si un clúster tiene habilitada la federación de identidades de carga de trabajo para GKE, puedes inhabilitarla de forma selectiva en un grupo de nodos específico. Para ello, especifica explícitamente --workload-metadata=GCE_METADATA. Consulta más información sobre cómo proteger los metadatos de un clúster.

    3. Consola

    Para modificar un grupo de nodos que ya tengas para que use Workload Identity Federation for GKE, sigue estos pasos:

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

      Ir a Google Kubernetes Engine

    2. En la lista de clústeres, haga clic en el nombre del clúster que quiera 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 que quieras modificar.

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

    6. En la página Editar grupo de nodos, ve a la sección Seguridad y marca la casilla Habilitar servidor de metadatos de GKE.

    7. Haz clic en Guardar.

Configurar aplicaciones para usar Workload Identity Federation for GKE

Para permitir que tus aplicaciones de GKE se autentiquen en las APIs mediante Workload Identity Federation for GKE, debes crear políticas de gestión de identidades y accesos para las APIs específicas. Google CloudLa cuenta principal de estas políticas es un identificador de cuenta principal de gestión de identidades y accesos que corresponde a las cargas de trabajo, los espacios de nombres o las cuentas de servicio de Kubernetes. Este proceso devuelve un token de acceso federado que tu carga de trabajo puede usar en las llamadas a la API.

También puedes configurar cuentas de servicio de Kubernetes para suplantar cuentas de servicio de IAM, lo que configura GKE para intercambiar el token de acceso federado por un token de acceso de la API de credenciales de cuenta de servicio de IAM. Para obtener más información, consulta la sección Alternativa: vincular cuentas de servicio de Kubernetes a IAM.

Configurar la autorización y las entidades

  1. Obtén las credenciales de tu clúster:

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

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre del clúster que tiene habilitada la federación de identidades de carga de trabajo para GKE.
    • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.

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

    kubectl create namespace NAMESPACE

  3. Crea una cuenta de servicio de Kubernetes para que la use tu aplicación. También puedes usar cualquier cuenta de servicio de Kubernetes que ya tengas en cualquier espacio de nombres. Si no asignas una cuenta de servicio a tu carga de trabajo, Kubernetes asignará la cuenta de servicio default del espacio de nombres.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Haz los cambios siguientes:

    • KSA_NAME: el nombre de tu nueva cuenta de servicio de Kubernetes.
    • NAMESPACE: nombre del espacio de nombres de Kubernetes de la cuenta de servicio.

  4. Crea una política de gestión de identidades y accesos de permiso que haga referencia a la cuenta de servicio de Kubernetes. Como práctica recomendada, concede permisos a recursos específicos deGoogle Cloud a los que tu aplicación necesite acceder. Debes tener los permisos de gestión de identidades y accesos pertinentes para crear políticas de permiso en tu proyecto.

    Por ejemplo, el siguiente comando asigna el rol Kubernetes Engine Cluster Viewer (roles/container.clusterViewer) a la cuenta de servicio que has creado:

    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

    Haz los cambios siguientes:

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

    Puedes conceder roles en cualquier Google Cloud recurso que admita políticas de permiso de gestión de identidades y accesos. La sintaxis del identificador de la cuenta principal depende del recurso de Kubernetes. Para ver una lista de los identificadores admitidos, consulta Identificadores principales de Workload Identity Federation para GKE.

Opcional: Configurar opciones de Service Mesh

Si usas Istio o Cloud Service Mesh para gestionar tu entorno, añade la siguiente anotación al campo metadata.annotations de la especificación de tu pod:

metadata:
  annotations:
    proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'

Esta anotación impide que tus contenedores se inicien hasta que el proxy de la malla de servicios esté listo para redirigir el tráfico de tus aplicaciones.

Verificar la configuración de Workload Identity Federation para GKE

En esta sección, creará un segmento de Cloud Storage y concederá acceso de lectura al segmento a la cuenta de servicio de Kubernetes que creó en la sección anterior. A continuación, despliega una carga de trabajo y comprueba que el contenedor puede enumerar los clústeres del proyecto.

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

    gcloud storage buckets create gs://BUCKET

    Sustituye BUCKET por el nombre que quieras darle al nuevo segmento.

  2. Da el rol Lector de objetos de Storage (roles/storage.objectViewer) a la cuenta de servicio que has creado:

    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

    Haz los cambios siguientes:

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

  3. Guarda el siguiente archivo de 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, añade lo siguiente al campo template.spec para colocar los pods en grupos de nodos que usen Workload Identity Federation para GKE.

    Omite este paso en los clústeres de Autopilot, que rechazan este nodeSelector, ya que todos los nodos usan Workload Identity Federation 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 será 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 los objetos del segmento:

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

    El resultado es el siguiente:

    {
  "kind": "storage#objects"
}

    Este resultado muestra que tu pod puede acceder a los objetos del segmento.

Alternativa: vincular cuentas de servicio de Kubernetes a IAM

Práctica recomendada:

Usa identificadores de principales de IAM para configurar Workload Identity Federation para GKE. Sin embargo, esta identidad federada tiene limitaciones específicas para cada API compatible. Google Cloud Si se aplican estas limitaciones, 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 cuenta de servicio 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 de cualquier proyecto de tu organización.

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

    Haz los cambios siguientes:

    • IAM_SA_NAME: un nombre para tu nueva cuenta de servicio de gestión de identidades y accesos.
    • IAM_SA_PROJECT_ID: el ID del proyecto de tu cuenta de servicio de gestión de identidades y accesos.

    Para obtener información sobre cómo autorizar a las cuentas de servicio de Gestión de Identidades y Accesos para que accedan a las APIs de Google Cloud, consulta el artículo Información sobre las cuentas de servicio.

  4. Concede a tu cuenta de servicio de gestión de identidades y accesos los roles que necesite en APIs Google Cloud específicas:

    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"

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

  5. Crea una política de permiso de gestión de identidades y accesos que dé a la cuenta de servicio de Kubernetes acceso para suplantar la cuenta de servicio de gestión de identidades y accesos:

    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 la vinculación 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

    Tanto la política de permiso de gestión de identidades y accesos como la anotación son obligatorias cuando se usa este método.

Usar Workload Identity Federation 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 Workload Identity Federation for GKE, tus solicitudes al servidor de metadatos de la instancia se dirigen al servidor de metadatos de GKE. El código que ya se autentica mediante el servidor de metadatos de instancia (como el código que usa las bibliotecas de clienteGoogle Cloud ) debería funcionar sin modificaciones.

Usar cuota de otro proyecto con Workload Identity Federation para GKE

En los clústeres que ejecutan la versión 1.24 de GKE o una posterior, puedes configurar tu cuenta de servicio de Kubernetes para que use la cuota de otro proyecto Google Cloud al hacer llamadas a los métodos GenerateAccessToken y GenerateIdToken de la API de credenciales de cuenta de servicio de IAM. De esta forma, puedes evitar usar toda la cuota de tu proyecto principal y, en su lugar, usar la cuota de otros proyectos para estos servicios de tu clúster.

Para configurar un proyecto de cuota con Workload Identity Federation for GKE, haz lo siguiente:

  1. Concede 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' \

    Sustituye 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 comprobar que la configuración funciona correctamente, haz lo siguiente:

  1. Crea un pod e inicia una sesión de shell. Consulta la documentación de Kubernetes para obtener un shell de un contenedor en ejecución.

  2. Envía 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 Credentials de cuentas de servicio de IAM en la Google Cloud consola de tu proyecto de cuota:

    Ir a APIs

  4. Comprueba si hay cambios en el tráfico.

Limpieza

Para dejar de usar Workload Identity Federation para GKE, revoca el acceso a la cuenta de servicio de IAM e inhabilita Workload Identity Federation para GKE en el clúster.

Revocar acceso

Para revocar el acceso a la principal, elimina la política de permiso de gestión de identidades y accesos que has creado en la sección Configurar aplicaciones para que usen Workload Identity Federation for 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

Inhabilitar Workload Identity Federation para GKE

Solo puedes inhabilitar Workload Identity Federation para GKE en 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 Workload Identity Federation para GKE en cada grupo de nodos:

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

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

  3. Inhabilita Workload Identity Federation for GKE en el clúster:

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --disable-workload-identity

    4. Consola

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

      Ir a Google Kubernetes Engine

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

    3. Haz clic en la pestaña Nodos.

    4. Para inhabilitar Workload Identity Federation for GKE en cada grupo de nodos, haz lo siguiente en cada grupo de nodos de la sección Grupos de nodos:

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

    5. Para inhabilitar Workload Identity Federation for GKE en el clúster, haz lo siguiente:

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

Inhabilitar Workload Identity Federation para GKE en tu organización

Desde el punto de vista de la seguridad, Workload Identity Federation for GKE permite a GKE afirmar identidades de cuentas de servicio de Kubernetes que se pueden autenticar y autorizar para acceder a los recursos. Google CloudSi eres administrador y has tomado medidas para aislar las cargas de trabajo de los recursos, 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 de cargas de trabajo para GKE en tu organización.Google Cloud

Consulta estas instrucciones para inhabilitar Workload Identity Federation para GKE en tu organización.

Solución de problemas

Para obtener información sobre cómo solucionar problemas, consulta el artículo Solucionar problemas de Workload Identity Federation para GKE.

Siguientes pasos