Activer Agent Sandbox sur GKE

Ce document explique comment activer Agent Sandbox sur Google Kubernetes Engine (GKE) dans un cluster. 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 une présentation de la façon dont Agent Sandbox sur GKE isole le code non approuvé généré par l'IA, consultez À propos d'Agent Sandbox sur GKE.

Coûts

Agent Sandbox sur GKE est proposé sans frais supplémentaires. La tarification de 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 Google Cloud console, sur la page de sélection du projet, sélectionnez ou créez un Google Cloud projet.

    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 Google Cloud projet.

  3. Activez les API Artifact Registry et Google Kubernetes Engine, si elles ne le sont pas déjà.

    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 obtenir cette autorisation via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

  4. Dans la Google Cloud console, 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 Google Cloud projet 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 : Google Cloud région ou zone où votre cluster GKE est créé. Définissez cette valeur 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 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 sur GKE

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

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

Nous vous recommandons d'utiliser un cluster GKE 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 sur GKE activé, incluez l'option --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 sur GKE activé, vous devez créer le cluster, ajouter un pool de nœuds avec gVisor activé, puis activer Agent Sandbox sur GKE. 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

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

  3. Mettez à jour le cluster pour activer Agent Sandbox sur GKE :

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

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

Pour activer Agent Sandbox sur GKE dans un cluster existant, le cluster 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 sur GKE s'appuie sur gVisor. Si votre cluster Standard ne dispose pas d'un pool de nœuds avec gVisor activé, 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 Agent Sandbox sur GKE :

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

Vérifier la configuration

Vous pouvez vérifier si Agent Sandbox sur GKE est activé en inspectant 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 activée, la commande renvoie True.

Exigences de déploiement d'Agent Sandbox sur GKE

Pour déployer une charge de travail, telle qu'un Sandbox ou 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). Si ces exigences ne sont pas remplies, 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 de monter 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 les scénarios potentiels de déni de service (DoS).
  • nodeSelector : doit cibler sandbox.gke.io/runtime: gvisor.
  • tolerations: doit inclure une tolérance pour la contamination 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.
  • Volumes HostPath.
  • Fonctionnalités ajoutées (capabilities.add).
  • Paramètres hostPort.
  • Sysctls personnalisés.
  • Volumes projetés pour les jetons ou certificats de compte de service.

Déployer un environnement en bac à sable

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

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

Le SandboxTemplate sert de modèle réutilisable. Le 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 revendiqué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 le SandboxTemplate et le 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 un SandboxClaim

Le SandboxClaim demande un bac à sable à partir du pool préprovisionné. Étant donné que vous avez créé un pool préprovisionné, 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 préprovisionné 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 préprovisionné sont prêts :

    kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod

Autre solution : créer un bac à sable directement

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

Pour déployer un environnement en bac à sable en créant un bac à sable directement, 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 sur GKE de v1alpha1 vers v1beta1

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

Remarque : Cette procédure de migration s'applique aux clusters utilisant la fonctionnalité gérée Agent Sandbox sur GKE (--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 entre les API v1alpha1 et v1beta1

Concept Comportement v1alpha1 Comportement v1beta1 Impact de la migration
Cibles SandboxClaim Référence directe autorisée à SandboxTemplate sans pool préprovisionné (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 préprovisionné fantôme (replicas: 0).
Mode de fonctionnement du bac à sable Déduit des champs de répliques ou d'état. 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é 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 Aucun. 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 préprovisionnés fantômes et persister à nouveau 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 d'exécution de la migration pas à pas

Pour migrer un cluster existant avec un temps d'arrêt de la charge de travail quasi nul, effectuez les trois phases suivantes dans l'ordre :

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

  1. Sauvegardez les ressources existantes : enregistrez une sauvegarde YAML de vos ressources déclaratives Agent Sandbox sur GKE (sandboxtemplates, sandboxwarmpools et sandboxclaims) :

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

  2. Vérifiez la conformité de la sécurité des modèles : assurez-vous que les ressources SandboxTemplate existantes répondent aux exigences de déploiement d'Agent Sandbox sur GKE. Lors de la migration du stockage à la phase 3, le contrôleur d'admission rejette les mises à jour de tous les modèles qui ne sont pas conformes à 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 4 CustomResourceDefinitions affichent :
storedVersions=["v1beta1"]
Continuité du pod kubectl get pods -n default -o wide Status: 1/1 Running
Restarts: 0
(s'applique aux clusters avec des bacs à sable actifs en cours d'exécution)
Liaison de revendication kubectl get sandboxclaims -n default -o yaml spec.warmPoolRef.name: shadow-pool-...
status.conditions: Ready=True (nécessite la conformité du modèle aux exigences d'admission)
Compatibilité v1alpha1 kubectl get sandboxes.v1alpha1.agents.x-k8s.io Affiche un avertissement d'obsolescence et renvoie la ressource
CRUD natif v1beta1 kubectl apply -f sandbox-claim.yaml S'applique avec 0 avertissement

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

Une fois que vous avez confirmé que toutes les ressources sont migrées, vous pouvez éventuellement supprimer v1alpha1 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 la mise à niveau du plan de contrôle ou l'exécution de la migration du stockage, résolvez-les plutôt que d'essayer de rétrograder le plan de contrôle :

  • Revendication bloquée dans 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 préprovisionné 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 a nommé un pool préprovisionné spécifique qui n'existe plus, créez la ressource SandboxWarmPool manquante avec ce nom ou mettez à jour spec.warmPoolRef.name sur la revendication pour référencer un pool préprovisionné 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 d'Agent Sandbox sur GKE, 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 le problème persiste, contactez l'assistance Cloud Customer Care.

Désactiver Agent Sandbox sur GKE

Pour désactiver Agent Sandbox sur GKE, 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 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).

Effectuer un nettoyage des ressources

Pour éviter que des frais ne soient facturés sur votre Google Cloud compte, 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 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).

Étape suivante