Crea e gestisce sandbox con l'SDK

Importante

Questa funzionalità è in versione beta. Per abilitare questa anteprima di funzionalità nello spazio di lavoro, opta per l'impostazione Sandbox Databricks nella pagina Anteprime dello spazio di lavoro. Vedere Gestire le anteprime di Azure Databricks.

L'SDK Databricks per Python include un client sandbox per creare sandbox, eseguire comandi al loro interno, inoltrare le porte alle app che vi sono in esecuzione e gestire il loro ciclo di vita. Per una panoramica di Databricks Sandbox, vedi Databricks Sandbox.

Installare l'SDK

Installa o aggiorna l'SDK Databricks per Python, che include il client sandbox:

pip install --upgrade databricks-sdk

Crea un WorkspaceClient

Tutte le operazioni sandbox vengono eseguite attraverso un WorkspaceClient. Crea un WorkspaceClient utilizzando le credenziali recuperate dall'ambiente, da un profilo di configurazione o da un host e un token espliciti:

from databricks.sdk import WorkspaceClient

# Resolve credentials from the environment or the default config profile:
w = WorkspaceClient()

# Or select a specific ~/.databrickscfg profile:
w = WorkspaceClient(profile="my-workspace")

# Or pass the host and token explicitly:
w = WorkspaceClient(host="https://<workspace>.cloud.databricks.com", token="dapi...")

Per ulteriori informazioni sulla configurazione e autenticazione dell'SDK, consulta Databricks SDK per Python.

Crea un sandbox

Crea una sandbox tramite ID. Puoi opzionalmente configurare la specifica di calcolo, come il timeout di inattività che controlla quanto a lungo il sandbox rimane attivo senza attività:

from google.protobuf.duration_pb2 import Duration
from databricks.sdk.service.sandbox import ComputeSpec, Sandbox, SandboxSpec

created = w.sandbox.create_sandbox(
    sandbox=Sandbox(
        spec=SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=900))),
    ),
    sandbox_id="my-sandbox",
)
print(created.name)   # "sandboxes/my-sandbox"

Tip

Per creare un sandbox dalla tua immagine container, imposta spec.environment.image_uri. Vedi Crea un sandbox da un'immagine personalizzata.

Ottieni e elenca sandbox

Recupera un singolo sandbox per nome, oppure elenca tutti i sandbox:

sandbox = w.sandbox.get_sandbox("sandboxes/my-sandbox")
print(sandbox.status.state)   # SandboxState.SANDBOX_STATE_RUNNING

for sandbox in w.sandbox.list_sandboxes():
    print(sandbox.name, sandbox.status.state if sandbox.status else None)

Esegui un comando in un ambiente sandbox

Esegui un comando in un sandbox e leggi il suo output. Il primo argomento è il nome sandbox, seguito dal programma da eseguire e dai suoi argomenti. Questo è un exec diretto senza shell, quindi, per eseguire un comando della shell, richiama /bin/bash -c. Fai passare qualsiasi variabile ambientale attraverso envs:

from google.protobuf.duration_pb2 import Duration

resp = w.sandbox.execute_command_sync(
    "sandboxes/my-sandbox",
    "/bin/bash",
    args=["-c", "echo hello world && whoami"],
    envs={"MY_VAR": "value"},
    execution_timeout=Duration(seconds=30),
)
print(resp.status)      # ExecuteCommandStatus.EXECUTE_COMMAND_STATUS_COMPLETED
print(resp.exit_code)   # 0
print(resp.stdout)      # "hello world\nsandbox-agent\n"
print(resp.stderr)
print(resp.truncated)   # True if the output was truncated

Inoltrare una porta da un ambiente sandbox

Usa il port forwarding per raggiungere un server web, un notebook o un'API in esecuzione in una sandbox dal tuo computer locale. forward() apre un listener su 127.0.0.1 e inoltra il traffico HTTP e WebSocket a una porta nella sandbox. Si autentica con le stesse credenziali dell'area di lavoro di WorkspaceClient, quindi non hai bisogno di chiavi SSH. Il port forwarding richiede databricks-sdk versione 0.166.0 o successiva. Consulta il riferimento dell'SDK forward() per la firma del metodo e l'intervallo di porte supportato.

Avvia un'app nella sandbox che ascolta su 0.0.0.0, poi inoltra la sua porta. Esegui l'app in background in modo che il comando ritorni mentre l'app continua a funzionare:

w.sandbox.execute_command_sync(
    "sandboxes/my-sandbox",
    "/bin/bash",
    args=["-c", "nohup python3 -m http.server 10080 --bind 0.0.0.0 > /tmp/server.log 2>&1 &"],
)

with w.sandbox.forward("sandboxes/my-sandbox", 10080) as fwd:
    print(fwd.url)          # http://127.0.0.1:<local-port>
    input("Press Enter to stop forwarding...")

forward() Ritorna non appena l'ascoltatore locale è pronto e l'inoltro viene eseguito in background finché non chiami close() o finché il with blocco non esce. Per impostazione predefinita, l'SDK sceglie una porta locale gratuita. Leggi la porta da fwd.local_port, oppure imposta una porta specifica con local_port:

fwd = w.sandbox.forward("sandboxes/my-sandbox", 10080, local_port=8080)
# Open http://127.0.0.1:8080 in a browser or send requests with curl.
fwd.close()

Il port forwarding ha i seguenti requisiti e limitazioni:

  • L'app nella sandbox deve ascoltare su tutte le interfacce (0.0.0.0). Le app che ascoltano solo su 127.0.0.1 sono irraggiungibili. Molti server di sviluppo rimangono in ascolto su 127.0.0.1 di default, quindi passa un'opzione host, come uvicorn --host 0.0.0.0, jupyter lab --ip=0.0.0.0 o vite --host.
  • Puoi inoltrare le porte 10000 a 65535, eccetto 10101, 18767 e 19090, che la piattaforma riserva.
  • Il port forwarding trasporta traffico HTTP/1.1 e WebSocket. Il TCP grezzo, come un protocollo di wire di database, non è supportato.
  • Puoi inoltrare le porte solo nelle sandbox che possiedi.
  • La prima richiesta a una sandbox arrestata la avvia. L'app deve essere in esecuzione sulla porta richiesta affinché la richiesta abbia successo.
  • Le connessioni WebSocket si chiudono dopo al massimo 1 ora. Riconnettiti per continuare.

Note

Nelle versioni 0.164.0 e 0.165.0 dell'SDK Databricks, questo metodo era chiamato port_forward(). Nella versione 0.166.0 e successiva, usa forward().

Per reindirizzare una porta da una sandbox creata utilizzando la Databricks CLI, specifica le opzioni SSH dopo --. Il riferimento della CLI Sandbox documenta questo inoltro. Usare -N per mantenere aperta la connessione senza avviare una shell remota:

databricks sandbox ssh -- -N -L 8080:localhost:8080

Aggiorna i metadati sandbox

Puoi aggiornare il nome visualizzato e il timeout di inattività di una sandbox. Sono accettati solo i seguenti percorsi di campo. Qualsiasi altro percorso restituisce INVALID_PARAMETER_VALUE:

  • display_name
  • spec.compute.inactivity_timeout
from databricks.sdk.common.types.fieldmask import FieldMask
from databricks.sdk.service.sandbox import ComputeSpec, Sandbox, SandboxSpec
from google.protobuf.duration_pb2 import Duration

# Rename the sandbox
w.sandbox.update_sandbox(
    name="sandboxes/my-sandbox",
    sandbox=Sandbox(display_name="renamed sandbox"),
    update_mask=FieldMask(["display_name"]),
)

# Extend the inactivity timeout
w.sandbox.update_sandbox(
    name="sandboxes/my-sandbox",
    sandbox=Sandbox(spec=SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=1800)))),
    update_mask=FieldMask(["spec.compute.inactivity_timeout"]),
)

Fermati e riavvia un sandbox

Arresta un sandbox per liberare le relative risorse di calcolo mantenendo la tua directory home:

w.sandbox.stop_sandbox("sandboxes/my-sandbox")    # Moves to SANDBOX_STATE_STOPPED

Riavvia la sandbox per riprendere il lavoro:

w.sandbox.start_sandbox("sandboxes/my-sandbox")   # Moves to SANDBOX_STATE_RUNNING

Un sandbox si interrompe automaticamente 24 ore dopo ogni avvio, quindi riavviarlo inizia un nuovo periodo di 24 ore. Vedi limitazioni Sandbox di Databricks.

Eliminazione di un sandbox

Elimina un sandbox quando hai finito. L'eliminazione di un sandbox rimuove la sua directory home e interrompe la fatturazione del sandbox:

w.sandbox.delete_sandbox("sandboxes/my-sandbox")

Risorse aggiuntive