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 en 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 la fonctionnalité Agent Sandbox isole le code non approuvé généré par l'IA, consultez À propos de GKE Agent Sandbox.

Coûts

Agent Sandbox est proposé sans frais supplémentaires dans GKE. 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é 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 avez besoin 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.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. 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.35.2-gke.1269000 ou une version 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 actuel. Google Cloud 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 où votre cluster GKE est créé. Google Cloud 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 une 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

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

    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 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, le cluster doit exécuter la version 1.35.2-gke.1269000 ou une version ultérieure.

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

Vous pouvez vérifier si la fonctionnalité Agent Sandbox est activée 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

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 respectées, le contrôleur d'admission rejette le déploiement.

Configuration requise

Le fichier manifeste de votre 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

Le fichier manifeste de votre 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 les 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é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 préchauffé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échauffés sont toujours en cours d'exécution et prêts à être revendiqués. L'utilisation de cette ressource client minimise 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/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

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

  4. Appliquez le fichier manifeste SandboxWarmPool :

    kubectl apply -f sandbox-warmpool.yaml

Créer un SandboxClaim

Le SandboxClaim demande un bac à sable à partir du modèle. Étant donné que vous avez créé un pool préchauffé, 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 :

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

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

  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

Désactiver Agent Sandbox

Pour désactiver la fonctionnalité Agent Sandbox, 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