Habilita la federación de identidades para cargas de trabajo en AKS y EKS

Version 1.14 (latest)

   Versiones compatibles:

• v1.13 (la más reciente)                        
• v1.12                         
• v1.11                         
• Lista de versiones compatibles

   Versiones no compatibles

• v1.10                                      
• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

En este tema, se explica cómo habilitar la federación de identidades para cargas de trabajo para las instalaciones híbridas de Apigee en las plataformas AKS y EKS.

Para instalaciones en GKE, sigue las instrucciones en Habilita Workload Identity en GKE.

Descripción general

La federación de identidades de cargas de trabajo permite que las aplicaciones que se ejecutan fuera de Google Cloud actúen en nombre de una cuenta de servicio de Google Cloud Platform mediante credenciales de un proveedor de identidad externo.

El uso de la federación de Workload Identity puede ayudarte a mejorar la seguridad, ya que permite que las aplicaciones usen los mecanismos de autenticación que proporciona el entorno externo y puede reemplazar las claves de la cuenta de servicio.

Si quieres obtener una descripción general, consulta Prácticas recomendadas para usar la federación de identidades para cargas de trabajo.

Nota: El componente apigee-logger no admite la federación de identidades para cargas de trabajo. Consulta el problema conocido.

Configura la federación de identidades para cargas de trabajo

Para usar la federación de identidades para cargas de trabajo con Apigee Hybrid, primero configura tu clúster y, luego, aplica la función a la instalación de Apigee Hybrid.

Antes de comenzar

En estas instrucciones, se supone que ya configuraste tu instalación híbrida de Apigee. Las cuentas de servicio de IAM y las cuentas de servicio de Kubernetes se crean durante la instalación inicial. Consulta Panorama general para obtener una descripción general de la instalación de Apigee Hybrid.

Para las instalaciones en AKS, asegúrate de haber habilitado la entidad emisora de OpenID Connect (OIDC). Debes habilitar esta función para que la federación de identidades para cargas de trabajo pueda acceder a los metadatos de OpenID Connect y el conjunto de claves web JSON (JWKS) del clúster.

Configura el clúster para usar la federación de identidades para cargas de trabajo.

1. Verifica que la configuración actual de gcloud sea el ID de tu proyecto de Google Cloud con el siguiente comando:

   gcloud config get project

Si es necesario, establece la configuración actual gcloud:

gcloud config set project PROJECT_ID

2. Habilita la API de Security Token Service:

   Verifica que la API de Security Token Service esté habilitada con el siguiente comando:

   gcloud services list --enabled --project PROJECT_ID | grep sts.googleapis.com

   Si la API no está habilitada, haz lo siguiente:

   Console

   Enable the Security Token Service API.

   Enable the API

   Línea de comandos

   Habilita la API con el siguiente comando:

   gcloud services enable sts.googleapis.com --project PROJECT_ID

3. Crea el proveedor y el grupo de identidades para cargas de trabajo.

   Roles obligatorios

   Para obtener los permisos que necesitas para configurar la federación de Workload Identity, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

   • Administrador de grupos de identidades para cargas de trabajo (roles/iam.workloadIdentityPoolAdmin)
   • Administrador de cuenta de servicio (roles/iam.serviceAccountAdmin)

   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.

   Como alternativa, el rol básico de propietario de IAM (roles/owner) también incluye permisos para configurar la federación de identidades. No deberías otorgar roles básicos en un entorno de producción, pero puedes otorgarlos en un entorno de desarrollo o de prueba.

   Para crear un proveedor y un grupo de identidades para cargas de trabajo, haz lo siguiente:

   1. Determina la URL de la entidad emisora de tu clúster de AKS:

      AKS

      az aks show -n NAME -g RESOURCE_GROUP --query "oidcIssuerProfile.issuerUrl" -otsv

      Reemplaza lo siguiente:

      • NAME: Es el nombre del clúster.
      • RESOURCE_GROUP: Es el grupo de recursos del clúster.

      El comando genera la URL de la entidad emisora. Necesitarás la URL de la entidad emisora en uno de los siguientes pasos.

      Si el comando no devuelve una URL de la entidad emisora, verifica que hayas habilitado la función entidad emisora de OIDC.

      EKS

      aws eks describe-cluster --name NAME --query "cluster.identity.oidc.issuer" --output text
      

      Reemplaza NAME por el nombre del clúster.

      El comando genera la URL de la entidad emisora. Necesitas la URL de la entidad emisora en uno de los siguientes pasos.

      Otros Kubernetes

      1. Conéctate a tu clúster de Kubernetes y usa "kubectl" para determinar la URL de la entidad emisora de tu clúster:

         kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
         

         Necesitas la URL de la entidad emisora en uno de los siguientes pasos.

   2. Opcional: Si no se puede acceder públicamente a tu emisor de OIDC, descarga el conjunto de claves web JSON (JWKS) del clúster:
      Nota: Este paso requiere acceso de kubectl a tu clúster.
      Sugerencia: Cuando uses el archivo JWKS, deberás subir un archivo JWKS nuevo cada vez que rotes las claves de firma del clúster.

      kubectl get --raw /openid/v1/jwks > cluster-jwks.json
      

      Para verificar si tu proveedor de OIDC está disponible de forma pública, deberías poder acceder a la URL del proveedor con un comando CURL y recibir una respuesta 200.

   3. Crea un nuevo grupo de identidades para cargas de trabajo:

      gcloud iam workload-identity-pools create POOL_ID \
        --location="global" \
        --description="DESCRIPTION" \
        --display-name="DISPLAY_NAME"
                  

      Reemplaza lo siguiente:

      • POOL_ID: el ID único para el grupo.
      • DISPLAY_NAME: (Opcional) Es el nombre del grupo.
      • DESCRIPTION: (Opcional) Es una descripción del grupo que eliges. Esta descripción aparece cuando otorgas acceso a identidades de grupo.

      Por ejemplo:

      gcloud iam workload-identity-pools create my-wi-pool --display-name="My workload pool" --description="My workload pool description"

   4. Agrega el clúster como proveedor de grupos de identidades para cargas de trabajo. Elige el comando para crear el proveedor según si tu emisor de OIDC es de acceso público o no:

      Accesible de forma pública

      Si tu emisor de OIDC es de acceso público, crea el proveedor con el siguiente comando:

      gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --attribute-mapping="google.subject=assertion.sub"

      No es de acceso público

      Si no se puede acceder públicamente a tu emisor de OIDC, crea el proveedor con el siguiente comando:

        gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --jwks-file="cluster-jwks.json" \
        --attribute-mapping="google.subject=assertion.sub"

      Nota: Si rotas las claves, debes subir las JWK nuevas con cada rotación de claves.

      El comando no valida el JWKS del clúster. Si el JWKS tiene un formato incorrecto o venció, es posible que los intentos de autenticación posteriores fallen con un mensaje de error Error connecting to the given credential's issuer.

      Reemplaza lo siguiente:

      • WORKLOAD_PROVIDER_ID: Un ID de proveedor de grupos de identidades para cargas de trabajo único que elijas.
      • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo que creaste antes.
      • ISSUER: Usa la URL de la entidad emisora que determinaste antes para el URI de la entidad emisora .

      attribute-mapping="google.subject=assertion.sub" asigna el sujeto de Kubernetes al sujeto de IAM.

Crea los archivos de configuración de credenciales

Para implementar una carga de trabajo de Kubernetes que pueda acceder a Google Cloud recursos, primero debes crear un archivo de configuración de credenciales para cada cuenta de servicio de IAM:

1. Muestra una lista de las cuentas de servicio de IAM (también llamadas "cuentas de servicio de Google") con el siguiente comando:

   gcloud iam service-accounts list --project PROJECT_ID

   Nota: Es probable que ya hayas creado las cuentas de servicio de IAM (también llamadas “cuentas de servicio de Google”) durante la instalación inicial de Apigee hybrid con la herramienta create-service-account. Consulta Acerca de las cuentas de servicio para obtener una lista de las cuentas de servicio de IAM que necesita Apigee hybrid. Consulta Paso 4: Crear cuentas de servicio para conocer el procedimiento de la guía de instalación para crear las cuentas de servicio de IAM.

   Deberás crear los archivos de configuración de credenciales para las siguientes cuentas de servicio de IAM:

   Producción

   Para entornos de producción, haz lo siguiente:

   DISPLAY NAME         EMAIL                                                      DISABLED
   apigee-cassandra     apigee-cassandra@my_project_id.iam.gserviceaccount.com     False
   apigee-mart          apigee-mart@my_project_id.iam.gserviceaccount.com          False
   apigee-metrics       apigee-metrics@my_project_id.iam.gserviceaccount.com       False
   apigee-runtime       apigee-runtime@my_project_id.iam.gserviceaccount.com       False
   apigee-synchronizer  apigee-synchronizer@my_project_id.iam.gserviceaccount.com  False
   apigee-udca          apigee-udca@my_project_id.iam.gserviceaccount.com          False
   apigee-watcher       apigee-watcher@my_project_id.iam.gserviceaccount.com       False
   

   No producción

   Para entornos que no son de producción, haz lo siguiente:

   DISPLAY NAME         EMAIL                                                      DISABLED
   apigee-non-prod      apigee-non-prod@my_project_id.iam.gserviceaccount.com      False
   

   Sugerencia: Si tienes nombres personalizados para tus cuentas de servicio que no se corresponden con facilidad con los nombres de los componentes de Apigee, puedes determinar el rol de cada cuenta de servicio si verificas los roles asignados a ella y los comparas con los roles recomendados en Acerca de las cuentas de servicio.

   Usa el siguiente comando para verificar los roles asignados a una cuenta de servicio:

   gcloud projects get-iam-policy PROJECT_ID  \
     --flatten="bindings[].members" \
     --format='table(bindings.role)' \
     --filter="SERVICE_ACCOUNT_NAME"

   Ten en cuenta qué cuenta de servicio personalizada corresponde a cada cuenta de servicio de IAM que se indica en la lista anterior.

2. Crea un archivo de configuración de credenciales para cada cuenta de servicio de IAM de la lista anterior. Necesitarás estos archivos de configuración de credenciales para configurar Apigee Hybrid para usar la federación de identidades para cargas de trabajo:

   Código

   gcloud iam workload-identity-pools create-cred-config \
     projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
     --service-account=SERVICE_ACCOUNT_EMAIL \
     --credential-source-file=/var/
     --credential-source-type=text \
     --output-file=SERVICE_ACCOUNT_NAME-credential-configuration.json
     

   Ejemplo

   gcloud iam workload-identity-pools create-cred-config \
     projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider \
     --service-account=[e-mail] \
     --credential-source-file=/var/
     --credential-source-type=text \
     --output-file=apigee-cassandra-credential-configuration.json
     

   Aquí:

   • PROJECT_NUMBER: Es el número del proyecto que contiene el grupo de Workload Identity. Debe ser el número del proyecto en lugar del ID del proyecto.
   • POOL_ID: El ID del grupo de identidades para cargas de trabajo
   • WORKLOAD_PROVIDER_ID: El ID del proveedor de grupos de identidades para cargas de trabajo
   • SERVICE_ACCOUNT_EMAIL: Es la dirección de correo electrónico de la cuenta de servicio si configuraste tu cuenta de servicio de Kubernetes para usar la identidad temporal como cuenta de servicio.
   Importante: credential-source-type se debe configurar como text.
   Nota: No crees un archivo de configuración de credenciales para la cuenta de servicio apigee-logger.

   El archivo de configuración de credenciales permite que las [bibliotecas cliente de Cloud](/apis/docs/cloud-client-libraries), gcloud CLI y Terraform determinen lo siguiente:

   • Dónde obtener credenciales externas
   • Qué grupo y proveedor de identidades para cargas de trabajo usar
   • Qué cuenta de servicio actuará en nombre de ella
   Nota: A diferencia de una clave de cuenta de servicio, un archivo de configuración de credenciales no contiene una clave privada y no es confidencial. Los detalles sobre el archivo de configuración de credenciales están disponibles en https://google.aip.dev/auth/4117.

   Configura Apigee Hybrid para usar la federación de identidades para cargas de trabajo

   Sugerencia: Puedes configurar la instalación híbrida a fin de usar la federación de identidades para cargas de trabajo para cualquiera o todos los componentes. Por ejemplo, el UDCA puede usar la federación de identidades para cargas de trabajo, mientras que Synchronizer usa cuentas de servicio de Google IAM o viceversa.
   1. Copia o mueve cada archivo de salida (SERVICE_ACCOUNT_NAME-credential-configuration.json) a los siguientes directorios de gráficos (o sus subdirectorios). Estos son los archivos que creaste en el paso Crea los archivos de configuración de credenciales.

      Producción

      Cuenta de servicio	Directorio de gráficos de Helm para Apigee
      apigee-cassandra	apigee-datastore/
      apigee-mart	apigee-org/
      apigee-metrics	apigee-telemetry/
      apigee-runtime	apigee-env/
      apigee-synchronizer	apigee-env/
      apigee-udca	apigee-org/ apigee-env/
      apigee-watcher	apigee-org/

      No producción

      Cuenta de servicio	Gráfico de Helm para Apigee
      apigee-non-prod	apigee-datastore/ apigee-telemetry/ apigee-org/ apigee-env/

   2. Realiza los siguientes cambios globales en el archivo de anulaciones del clúster:

      Código

      gcp:
        workloadIdentity:
          enabled: false # must be set to false to use Workload Identity Federation
        federatedWorkloadIdentity:
          enabled: true
          audience: "AUDIENCE"
          credentialSourceFile: "/var/run/service-account/token"
      

      Ejemplo

      gcp:
        workloadIdentity:
          enabled: false
        federatedWorkloadIdentity:
          enabled: true
          audience: "//iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider"
          credentialSourceFile: "/var/run/service-account/token"
      

      Nota: Consulta

      • gcp.workloadIdentity.enabled
      • gcp.federatedWorkloadIdentity.enabled
      • gcp.federatedWorkloadIdentity.audience
      • gcp.federatedworkloadIdentity.credentialSourceFile

      Donde: AUDIENCE es el público permitido del proveedor de Workload Identity. Para encontrar el valor, busca el término audience: en cualquiera de los archivos de configuración de credenciales. El valor del público es el mismo en cada archivo de configuración de credenciales.

      Por ejemplo, en el siguiente archivo apigee-udca-credential-configuration.json de muestra:

      {
        "universe_domain": "googleapis.com",
        "type": "external_account:,"
        "audience": "//iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider",
        "subject_token_type": "urn:ietf:params:oauth: token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "service
        "impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[e-mail]:generateAccessToken",
        "credential_source": {
          "file": "/var/run/service-account/token",
          "format": {
            "type": "text"
          }
        }
      }

      El valor del público es //iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider.

   3. Configura las anulaciones para cada componente mediante la federación de identidades para cargas de trabajo. Selecciona las instrucciones para los archivos de certificación, los secrets de Kubernetes o Vault según corresponda para tu instalación.

      Archivo de certificación

      Reemplaza el valor de serviceAccountPath por el archivo fuente de la credencial de la cuenta de servicio de IAM correspondiente. Esta debe ser la ruta de acceso relacionada con el directorio del gráfico. Por ejemplo:

      envs:
      - name: ENVIRONMENT_NAME
        serviceAccountPaths:
          synchronizer: apigee-synchronizer-credential-configuration.json
          runtime: apigee-runtime-credential-configuration.json
          udca: udca-credential-configuration.json
      
      mart:
        serviceAccountPath: mart-credential-configuration.json
      
      connectAgent:
        serviceAccountPath: mart-credential-configuration.json
      
      metrics:
        serviceAccountPath: metrics-credential-configuration.json
      
      udca:
        serviceAccountPath: UDCA_SERVICE_ACCOUNT_FILEPATH
      
      watcher:
        serviceAccountPath: WATCHER_SERVICE_ACCOUNT_FILEPATH
      

      Secreto de K8s

      1. Crea un nuevo secreto de Kubernetes con el archivo fuente de la credencial para cada archivo de configuración de credenciales.

         kubectl create secret -n APIGEE_NAMESPACE generic SECRET_NAME --from-file="client_secret.json=CREDENTIAL_CONFIGURATION_FILE"

         Por ejemplo:

         kubectl create secret -n apigee generic udca-workoad-identity-secret --from-file="client_secret.json=./apigee-udca-credential-configuration.json"

      2. Reemplaza el valor de serviceAccountRef por el secreto nuevo. Por ejemplo:

         udca:
           serviceAccountRef: udca-workoad-identity-secret
         

      Vault

      Actualiza la clave de la cuenta de servicio, SAKEY, para cada cuenta de servicio en Vault con el archivo fuente de la credencial correspondiente. El procedimiento es similar para todos los componentes. Por ejemplo, para el UDCA:

      SAKEY=$(cat .apigee-udca-credential-configuration.json); kubectl -n APIGEE_NAMESPACE exec vault-0 -- vault kv patch secret/apigee/orgsakeys udca="$SAKEY"

      Consulta Storing service account keys in Hashicorp Vault para obtener más información.

   4. Aplica los cambios a cada componente afectado con el comando helm upgrade:

      Si actualizaste las claves de la cuenta de servicio de Vault, actualiza el gráfico apigee-operator.

      helm upgrade operator apigee-operator/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      Actualiza el resto de los gráficos afectados en el siguiente orden:

      helm upgrade datastore apigee-datastore/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      helm upgrade telemetry apigee-telemetry/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      helm upgrade $ORG_NAME apigee-org/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      Actualiza el gráfico apigee-env para cada entorno y reemplaza $ENV_RELEASE_NAME y ENV_NAME cada vez:

      helm upgrade $ENV_RELEASE_NAME apigee-env/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        --set env=$ENV_NAME \
        -f overrides.yaml
      

      Consulta la referencia de Helm de Apigee hybrid para obtener una lista de componentes y sus gráficos correspondientes.

   Otorga acceso a las cuentas de servicio de Kubernetes

   1. Muestra una lista de las cuentas de servicio de Kubernetes con el siguiente comando:

      kubectl get sa -n APIGEE_NAMESPACE

      Nota: Los gráficos de Apigee Hybrid crearon las cuentas de servicio de Kubernetes necesarias para cada componente cuando ejecutaste los comandos helm upgrade.
      Importante: No usarás todas las cuentas de servicio de Kubernetes que se enumeran en este comando.
   2. Otorga a las cuentas de servicio de Kubernetes acceso para actuar en nombre de las cuentas de servicio de IAM asociadas, como se muestra en la siguiente tabla. En la tabla, se muestran los nombres predeterminados de las cuentas de servicio de IAM de Apigee. Si usas nombres de cuentas de servicio personalizados, usa las cuentas de servicio de IAM correspondientes:

      Cuentas de servicio de Kubernetes	Cuenta de servicio de IAM
      Cuentas de servicio de Kubernetes a nivel de la organización
      apigee-connect-agent-ORG_NAME-ORG_HASH_ID	apigee-mart
      apigee-mart-ORG_NAME-ORG_HASH_ID	apigee-mart
      apigee-metrics-apigee-telemetry	apigee-metrics
      apigee-open-telemetry-collector-apigee-telemetry	apigee-metrics
      apigee-udca-ORG_NAME-ORG_HASH_ID	apigee-udca
      apigee-watcher-ORG_NAME-ORG_HASH_ID	apigee-watcher
      Cuentas de servicio de Kubernetes a nivel del entorno
      apigee-runtime-ORG_NAME-ENV_NAME-ENV_HASH_ID	apigee-runtime
      apigee-synchronizer-ORG_NAME-ENV_NAME-ENV_HASH_ID	apigee-synchronizer
      Copia de seguridad y restablecimiento de Cassandra (si está habilitado)
      apigee-cassandra-backup-sa	apigee-cassandra
      apigee-cassandra-restore-sa	apigee-cassandra

      Aquí:

      • ORG_NAME: Los primeros 15 caracteres del nombre de tu organización.
      • ORG_HASH_ID: Un ID de hash único del nombre completo de tu organización.
      • ENV_NAME: Los primeros 15 caracteres del nombre de tu entorno.
      • ENV_HASH_ID: Es un ID de hash único de los nombres de tu organización y entorno.

      Por ejemplo:

      • apigee-connect-agent-myhybridorg-123abcd
      • apigee-runtime-myhybridorg-prodenv-234bcde
      Importante: Deberás repetir este paso para cada entorno.

      Otorga a cada cuenta de servicio de Kubernetes acceso para actuar en nombre de la cuenta de servicio de IAM adecuada con el siguiente comando:

      gcloud iam service-accounts add-iam-policy-binding \
        IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
          --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT" \
          --role=roles/iam.workloadIdentityUser

      Aquí:

      • IAM_SA_NAME: Es el nombre de la cuenta de servicio.
      • PROJECT_ID: Es el ID del proyecto asociado con la organización de Apigee.
      • PROJECT_NUMBER: Es el número del proyecto en el que creaste el grupo de Workload Identity.
      • POOL_ID: El ID del grupo de identidades para cargas de trabajo.
      • MAPPED_SUBJECT: La cuenta de servicio de Kubernetes del reclamo en tu token de ID que asignaste a google.subject Por ejemplo, si asignaste google.subject=assertions.sub y tu token de ID contiene "sub": "system:serviceaccount:default:my-kubernetes-serviceaccount", MAPPED_SUBJECT es system:serviceaccount:default:my-kubernetes-serviceaccount.
      Nota: Debes usar el número de proyecto en el identificador de miembro. No se admite el uso del ID del proyecto.

   Si deseas obtener más información sobre la federación de identidades para cargas de trabajo y las prácticas recomendadas, consulta Prácticas recomendadas para usar la federación de identidades para cargas de trabajo.