Connexions directes aux Sandbox

Une connexion directe à une Sandbox achemine les opérations d’exécution, de journalisation et sur les fichiers directement de votre client vers la Sandbox via TLS mutuel (mTLS), sans passer par la passerelle CoreWeave Sandboxes. En supprimant ce saut intermédiaire, vous réduisez la latence et augmentez le débit des charges de travail qui transfèrent de grands volumes de données vers et depuis une Sandbox. Les opérations de cycle de vie et de gestion, comme le démarrage, l’affichage de la liste ou l’arrêt des Sandbox, passent toujours par l’API CoreWeave Sandboxes. Une connexion directe ne s’applique qu’aux opérations sur les données d’une Sandbox déjà en cours d’exécution. Cette page s’adresse aux développeurs qui utilisent le SDK Python cwsandbox pour lancer et gérer des Sandbox. Elle explique comment choisir une politique de transport pour les opérations sur les données, comment le SDK établit une connexion directe et comment vérifier le transport utilisé par une opération.

Choisir l’authentification

Ces exemples s’exécutent sur une capacité sans serveur, sauf si une section indique CKS. Choisissez l’identifiant d’authentification du compte propriétaire de vos Sandbox. Pour obtenir une clé ou un jeton, consultez Choisir et obtenir des identifiants d’authentification. Exécutez les commandes d’installation dans un environnement virtuel Python actif. Enregistrez le code Python de l’onglet correspondant à votre identifiant d’authentification sous le nom sandbox_auth.py, dans le même répertoire que les scripts Python que vous exécutez depuis cette page. Ce fichier enregistre la méthode d’authentification choisie, et non votre identifiant d’authentification. Les exemples importent AUTH depuis ce fichier et le transmettent explicitement à chaque nouvelle Sandbox ou session.

Clé API Forge
Jeton d’accès à l’API CoreWeave

Utilisez votre clé API Forge avec la stratégie d’authentification W&B du SDK :

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Utilisez le jeton de votre organisation CoreWeave :

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

Pour un placement sur CKS, choisissez le jeton CoreWeave, activez un exécuteur et définissez placement_mode="cks" lors de la création de la Sandbox ou dans SandboxDefaults. Une session créée avec auth=AUTH authentifie également les Sandbox qui lui appartiennent. Utilisez le même identifiant d’authentification pour vous reconnecter aux Sandbox, les lister ou les nettoyer.

Aperçu

L’enum DataPlaneMode définit la politique de transport des opérations sur les données. Le SDK utilise AUTO sauf indication contraire de votre part : la plupart des appelants bénéficient ainsi de connexions directes sans modifier leur code.

Mode	Comportement	Quand l’utiliser
`AUTO`	Privilégie une connexion mTLS directe et bascule de manière transparente vers la passerelle lorsque l’accès direct n’est pas disponible.	Valeur par défaut. Utilisez-la, sauf si vous devez imposer un transport précis.
`DIRECT`	Exige la connexion mTLS directe et lève une erreur si celle-ci ne peut pas être établie.	Pour vérifier que la connectivité directe fonctionne dans votre environnement.
`GATEWAY`	Achemine toujours les opérations sur les données via la passerelle.	Solution de retour arrière déterministe lorsque vous devez écarter le transport direct.

Définir la politique de transport

Pour définir la politique de transport d’une seule Sandbox, passez data_plane_mode à Sandbox.run(). Pour la définir pour un groupe de Sandbox, passez data_plane_mode à SandboxDefaults.

from sandbox_auth import AUTH
from cwsandbox import DataPlaneMode, Sandbox, SandboxDefaults

# AUTO est la valeur par défaut : privilégie le chemin direct, avec repli sur la passerelle.
with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
    print(result.stdout)

# Exiger le chemin direct. Utile pour valider la connectivité.
with Sandbox.run(
    data_plane_mode=DataPlaneMode.DIRECT,
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) as sandbox:
    print(sandbox.read_file("/etc/hostname").result().decode())

# Forcer le passage par la passerelle pour chaque sandbox utilisant ces valeurs par défaut.
defaults = SandboxDefaults(
    data_plane_mode=DataPlaneMode.GATEWAY,
    resources={"cpu": "1", "memory": "1Gi"},
)
with Sandbox.run(defaults=defaults, auth=AUTH) as sandbox:
    print(sandbox.exec(["echo", "gateway"]).result().stdout)

Établissement d’une connexion directe

Lorsqu’une sandbox est en cours d’exécution et que vous lancez sa première opération sur les données, le SDK génère en mémoire une clé privée P-256 et n’envoie qu’une demande de signature de certificat à l’API CoreWeave Sandboxes. L’API renvoie un certificat limité à cette sandbox, que le SDK utilise pour ouvrir une connexion mTLS directement avec la sandbox. Deux propriétés de cet échange sont à prendre en compte lorsque vous réfléchissez aux identifiants d’authentification :

La clé privée ne quitte jamais le processus client. Le SDK transmet une demande de signature de certificat, et non la clé.
Votre jeton Bearer d’API n’est jamais envoyé au point de terminaison de données de la sandbox. La sandbox authentifie le client uniquement au moyen de son certificat.

Le SDK crée les identifiants d’authentification à la demande : une sandbox qui n’exécute que des appels de cycle de vie n’en demande donc jamais. Le SDK s’appuie sur la date d’expiration du certificat fixée par le serveur, sans imposer de son côté une durée de vie de session plus courte.

Délais et repli

AUTO et DIRECT diffèrent par la durée d’attente et par ce qui se passe lorsque la configuration ne se termine pas à temps.

En mode AUTO, l’émission des identifiants d’authentification et la mise en état de préparation du canal se partagent un budget d’une seconde. Une fois ce budget épuisé, l’opération transite par la passerelle et le SDK attend 30 secondes avant de retenter une connexion directe. Le repli est transparent : l’opération aboutit quand même.
En mode DIRECT, la configuration de la connexion dispose d’un délai maximal de 10 secondes, sans repli. Si la configuration n’aboutit pas, l’opération lève une erreur.

Réutilisation des connexions

Le SDK maintient, à l’échelle du processus, un pool de canaux directs inactifs limité à 64. Grâce à cette limite, un programme qui conserve un grand nombre d’objets sandbox inactifs ne garde pas un socket ouvert par sandbox. Un flux actif conserve le canal sur lequel il a démarré. Lorsqu’un canal est marqué comme obsolète, les flux existants s’y terminent progressivement, tandis que les nouveaux appels créent un canal de remplacement.

Vérifier le transport utilisé par une opération

Pour confirmer que la connectivité directe fonctionne depuis votre environnement, exécutez une opération en mode DIRECT. Ce mode ne bascule jamais vers une solution de repli : une opération qui aboutit a donc forcément utilisé le transport direct. Une opération qui ne parvient pas à établir la connexion lève une erreur au lieu de basculer silencieusement sur la passerelle.

from sandbox_auth import AUTH
from cwsandbox import DataPlaneMode, Sandbox

with Sandbox.run(
    data_plane_mode=DataPlaneMode.DIRECT,
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) as sandbox:
    result = sandbox.exec(["echo", "direct"]).result()
    print(result.stdout)

Si cette opération génère une erreur alors que le même appel en mode GATEWAY réussit, le point de terminaison de données de la sandbox n’est pas joignable depuis votre réseau. Laissez les appelants en mode AUTO pour qu’ils continuent de fonctionner via la passerelle pendant que vous vérifiez les restrictions de trafic sortant entre votre client et la sandbox.

Voir aussi

Architecture des bacs à sable : comment s’articulent le plan de contrôle, la passerelle et les exécuteurs.
Exécution : lancer des commandes dans une sandbox.
Opérations sur les fichiers : lire et écrire des fichiers dans une sandbox.
Configuration du bac à sable : les autres options que vous pouvez définir via SandboxDefaults et Sandbox.run().

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Connexions directes aux Sandbox

Choisir l’authentification

Aperçu

Définir la politique de transport

Établissement d’une connexion directe

Délais et repli

Réutilisation des connexions

Vérifier le transport utilisé par une opération

Voir aussi

​Choisir l’authentification

​Aperçu

​Définir la politique de transport

​Établissement d’une connexion directe

​Délais et repli

​Réutilisation des connexions

​Vérifier le transport utilisé par une opération

​Voir aussi

Choisir l’authentification

Aperçu

Définir la politique de transport

Établissement d’une connexion directe

Délais et repli

Réutilisation des connexions

Vérifier le transport utilisé par une opération

Voir aussi