Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Demander une identité d'agent pour un agent GKE

Autopilot Standard

Les charges de travail d'agent que vous déployez sur des clusters Google Kubernetes Engine (GKE) doivent souvent accéder à des outils et services externes, soit avec leur propre identité, soit au nom des utilisateurs finaux. Les administrateurs de sécurité et de plate-forme souhaitent également savoir ce que font les agents déployés dans les services Google Cloud. Ce document vous explique comment configurer l'authentification pour les charges de travail de l'agent en demandant une identité d'agent pour vos pods. Cette identité d'agent vous permet de configurer l'authentification sans avoir à gérer manuellement les identifiants pour différents workflows. Elle intègre également vos agents GKE à Gemini Enterprise Agent Platform. Ce document est destiné aux développeurs d'applications qui créent et exécutent des charges de travail d'agent sur des clusters GKE.

Vous devez déjà maîtriser les thèmes suivants :

Tarifs

L'identité de l'agent est fournie sans frais supplémentaires dans GKE.

Limites

Vous ne pouvez enregistrer automatiquement que les déploiements dans le registre d'agents. Les autres contrôleurs de charge de travail et les pods statiques ne sont pas compatibles avec l'enregistrement automatique. Bien que vous puissiez demander des identités d'agent pour tous les types de charges de travail, l'enregistrement dans Agent Registry vous permet d'intégrer ces identités à Agent Platform.
Les jetons d'accès à l'identité de l'agent lié n'utilisent que le champ d'application OAuth https://www.googleapis.com/auth/cloud-platform. Vous ne pouvez pas spécifier une portée différente pour les jetons d'accès liés.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

Activez l'API Google Kubernetes Engine.

Activer l'API Google Kubernetes Engine

Pour utiliser Google Cloud CLI pour cette tâche, installez puis initialisez la gcloud CLI. Si vous avez déjà installé la gcloud CLI, obtenez la dernière version en exécutant la commande gcloud components update. Il est possible que les versions antérieures de la gcloud CLI ne permettent pas d'exécuter les commandes de ce document.
Remarque : Pour les installations de la gcloud CLI existantes, veillez à définir la propriété compute/region. Si vous utilisez principalement des clusters zonaux, définissez plutôt compute/zone. En définissant un emplacement par défaut, vous pouvez éviter les erreurs gcloud CLI de ce type : One of [--zone, --region] must be supplied: Please specify location. Vous devrez peut-être spécifier l'emplacement dans certaines commandes si celui de votre cluster diffère de l'emplacement par défaut que vous avez défini.

Activez l'API Agent Registry, si ce n'est pas déjà fait :
Rôles requis pour activer les API
Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.
```
gcloud services enable agentregistry.googleapis.com
```
Vérifiez que vous disposez d'un cluster Autopilot ou standard existant sur lequel la Workload Identity Federation for GKE est activée et qui exécute la version 1.37.0-gke.3503000 ou ultérieure de GKE.
Vérifiez que vous disposez d'un quota suffisant pour les opérations d'échange de jetons. Ce quota est nommé Requêtes de jeton Workload Identity d'échange par minute et par région. Pour en savoir plus, consultez la page Quotas et limites.

Rôles requis

Pour obtenir les autorisations nécessaires pour demander une identité d'agent et déployer des charges de travail, demandez à votre administrateur de vous accorder le rôle IAM Développeur Kubernetes Engine (roles/container.developer) sur votre projet Google Cloud . Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Demander une identité d'agent pour une charge de travail

Pour obtenir une identité d'agent pour les pods, ajoutez des annotations à la spécification de votre pod afin de demander un ID SPIFFE pour la charge de travail et d'injecter le bundle de certificats X.509 dans chaque pod. Pour les pods gérés par des déploiements, vous devez également ajouter une annotation et un libellé pour enregistrer l'agent dans Agent Registry. Bien que l'enregistrement soit facultatif, seuls les agents enregistrés peuvent utiliser les services de la plate-forme d'agent, comme Agent Gateway. Pour en savoir plus sur les annotations et les libellés spécifiques, consultez Configuration au niveau de la charge de travail.

Les étapes suivantes vous expliquent comment créer un exemple de déploiement qui demande des identités d'agent :

Trouvez l'ID de votre organisation. Si votre projet ne fait pas partie d'une organisation, ignorez cette étape et recherchez plutôt le numéro de votre projet.
```
gcloud projects get-ancestors PROJECT_ID
```
Remplacez PROJECT_ID par l'ID du projet de cluster.

Le résultat ressemble à ce qui suit :
```
ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization
```
Notez la valeur du champ ID pour la ressource organization.
Connectez-vous à votre cluster :
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION
```
Remplacez les éléments suivants :
- CLUSTER_NAME : nom du cluster
- CONTROL_PLANE_LOCATION : région ou zone du plan de contrôle de votre cluster.
Créez un espace de noms pour exécuter l'exemple de déploiement :
```
kubectl create namespace NAMESPACE_NAME
```
Remplacez NAMESPACE_NAME par le nom de l'espace de noms.
Créez un compte de service Kubernetes pour le déploiement :
```
kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME
```
Remplacez SERVICEACCOUNT_NAME par le nom du compte de service.

Enregistrez le fichier manifeste de Déploiement suivant sous le nom agent-identity-deployment.yaml :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-identity-deployment
  namespace: NAMESPACE_NAME
  # Add the agent to Agent Registry
  labels:
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  replicas: 2
  selector:
    matchLabels:
      workload-type: agent
  template:
    metadata:
      name: agent-identity-pod
      annotations:
        iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*" # The trust domain from which to assign SPIFFE IDs.
        iam.gke.io/inject-podcertificates: "true" # Inject X.509 certificates and per-Pod private key into each Pod.
        iam.gke.io/spiffe-identity-type: "agent-identity" # Required for Agent Registry registration.
      labels:
        workload-type: agent
    spec:
      serviceAccountName: SERVICEACCOUNT_NAME
      containers:
      - name: agent
        image: python:3.11-slim
        command: ["sleep","infinity"]

Remplacez TRUST_DOMAIN par le domaine de confiance qui émet des identités pour les agents de votre projet. Cette valeur doit utiliser l'une des syntaxes suivantes, selon que votre projet se trouve ou non dans une organisation :

Projets appartenant à une organisation : agents.global.org-ORGANIZATION_ID.system.id.goog, où ORGANIZATION_ID est l'ID de l'organisation.
Projets qui ne font pas partie d'une organisation : agents.global.proj-PROJECT_NUMBER.system.id.goog, où PROJECT_NUMBER correspond au numéro du projet de cluster.

Ce déploiement demande une identité d'agent pour la charge de travail, ajoute les certificats X.509 par pod aux pods et enregistre l'agent dans le registre des agents.

Créez le déploiement :

kubectl apply -f agent-identity-deployment.yaml

Vérifiez que les pods sont en cours d'exécution :

kubectl get pods -l workload-type=agent -n NAMESPACE_NAME

Vérifier l'identité de l'agent attribué

Après avoir déployé une charge de travail qui demande une identité d'agent, vous pouvez vérifier l'identité en consultant les certificats X.509. Si vous désactivez l'injection de certificat, vous pouvez obtenir un jeton d'identité non lié à partir du serveur de métadonnées GKE pour vérifier le champ "Subject", comme décrit dans S'authentifier auprès des API Google Cloud .

Pour lire le certificat X.509 dans un pod, procédez comme suit :

Vérifiez si un pod a accès au certificat X.509 et à la clé privée :
```
kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
```
Remplacez POD_NAME par le nom d'un pod qui utilise l'identité de l'agent.

Le résultat ressemble à ce qui suit :
```
kube-api-access-bx86g
gke-workload-spiffe-credentials
```
Dans ce résultat, le volume gke-workload-spiffe-credentials correspond à l'emplacement des certificats injectés. Si ce volume ne s'affiche pas, vérifiez que l'annotation iam.gke.io/inject-podcertificates est définie sur la valeur true dans la spécification du pod.

Créez une session shell interactive dans le pod :

kubectl exec -n NAMESPACE_NAME -it POD_NAME -- /bin/bash

Dans la session shell, listez les identifiants dans le volume gke-workload-spiffe-credentials :
```
ls -1 /var/run/secrets/workload-spiffe-credentials/
```
Le résultat ressemble à ce qui suit :
```
x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem
```
Le résultat affiche les fichiers suivants :
- x509.credential-bundle.private-key.pem : bundle d'identifiants d'identité de l'agent, qui inclut la chaîne de certificats X.509 et une clé privée unique au pod. Ce bundle d'identifiants est utilisé pour demander des jetons d'accès et des jetons d'identité, et pour s'authentifier auprès des API Google Cloudà l'aide de mTLS.
- TRUST_DOMAIN.spiffe-trust-bundle.pem : bundle de confiance de l'autorité de certification racine, qui contient les certificats autosignés qui constituent l'ancre de confiance pour les identifiants d'identité de l'agent. Ce bundle de confiance est principalement utilisé pour valider les certificats TLS d'autres charges de travail lors des handshakes mTLS.

Pour obtenir l'ID SPIFFE associé au pod, lisez le certificat X.509 :

openssl x509 -in /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem -text -noout

Le résultat ressemble à ce qui suit :

Certificate:
    Data:
    # Multiple lines are omitted here
        X509v3 extensions:
            # Multiple lines are omitted here
            X509v3 Subject Alternative Name: critical
                URI:spiffe://agents.global.org-301928500920.system.id.goog/resources/container/projects/729788050015/locations/us-central1/clusters/cluster-2/ns/agent-identity-ns/sa/agent-identity-sa
    # Multiple lines are omitted here

Dans ce résultat, la valeur du champ URI pour le champ X509v3 Subject Alternative Name correspond à l'ID SPIFFE de l'agent.

Si un ID SPIFFE est attribué à votre pod d'agent, votre demande d'identité d'agent a abouti. Vous pouvez utiliser l'identité attribuée pour vous authentifier auprès de divers outils et services.