Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Les utilisateurs de GKE peuvent bénéficier sans frais de l'environnement de bac à sable de l'agent. Les tarifs de GKE s'appliquent 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

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é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.
Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

Accéder au sélecteur de projet
Vérifiez que la facturation est activée pour votre projet Google Cloud .
Activez les API Artifact Registry et Google Kubernetes Engine.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer les API

Dans la console Google Cloud , activez Cloud Shell.

Activer Cloud Shell
Assurez-vous que votre cluster exécute GKE version 1.35.2-gke.1269000 ou ultérieure.

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.35.2-gke.1269000"
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 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. La fonctionnalité Agent Sandbox nécessite la version 1.35.2-gke.1269000 ou 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 le bac à sable de l'agent

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 :

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

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

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

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.35.2-gke.1269000 ou ultérieure.

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.

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

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 de la sandbox de l'agent

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échauffé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 :

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

apiVersion: extensions.agents.x-k8s.io/v1alpha1
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

Appliquez le fichier manifeste SandboxTemplate :
```
kubectl apply -f sandbox-template.yaml
```

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

apiVersion: extensions.agents.x-k8s.io/v1alpha1
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

Appliquez le fichier manifeste SandboxWarmPool :
```
kubectl apply -f sandbox-warmpool.yaml
```

Créer un SandboxClaim

SandboxClaim demande un bac à sable à partir du modèle. 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 modèle en créant un SandboxClaim, procédez comme suit :

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

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

Appliquez le fichier manifeste SandboxClaim :
```
kubectl apply -f sandbox-claim.yaml
```
Vérifiez que le bac à sable, la revendication et le pool de préchauffage sont prêts :
```
kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
```

Autre option : 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 :

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

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: Always
      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

Appliquez le fichier manifeste Sandbox :
```
kubectl apply -f sandbox.yaml
```
Vérifiez que le bac à sable est en cours d'exécution :
```
kubectl get sandbox
```

Désactiver le bac à sable de l'agent

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

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

É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 Google Cloud . Si vous installez et utilisez ce logiciel, vous êtes responsable de sa gestion et du dépannage. L'assistance et les SLA de Google ne s'appliquent pas à Kata Containers.