Gérer les bacs à sable

Cette page explique comment gérer le cycle de vie de vos environnements de bac à sable à l'aide du SDK Python. Vous pouvez lister les bacs à sable existants, afficher leurs détails, les suspendre et les réactiver, ou les supprimer lorsqu'ils ne sont plus nécessaires.

Avant de commencer

Pour gérer les bacs à sable, vous devez disposer des rôles suivants sur votre projet :

  • Utilisateur Agent Platform (roles/aiplatform.user)

Gérer les bacs à sable

Vous pouvez lister, afficher les détails, suspendre, reprendre et supprimer les environnements de bac à sable associés à une instance Agent Platform. La mise en pause et la reprise vous permettent de déprogrammer les ressources de calcul pour les bacs à sable inactifs et de les remettre en ligne ultérieurement sans perdre l'état du système de fichiers ni l'identité de connexion. Pour modifier la configuration d'un bac à sable existant, vous devez le supprimer et en créer un autre.

Lister les bacs à sable

Pour lister tous les bacs à sable associés à une instance Agent Platform :

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région Google Cloud de votre instance Agent Platform. Consultez Régions prises en charge.
  • INSTANCE_ID : ID de l'instance Agent Platform.

Afficher les détails du bac à sable

Pour afficher la configuration et l'état d'un bac à sable spécifique :

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région Google Cloud de votre instance Agent Platform. Consultez Régions prises en charge.
  • INSTANCE_ID : ID de l'instance Agent Platform qui contient votre bac à sable.
  • SANDBOX_ID : ID du bac à sable existant.

Le résultat inclut des détails tels que l'heure de création, l'état (par exemple, STATE_RUNNING) et la spécification du bac à sable.

Suspendre un bac à sable

La mise en pause d'un bac à sable libère ses ressources de calcul tout en préservant l'état du disque et les métadonnées de connexion. Les bacs à sable mis en pause coûtent beaucoup moins cher que ceux en cours d'exécution et peuvent être réactivés en quelques secondes. Utilisez la mise en pause lorsqu'un bac à sable est inactif pendant une période prolongée, mais que vous souhaitez conserver l'état de la session et l'identité de la connexion pour une utilisation ultérieure.

Les bacs à sable mis en pause présentent les caractéristiques suivantes :

  • Conservez l'ID de bac à sable, les métadonnées de connexion et tout point de terminaison Private Service Connect.
  • Conservez l'état de tous les systèmes de fichiers dans le conteneur au moment de la mise en pause.
  • Passer à STATE_PAUSED. Les requêtes envoyées à leur point de terminaison du plan de données renvoient des erreurs jusqu'à ce que vous les réactiviez.

Pour suspendre un bac à sable en cours d'exécution, exécutez le code suivant :

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région Google Cloud de votre instance Agent Platform. Consultez Régions prises en charge.
  • INSTANCE_ID : ID de l'instance Agent Platform qui contient votre bac à sable.
  • SANDBOX_ID : ID du bac à sable existant.

Réactiver un bac à sable

La reprise d'un bac à sable mis en pause remet en ligne ses ressources de calcul. Le bac à sable conserve le même ID, le même point de terminaison de connexion (y compris tout rattachement de service Private Service Connect) et le même état du système de fichiers qu'au moment de la mise en pause. Les requêtes du plan de données peuvent être envoyées à nouveau au bac à sable dès que l'opération de reprise est terminée.

Pour reprendre un bac à sable suspendu, exécutez le code suivant :

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région Google Cloud de votre instance Agent Platform. Consultez Régions prises en charge.
  • INSTANCE_ID : ID de l'instance Agent Platform qui contient votre bac à sable.
  • SANDBOX_ID : ID du bac à sable mis en pause.

Supprimer un bac à sable

Pour supprimer explicitement un environnement de bac à sable et libérer des ressources :

client.sandboxes.delete(name=sandbox_name)
print("Sandbox deleted.")

Journalisation et surveillance des audits

Lorsque vous gérez et exécutez des commandes dans des bacs à sable, Agent Platform enregistre l'activité au niveau de l'API dans Cloud Audit Logs sous le nom de service aiplatform.googleapis.com et le type de ressource surveillée audited_resource :

  • Journaux d'activité d'administration (ADMIN_WRITE) : enregistrés automatiquement pour les mutations du cycle de vie du plan de contrôle, y compris CreateSandboxEnvironment, PauseSandboxEnvironment, ResumeSandboxEnvironment, SnapshotSandboxEnvironment et DeleteSandboxEnvironment (nécessitant des autorisations IAM aiplatform.sandboxEnvironments.*).
  • Journaux d'accès aux données (ADMIN_READ) : enregistrés lorsqu'ils sont activés pour les opérations de lecture de métadonnées, y compris GetSandboxEnvironment et ListSandboxEnvironments.
  • Journaux d'accès aux données (DATA_WRITE) : enregistrés lorsqu'ils sont activés pour l'exécution des commandes du plan de données et les appels d'autorisation d'accès, y compris ExecuteSandboxEnvironment, BidiExecuteSandboxEnvironment, AuthorizeSandboxEnvironmentAccess et ExecuteCode. Pour les ressources protégées par VPC Service Controls, les charges utiles de requête et de réponse sont omises des journaux d'audit.

Tenez compte des limites d'observabilité et de détection des menaces suivantes :

  • Activité des processus et des flux dans le conteneur : Cloud Audit Logs consigne la requête API qui lance l'exécution de la commande ou autorise une connexion, mais ne consigne pas les processus enfants individuels générés dans le conteneur, les modifications du système de fichiers ou les frames interactifs ultérieurs envoyés via une session WebSocket, protocole Chrome DevTools (CDP) ou PTY ouverte.
  • Journalisation des conteneurs stdout et stderr : la collecte Cloud Logging automatique pour Agent Runtime (comme reasoning_engine_stdout et reasoning_engine_stderr) ne s'applique qu'à l'instance parente ReasoningEngine et ne collecte pas automatiquement les journaux des ressources enfants du bac à sable. Le résultat de la commande (stdout, stderr et codes de sortie) est renvoyé dans la réponse d'exécution à votre agent parent, où vous pouvez inspecter et écrire des entrées structurées dans Cloud Logging.
  • Détection des menaces et inspection du réseau : les bacs à sable appliquent le confinement via l'isolation du noyau gVisor et une identité sans privilèges dans le bac à sable, sans identifiants ambiants Google Cloud . Pour surveiller les comportements anormaux ou les sorties réseau non autorisées, combinez les journaux d'audit DATA_WRITE avec la détection d'anomalies de l'agent sur l'agent parent et acheminez la sortie du bac à sable via une interface Private Service Connect avec les journaux de flux VPC, la journalisation des règles Cloud Next Generation Firewall (Cloud NGFW) et l'inspection Secure Web Proxy. Pour en savoir plus, consultez Limites de sécurité, d'identité et d'observabilité.