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 bac à sable sur le cluster pour exécuter du code non approuvé de manière sécurisée.

Pour obtenir une présentation 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é ce document.

Avant de commencer

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

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

   • Sélectionnez 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 Cloud de Confiance .

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 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.

   Activer les API

4. Dans la console Cloud de Confiance , 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 Cloud de Confiance by S3NS 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 Cloud de Confiance by S3NS dans laquelle 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 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.

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --cluster-version=${CLUSTER_VERSION} \
    --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 dans laquelle se trouve votre cluster existant.

1. Si vous utilisez un cluster GKE Standard, Agent Sandbox 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 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 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).

Si la fonctionnalité est 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). 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).
• Paramètres hostPort.
• sysctl 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 n'est pas compatible avec les pools chauds.

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

Recommandation : créer un SandboxTemplate et un SandboxWarmPool

SandboxTemplate sert de plan 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 revendiqués. L'utilisation de cette ressource personnalisée minimise la latence de démarrage.

Pour déployer un environnement bac à sable en créant 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 un SandboxClaim

SandboxClaim demande un bac à sable à partir du pool chaud. 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 de préchauffage 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 chauds, 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é gérée GKE Agent Sandbox (--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

Migrer à l'aide de l'outil de migration

Pour créer automatiquement des pools de préchauffage 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 de migration détaillé

Pour migrer un cluster existant avec un temps d'arrêt de la charge de travail quasi nul, suivez les trois phases ci-dessous 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 Agent Sandbox déclaratives (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é du modèle : 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 vérification post-migration

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 normal. Le script de migration réécrit tous les enregistrements existants sur 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 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 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 chaud 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 ressources préchauffées 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 ressources préchauffées existant.

• Condition de la 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 de l'Agent Sandbox, 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 Cloud de Confiance by S3NS , 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

• Découvrez comment enregistrer et restaurer des environnements de bac à sable d'agent avec des instantanés de pods.
• En savoir plus sur la technologie sous-jacente utilisée par Agent Sandbox
• En savoir plus sur la sécurité de GKE
• Explorez le projet Open Source Agent Sandbox sur GitHub.
• Découvrez comment utiliser Kata Containers Open Source avec Agent Sandbox. Kata Containers n'est pas un produit Cloud de Confiance . Si vous installez et utilisez ce logiciel, vous êtes responsable de sa gestion et de la résolution des problèmes. L'assistance et les SLA de Google ne s'appliquent pas à Kata Containers.