Activer Agent Sandbox sur GKE

Ce document explique comment activer la fonctionnalité Agent Sandbox dans un cluster Google Kubernetes Engine (GKE). Il explique également comment créer un environnement de bac à sable sur le cluster pour exécuter du code non approuvé en toute sécurité.

Pour obtenir un aperçu de la façon dont la fonctionnalité Agent Sandbox isole le code non fiable généré par l'IA, consultez À propos de GKE Agent Sandbox.

Coûts

Agent Sandbox est proposé sans frais supplémentaires dans GKE. La tarification GKE s'applique aux ressources que vous créez.

Pour éviter des frais inutiles, assurez-vous de désactiver GKE ou de supprimer le projet une fois que vous avez terminé de lire ce document.

Avant de commencer

  1. Dans la console Google Cloud , sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud .

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle "Créateur de projet" (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    Accéder au sélecteur de projet

  2. Vérifiez que la facturation est activée pour votre projet Google Cloud .

  3. Activez les API Artifact Registry et Google Kubernetes Engine, 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 via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

  4. Dans la console Google Cloud , activez Cloud Shell.

    Activer Cloud Shell

  5. Assurez-vous que votre cluster exécute GKE version 1.36.3-gke.1767000 ou ultérieure (compatible avec l'API v1beta1).

Définir des variables d'environnement

Pour simplifier les commandes que vous exécutez dans ce document, vous pouvez définir des variables d'environnement dans Cloud Shell. Dans Cloud Shell, définissez les variables d'environnement utiles suivantes en exécutant les commandes suivantes :

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export CLUSTER_VERSION="1.36.3-gke.1767000"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"

Voici une explication de ces variables d'environnement :

  • PROJECT_ID : ID de votre projet Google Cloud actuel. La définition de cette variable permet de s'assurer que toutes les ressources, comme votre cluster GKE, sont créées dans le bon projet.
  • CLUSTER_NAME : nom de votre cluster GKE, par exemple agent-sandbox-cluster.
  • LOCATION : région ou zone Google Cloud dans laquelle votre cluster GKE est créé. Définissez cette option sur la région (par exemple, us-central1) si vous créez un cluster Autopilot, ou sur la zone (par exemple, us-central1-a) si vous créez un cluster Standard.
  • CLUSTER_VERSION : version de GKE que votre cluster exécutera (1.36.3-gke.1767000 ou version ultérieure).
  • NODE_POOL_NAME : nom du pool de nœuds qui exécutera les charges de travail en bac à sable (par exemple, agent-sandbox-pool). Cette variable n'est requise que si vous créez un cluster GKE Standard.
  • MACHINE_TYPE : type de machine des nœuds de votre pool de nœuds, par exemple e2-standard-2. Pour en savoir plus sur les différentes séries de machines et sur le choix entre les différentes options, consultez le Guide des ressources de familles de machines et guide comparatif. Cette variable n'est requise que si vous créez un cluster GKE Standard.

Activer Agent Sandbox

Vous pouvez activer la fonctionnalité Agent Sandbox lorsque vous créez un cluster ou lorsque vous mettez à jour un cluster existant.

Activer Agent Sandbox lors de la création d'un cluster GKE

Nous vous recommandons d'utiliser un cluster Autopilot pour une expérience Kubernetes entièrement gérée. Pour choisir le mode de fonctionnement GKE le mieux adapté à vos charges de travail, consultez la section Choisir un mode de fonctionnement GKE.

Autopilot

Pour créer un cluster GKE Autopilot avec Agent Sandbox activé, incluez le flag --enable-agent-sandbox :

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --cluster-version=${CLUSTER_VERSION} \
    --enable-agent-sandbox

Pour un cluster Autopilot, assurez-vous que la variable d'environnement LOCATION est définie sur une région (par exemple, us-central1).

Standard

Pour créer un cluster GKE Standard avec Agent Sandbox activé, vous devez créer le cluster, ajouter un pool de nœuds avec gVisor activé, puis activer la fonctionnalité Agent Sandbox. Pour réduire les coûts, nous vous recommandons de créer un cluster zonal avec un seul nœud par pool :

  1. Créez le cluster :

    gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --cluster-version=${CLUSTER_VERSION}

    Pour ce cluster Standard, assurez-vous que la variable d'environnement LOCATION est définie sur une zone (par exemple, us-central1-a).

  2. Créez un pool de nœuds distinct avec gVisor activé :

    gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --machine-type=${MACHINE_TYPE} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --image-type=cos_containerd \
    --sandbox=type=gvisor

    Le LOCATION doit être la même zone que celle que vous avez utilisée lors de la création du cluster.

  3. Mettez à jour le cluster pour activer la fonctionnalité Agent Sandbox :

    gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

Activer Agent Sandbox lors de la mise à jour d'un cluster GKE existant

Pour activer Agent Sandbox sur un cluster existant, celui-ci doit exécuter la version 1.36.3-gke.1767000 ou ultérieure, qui est compatible avec l'API v1beta1.

Assurez-vous que votre variable d'environnement LOCATION est définie sur la région ou la zone où se trouve votre cluster existant.

  1. Si vous utilisez un cluster GKE Standard, Agent Sandbox s'appuie sur gVisor. Si votre cluster standard ne comporte pas de pool de nœuds compatible avec gVisor, vous devez d'abord en créer un :

    gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --machine-type=${MACHINE_TYPE} \
    --location=${LOCATION} \
    --image-type=cos_containerd \
    --sandbox=type=gvisor

  2. Mettez à jour le cluster pour activer la fonctionnalité Agent Sandbox :

    gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

Vérifier la configuration

Pour vérifier si la fonctionnalité Agent Sandbox est activée, inspectez la description du cluster.

gcloud beta container clusters describe ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --format="value(addonsConfig.agentSandboxConfig.enabled)"

Si vous avez créé un cluster Autopilot, l'emplacement est la région (par exemple, us-central1). Si vous avez créé un cluster Standard, l'emplacement est la zone (par exemple, us-central1-a).

Si la fonctionnalité est bien activée, la commande renvoie True.

Exigences de déploiement d'Agent Sandbox

Pour déployer correctement une charge de travail, telle qu'un Sandbox ou un SandboxTemplate, votre fichier manifeste YAML doit inclure des paramètres de sécurité et de configuration spécifiques. GKE applique ces exigences à l'aide d'une stratégie d'admission de validation (VAP, Validating Admission Policy). Si ces exigences ne sont pas respectées, le contrôleur d'admission rejette le déploiement.

Configuration requise

Votre fichier manifeste de déploiement doit inclure les paramètres suivants :

  • runtimeClassName: gvisor : garantit que le pod s'exécute dans un bac à sable gVisor.
  • automountServiceAccountToken: false : empêche le pod d'installer automatiquement le jeton de compte de service par défaut.
  • securityContext.runAsNonRoot: true : garantit que le conteneur ne s'exécute pas en tant qu'utilisateur racine.
  • securityContext.capabilities.drop: ["ALL"] : supprime toutes les fonctionnalités Linux du conteneur.
  • resources.limits : vous devez spécifier des limites de processeur et de mémoire pour éviter d'éventuels scénarios de déni de service (DoS).
  • nodeSelector : doit cibler sandbox.gke.io/runtime: gvisor.
  • tolerations : doit inclure une tolérance pour le rejet sandbox.gke.io/runtime=gvisor:NoSchedule.

Configuration interdite

Votre fichier manifeste de déploiement ne doit pas inclure les éléments suivants :

  • hostNetwork: true, hostPID: true ou hostIPC: true.
  • privileged: true dans les contextes de sécurité des conteneurs.
  • HostPath volumes.
  • Ajout de fonctionnalités (capabilities.add).
  • hostPort paramètre.
  • sysctls personnalisés.
  • Volumes prévus pour les jetons ou certificats de compte de service.

Déployer un environnement de bac à sable

Nous vous recommandons de déployer un environnement en bac à sable en définissant un SandboxTemplate et en gardant des instances préchauffées prêtes à l'emploi à l'aide d'un SandboxWarmPool. Vous pouvez ensuite demander une instance à partir de ce pool de nœuds préchauffé à l'aide d'un SandboxClaim. Vous pouvez également créer un bac à sable directement, mais cette approche ne prend pas en charge les pools chauds.

SandboxTemplate, SandboxWarmPool, SandboxClaim et Sandbox sont des ressources personnalisées Kubernetes.

Le SandboxTemplate sert de modèle réutilisable. SandboxWarmPool permet de s'assurer qu'un nombre spécifié de pods préprovisionnés sont toujours en cours d'exécution et prêts à être réclamés. L'utilisation de cette ressource personnalisée réduit la latence de démarrage.

Pour déployer un environnement en bac à sable en créant les SandboxTemplate et SandboxWarmPool, procédez comme suit :

  1. Dans Cloud Shell, créez un fichier nommé sandbox-template.yaml avec le contenu suivant :

    apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox-type: python-runtime
    spec:
      runtimeClassName: gvisor # Required
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: OnFailure

  2. Appliquez le fichier manifeste SandboxTemplate :

    kubectl apply -f sandbox-template.yaml

  3. Créez un fichier nommé sandbox-warmpool.yaml avec le contenu suivant :

    apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: python-runtime-warmpool
  namespace: default
  labels:
    app: python-runtime-warmpool
spec:
  replicas: 2
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

  4. Appliquez le fichier manifeste SandboxWarmPool :

    kubectl apply -f sandbox-warmpool.yaml

Créer une SandboxClaim

Le SandboxClaim demande un bac à sable au pool de préchauffage. Comme vous avez créé un pool de préchauffage, le bac à sable créé adopte un pod en cours d'exécution à partir du pool au lieu de démarrer un nouveau pod.

Pour demander un bac à sable à partir du pool chaud en créant un SandboxClaim, procédez comme suit :

  1. Créez un fichier nommé sandbox-claim.yaml avec le contenu suivant :

    apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  warmPoolRef:
    # This must match the name of the SandboxWarmPool.
    name: python-runtime-warmpool

  2. Appliquez le fichier manifeste SandboxClaim :

    kubectl apply -f sandbox-claim.yaml

  3. Vérifiez que le bac à sable, la revendication et le pool de préchauffage sont prêts :

    kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod

Alternative : Créer un bac à sable directement

Si vous n'avez pas besoin des temps de démarrage rapides fournis par les pools préchauffés, vous pouvez déployer un bac à sable directement sans utiliser de modèles.

Pour déployer un environnement bac à sable en créant directement un bac à sable, procédez comme suit :

  1. Créez un fichier nommé sandbox.yaml avec le contenu suivant :

    apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: OnFailure
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
        runAsUser: 1000 # Required if image defaults to root (e.g. busybox)
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: my-container
        image: busybox
        command: ["/bin/sh", "-c"]
        args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"]
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
          allowPrivilegeEscalation: false
        resources:
          limits:
            cpu: "100m"
            memory: "128Mi" # Required

  2. Appliquez le fichier manifeste Sandbox :

    kubectl apply -f sandbox.yaml

  3. Vérifiez que le bac à sable est en cours d'exécution :

    kubectl get sandbox

Migrer Agent Sandbox de v1alpha1 vers v1beta1

Si votre cluster a été déployé avec une version antérieure d'Agent Sandbox à l'aide de ressources personnalisées v1alpha1, vous pouvez effectuer une mise à niveau vers la version 1.36.3-gke.1767000 de GKE ou une version ultérieure avec un temps d'arrêt des charges de travail quasi nul.

Remarque : Cette procédure de migration s'applique aux clusters utilisant la fonctionnalité GKE Agent Sandbox gérée (--enable-agent-sandbox). Si vous avez déployé Agent Sandbox à l'aide de fichiers manifestes Open Source, consultez le guide de migration en amont.

Principales différences d'API entre v1alpha1 et v1beta1

Concept Comportement de v1alpha1 Comportement v1beta1 Impact de la migration
Cibles SandboxClaim Référence directe autorisée à SandboxTemplate sans pool de préchauffage (démarrage à froid). Nécessite une référence à un SandboxWarmPool (spec.warmPoolRef.name). Les revendications de démarrage à froid doivent être mappées à un pool de préchauffage fantôme (replicas: 0).
Mode de fonctionnement du bac à sable Déduit des champs d'état ou des répliques. Valeur explicite pour le champ spec.operatingMode (par exemple, Running ou Suspended). Le webhook de conversion mappe et définit automatiquement ce champ.
Version de stockage CustomResourceDefinition v1alpha1 stockés dans etcd (storage: true). v1beta1 stocké dans etcd (storage: true). Le webhook effectue une conversion dynamique. L'étape post-mise à niveau persiste à nouveau les objets etcd.
Webhook de conversion Aucune. Actif sur /convert (port 9447). Conversion bidirectionnelle entre v1alpha1 et v1beta1.

Migrer à l'aide de l'outil de migration

Pour créer automatiquement des pools de préchauffage fantômes et re-persister le stockage, utilisez le script de migration canonique du dépôt Agent Sandbox.

Téléchargez et préparez le script :

curl -LO https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.6/helm/files/migrate.sh
chmod +x migrate.sh

Manuel de migration détaillé

Pour migrer un cluster existant avec un temps d'arrêt de la charge de travail quasi nul, procédez comme suit :

Phase 1 : Phase d'amorçage avant la mise à niveau

  1. Sauvegardez les ressources existantes : enregistrez une sauvegarde YAML de vos ressources de bac à sable d'agent déclaratif (sandboxtemplates, sandboxwarmpools et sandboxclaims) :

    kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims \
    --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yaml

  2. Vérifiez la conformité du modèle en termes de sécurité : assurez-vous que les ressources SandboxTemplate existantes répondent aux exigences de déploiement de l'Agent Sandbox. Lors de la migration du stockage à l'étape 3, le contrôleur d'admission refuse les mises à jour des modèles qui ne respectent pas ces règles de sécurité.

  3. Prévisualisez les pools fantômes à créer :

    ./migrate.sh --phase=bootstrap --dry-run

  4. Exécutez la phase d'amorçage :

    ./migrate.sh --phase=bootstrap

  5. Vérifiez les pools fantômes créés :

    kubectl get sandboxwarmpools --all-namespaces \
    -o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,REPLICAS:.spec.replicas,SHADOW:.metadata.annotations.agents\.x-k8s\.io/migration-shadow"

Phase 2 : Mettre à niveau le plan de contrôle GKE

Mettez à niveau le plan de contrôle GKE vers la version 1.36.3-gke.1767000 ou ultérieure :

gcloud container clusters upgrade ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --master \
    --cluster-version=1.36.3-gke.1767000

Lors du déploiement du plan de contrôle, tenez compte des points suivants :

  • Les pods ne subissent aucun redémarrage ni temps d'arrêt.
  • Le nouveau contrôleur et le point de terminaison du webhook /convert sont déployés sur le plan de contrôle.

Phase 3 : Migration du stockage après la mise à niveau

Une fois la mise à niveau du plan de contrôle terminée, actualisez vos identifiants et réécrivez les objets etcd stockés en exécutant la phase de migration du stockage :

./migrate.sh --phase=migrate

Checklist de validation post-migration

Élément à vérifier Commande Résultat attendu
Versions de stockage CustomResourceDefinition kubectl get crd sandboxes.agents.x-k8s.io sandboxclaims.extensions.agents.x-k8s.io sandboxtemplates.extensions.agents.x-k8s.io sandboxwarmpools.extensions.agents.x-k8s.io -o jsonpath='{range .items[*]}{.metadata.name}{": storedVersions="}{.status.storedVersions}{"\n"}{end}' Les quatre CustomResourceDefinitions s'affichent :
storedVersions=["v1beta1"]
Continuité des pods kubectl get pods -n default -o wide Status: 1/1 Running
Restarts: 0
(s'applique aux clusters avec des bacs à sable actifs)
Associer une revendication kubectl get sandboxclaims -n default -o yaml spec.warmPoolRef.name: shadow-pool-...
status.conditions: Ready=True (nécessite que le modèle soit conforme aux conditions d'admission)
Compatibilité avec v1alpha1 kubectl get sandboxes.v1alpha1.agents.x-k8s.io Affiche un avertissement d'abandon et renvoie la ressource
CRUD natif v1beta1 kubectl apply -f sandbox-claim.yaml S'applique sans avertissement

Si une CustomResourceDefinition continue de lister ["v1alpha1", "v1beta1"] dans .status.storedVersions une fois la phase de migration terminée, il s'agit d'un comportement Kubernetes attendu. Le script de migration réécrit tous les enregistrements existants dans v1beta1 dans etcd, mais Kubernetes ne supprime pas automatiquement les versions obsolètes de la liste status.storedVersions.

Après avoir confirmé que toutes les ressources ont été migrées, vous pouvez éventuellement élaguer v1alpha1 à partir des versions stockées :

for crd in \
    sandboxes.agents.x-k8s.io \
    sandboxclaims.extensions.agents.x-k8s.io \
    sandboxtemplates.extensions.agents.x-k8s.io \
    sandboxwarmpools.extensions.agents.x-k8s.io; do
  kubectl patch crd "${crd}" --subresource=status --type=merge \
    -p '{"status":{"storedVersions":["v1beta1"]}}'
done

Résoudre les problèmes de migration

Si vous rencontrez des problèmes après avoir mis à niveau le plan de contrôle ou exécuté la migration du stockage, résolvez-les plutôt que d'essayer de revenir à une version antérieure du plan de contrôle :

  • Revendication bloquée dans l'état WarmPoolNotFound :

    • Si une revendication v1alpha1 de démarrage à froid a été mise à niveau sans exécuter ./migrate.sh --phase=bootstrap, créez manuellement le pool de préchauffage fantôme manquant :

      apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: shadow-pool-TEMPLATE_NAME
  namespace: NAMESPACE
  annotations:
    agents.x-k8s.io/migration-shadow: "true"
spec:
  replicas: 0
  sandboxTemplateRef:
    name: TEMPLATE_NAME

    • Si une revendication mentionne un pool de préchauffage spécifique qui n'existe plus, créez la ressource SandboxWarmPool manquante avec ce nom ou mettez à jour spec.warmPoolRef.name dans la revendication pour faire référence à un pool de préchauffage existant.

  • Condition de revendication Ready=False : exécutez kubectl describe sandboxclaim pour inspecter les événements de la revendication. Assurez-vous que le SandboxTemplate référencé répond à toutes les exigences de déploiement du bac à sable de l'agent et réappliquez le modèle si nécessaire.

  • Erreurs de conversion ou de contrôleur : vérifiez que le bail d'élection du leader du plan de contrôle est actif en exécutant kubectl get leases -n gke-managed-agentsandbox. Si les problèmes persistent, contactez Cloud Customer Care.

Désactiver Agent Sandbox

Pour désactiver la fonctionnalité Bac à sable de l'agent, utilisez la commande gcloud beta container clusters update avec l'option --no-enable-agent-sandbox.

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --no-enable-agent-sandbox

Si vous avez créé un cluster Autopilot, l'emplacement correspond à la région (par exemple, us-central1). Si vous avez créé un cluster Standard, l'emplacement correspond à la zone (par exemple, us-central1-a).

Effectuer un nettoyage des ressources

Pour éviter que des frais ne soient facturés sur votre compte Google Cloud , supprimez le cluster GKE que vous avez créé.

gcloud container clusters delete $CLUSTER_NAME \
    --location=${LOCATION} \
    --quiet

Si vous avez créé un cluster Autopilot, l'emplacement correspond à la région (par exemple, us-central1). Si vous avez créé un cluster Standard, l'emplacement correspond à la zone (par exemple, us-central1-a).

Étapes suivantes