メインコンテンツまでスキップ

SDKを使用したサンドボックスの作成と管理

備考

ベータ版

この機能はベータ版です。ワークスペースでこの機能プレビューを有効にするには、ワークスペースの「プレビュー」ページで Databricks Sandbox 設定を有効にします。Databricksのプレビューを管理するを参照してください。

Databricks SDK for Pythonには、サンドボックスを作成し、その中でコマンドを実行し、その中で実行されているアプリにポートを転送し、そのライフサイクルを管理するためのサンドボックスクライアントが含まれています。Databricks Sandboxの概要については、「 Databricks Sandbox」を参照してください。

SDKをインストールする​

サンドボックスクライアントが含まれている Databricks SDK for Python をインストールまたはアップグレードします。

Bash
pip install --upgrade databricks-sdk

WorkspaceClientの作成​

すべてのサンドボックス操作は、WorkspaceClientを通じて実行されます。環境、構成プロファイル、または明示的なホストとトークンから解決された資格情報を使用して、WorkspaceClientを作成します。

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

SDK の構成と認証の詳細については、Databricks SDK for Python を参照してください。

サンドボックスを作成する​

IDを指定してサンドボックスを作成します。サンドボックスがアクティビティなしで実行され続ける時間を制御する非アクティブタイムアウトなど、コンピュートの仕様をオプションで構成できます:

Python
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"
ヒント

独自のコンテナイメージからサンドボックスを作成するには、spec.environment.image_uri を設定します。 カスタムイメージからサンドボックスを作成するを参照してください。

サンドボックスの取得と一覧表示​

名前を指定して単一のサンドボックスを取得するか、すべてのサンドボックスを一覧表示します:

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

サンドボックスでコマンドを実行する​

サンドボックスでコマンドを実行し、その出力を読み取ります。最初の引数はサンドボックス名で、その後に実行するプログラムとその引数が続きます。これはシェルなしの直接のexecであるため、シェルコマンドを実行するには /bin/bash -c を呼び出します。envs を介して環境変数を渡します:

Python
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

サンドボックスからのポート転送​

ポート転送を使用して、ローカルマシンからサンドボックスでラン中のWebサーバー、ノートブック、またはAPIにアクセスします。forward() は 127.0.0.1 でリスナーを開き、HTTPおよびWebSocketトラフィックをサンドボックス内のポートにリレーします。これは WorkspaceClient と同じワークスペース資格情報で認証されるため、SSHキーは不要です。ポート転送には databricks-sdk 0.166.0以降が必要です。メソッドのコントラクトおよびサポートされているポート範囲については、SDK forward() のリファレンスを参照してください。

0.0.0.0でリッスンするサンドボックスでアプリを起動してから、そのポートを転送します。アプリをランしたままコマンドが戻るように、アプリをバックグラウンドでランします。

Python
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() ローカルリスナーの準備が完了するとすぐに戻り、close()を呼び出すか、withブロックが終了するまでバックグラウンドで転送をランします。defaultでは、SDKは空いているローカルポートを選択します。fwd.local_portから読み取るか、local_portで特定のポートを設定します。

Python
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()

ポート転送には次の要件と制限があります。

  • サンドボックス内のアプリは、すべてのインターフェイス(0.0.0.0)でリッスンする必要があります。127.0.0.1でのみリッスンするアプリには到達できません。多くの開発サーバーは default で 127.0.0.1 にバインドされるため、uvicorn --host 0.0.0.0、jupyter lab --ip=0.0.0.0、または vite --host などのホストオプションを渡してください。
  • ポート10000から65535までを転送できます。ただし、プラットフォームが予約している10101、18767、19090は除きます。
  • ポート転送は、HTTP/1.1およびWebSocketトラフィックを伝送します。データベースワイヤープロトコルなどのRaw TCPはサポートされていません。
  • 自分が所有しているサンドボックスでのみポートを転送できます。
  • 停止したサンドボックスに対する最初の要求でサンドボックスが起動されます。要求を成功させるには、アプリが要求されたポートで実行されている必要があります。
  • WebSocket接続は最大1時間後に閉じられます。続行するには再接続してください。
注記

Databricks SDK のバージョン 0.164.0 および 0.165.0 では、このメソッドは port_forward() と命名されていました。バージョン 0.166.0 以降では、forward() を使用してください。

Databricks CLIで作成したサンドボックスからポートを転送するには、--の後にSSHオプションを渡します。サンドボックス CLIリファレンスは、このパススルーをドキュメント化しています。リモートシェルを起動せずに接続を維持するには-Nを使用します。

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

サンドボックスのメタデータを更新​

サンドボックスの表示名と非アクティブタイムアウトを更新できます。受け入れられるフィールドパスは次のとおりです。その他のパスでは INVALID_PARAMETER_VALUE が返されます:

  • display_name
  • spec.compute.inactivity_timeout
Python
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"]),
)

サンドボックスの停止と再起動​

ホームディレクトリを保持したままサンドボックスを停止してコンピュートを解放します:

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

作業を再開するにはサンドボックスを再度起動します:

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

サンドボックスは各起動から24時間後に自動的に停止するため、再起動すると新しい24時間サイクルが始まります。Databricks Sandboxの制限事項をご覧ください。

サンドボックスを削除する​

完了したらサンドボックスを削除します。サンドボックスを削除すると、そのホームディレクトリが削除され、サンドボックスの課金が停止します:

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

その他のリソース​