クリーンアップパターン

このガイドでは、サンドボックスのリソース管理とクリーンアップ戦略について説明します。信頼できるクリーンアップにより、スクリプト終了後に孤立したサンドボックスが発生するのを防ぎ、コストを予測可能に保ち、意図しないコンピュートリソースの使用を回避できます。ここで紹介するパターンは、明示的なセッションの有無にかかわらず、1 つまたは複数のサンドボックスを作成するスクリプトに適用されます。

認証を選択する

セクション内で CKS が指定されていない限り、これらの例はサーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンを取得するには、認証情報の選択と取得を参照してください。インストールコマンドは、有効化した Python 仮想環境で実行してください。使用する認証情報のタブにある Python コードを sandbox_auth.py という名前で、このページで実行する Python スクリプトと同じディレクトリに保存します。このファイルに保存されるのは認証方式の選択であり、認証情報そのものではありません。各例ではこのファイルから AUTH をインポートし、新しいサンドボックスやセッションを作成するたびに明示的に渡します。

Forge API キー
CoreWeave API アクセストークン

SDK の W&B 認証方式を使用して、Forge APIキーで認証します。

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

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

CKS に配置する場合は、CoreWeave トークンを選択し、ランナーを有効化したうえで、サンドボックスの作成時または SandboxDefaults で placement_mode="cks" を設定します。auth=AUTH を指定してセッションを作成すると、そのセッションが所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップを行う際も、同じ認証情報を使用してください。

自動クリーンアップ

自動クリーンアップは、サンドボックスの有効期間をPythonのコンテキストマネージャー、またはプロセスの終了時にSDKが閉じるSessionに結び付けます。SDKは明示的な stop() 呼び出しなしにリソースを解放します。 Sessionやコンテキストマネージャーの外で Sandbox.run() を使用して開始したサンドボックスは、スクリプトの終了後も実行され続けることがあります。サンドボックスは、メインコマンドが正常に終了した場合 (終了ステータス 0)、ユーザーが停止した場合、または最大ライフタイムに達した場合に停止します。0 以外の終了ステータスで終了すると、コンテナーの自動再起動がトリガーされることがあります。再起動の上限に達すると、サンドボックスは失敗します。詳細はメインコマンドの有効期間を参照してください。

コンテキストマネージャー (推奨)

コンテキストマネージャーは、囲まれたコードが例外を送出する場合でもクリーンアップを保証するため、推奨されるパターンです。SDK はコンテキストが終了するとサンドボックスを停止します：

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# sandbox.stop() は自動的に呼び出されます

セッションはすべてのサンドボックスをクリーンアップします：

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH) as session:
    sb1 = session.sandbox()
    sb2 = session.sandbox()
# 両方のサンドボックスは自動的に停止されます

グローバルなクリーンアップハンドラ

SDK は、プロセスの終了時に、登録済みのSessionが所有するサンドボックスを停止するクリーンアップハンドラを登録します。Sessionやコンテキストマネージャーを使わずに作成したスタンドアロンのサンドボックスは、明示的にクリーンアップする必要があります。

シナリオ	動作
スクリプトの正常終了	`atexit` ハンドラが登録済みSession内のサンドボックスを停止します
Ctrl+C (`SIGINT`)	シグナルハンドラが登録済みSession内のサンドボックスを停止します
`SIGTERM`	シグナルハンドラが登録済みSession内のサンドボックスを停止します
2 回目の Ctrl+C	強制終了します (シャットダウン時に応答しなくなるのを防ぎます)

SDK は、コードで最初にサンドボックスを作成した時点でこれらのハンドラをインストールします。SIGINT と SIGTERM のハンドラは、Python のメインスレッドから実行された場合にのみインストールされます。アプリケーションで独自にシグナルを処理している場合は、最初のサンドボックスを作成する前に cwsandbox.disable_signal_handlers() を呼び出すか、CWSANDBOX_DISABLE_SIGNAL_HANDLERS=1 を設定してください。この場合も atexit ハンドラは実行されますが、シグナル受信時にはアプリケーション側でサンドボックスを停止する必要があります。

手動クリーンアップ

サンドボックスまたはセッションをいつリリースするかを明示的に制御する必要がある場合に、手動クリーンアップを使用します。手動クリーンアップでは、停止オプションを渡したり、長時間実行されるコード全体でクリーンアップを調整したりできます。

サンドボックス stop()

次の例では、個別のサンドボックスを停止する方法と、停止時に指定できる省略可能なパラメーターを示します。

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH)
result = sandbox.exec(["echo", "hello"]).result()
sandbox.stop().result()

# オプション付き
sandbox.stop(graceful_shutdown_seconds=30.0).result()
sandbox.stop(snapshot_on_stop=True).result()
sandbox.stop(missing_ok=True).result()  # すでに存在しない場合は無視

Session close()

Session を閉じると、その Session が所有するサンドボックスがすべて停止します。

from sandbox_auth import AUTH
from cwsandbox import SandboxDefaults

session = cwsandbox.Session(SandboxDefaults(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH)
sandbox = session.sandbox()
# ...
session.close().result()  # すべてのサンドボックスを停止します

バッチのクリーンアップ

次の例では、複数のサンドボックスを並列で停止します。

from sandbox_auth import AUTH
from cwsandbox import results

sandboxes = [
    Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH)
    for _ in range(5)
]
# ... サンドボックスを使用する ...
results([sb.stop() for sb in sandboxes])  # すべてを並列で停止

孤立したサンドボックス management

孤立したサンドボックスとは、作成したプロセスの終了後も意図せず実行され続けているサンドボックスです。意図的に実行し続けているスタンドアロンのサンドボックスは孤立したサンドボックスではありませんが、その所在を把握できなくなると孤立したサンドボックスになります。以下のセクションでは、孤立したサンドボックスを検索しやすくする方法、孤立したサンドボックスをクエリする方法、および管理されたクリーンアップの下に戻す方法について説明します。

ディスカバリーのためのタグ付け

タグを使用して、後で孤立したサンドボックスを発見できるようにします。Sessionやコンテキストマネージャー内のサンドボックスは、SDK の自動クリーンアップによって、ほとんどの場合孤立せずに済みます。ただし、強制シャットダウン (kill -9) やネットワーク障害が発生した後は、これらのサンドボックスも実行され続けることがあります。また、クリーンアップハンドラはスタンドアロンのサンドボックスを停止しないため、停止し忘れると孤立したサンドボックスになります。

from sandbox_auth import AUTH
from cwsandbox import Sandbox, SandboxDefaults

# 作成時にタグを付ける
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project", "batch-job-123"),
    resources={"cpu": "1", "memory": "1Gi"},
)

with Sandbox.run(defaults=defaults, auth=AUTH) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()

サンドボックスを見つけやすくするには、次のタグを使用します：

project またはアプリケーション名 (my-project)
ジョブまたはrunの識別子 (batch-job-123, run-2024-01-15)
環境 (dev, staging, prod)

孤立したサンドボックスを検索する

タグでクエリして、以前の run からサンドボックスを検索します：

from sandbox_auth import AUTH
from cwsandbox import Sandbox

orphans = Sandbox.list(tags=["my-project"], auth=AUTH).result()
for sandbox in orphans:
    sandbox.stop().result()

セッションの取り込み

孤立したサンドボックスを取り込むと、それをセッションにアタッチし、セッションがその有効期間を管理します。その後、孤立したサンドボックスは新しく作成されたサンドボックスと同じ自動クリーンアップ保証を受けます。session.list() はセッションのデフォルトのタグをフィルターに追加するため、それらのタグが付いたサンドボックスのみが検索されます。セッションのタグを適用せずに検索するには、Sessions ガイドにあるように、Sandbox.list() を使用して、取得した各サンドボックスを取り込みます：

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH) as session:
    orphans = session.list(tags=["my-project"]).result()
    for sandbox in orphans:
        session.adopt(sandbox)
# セッションで取り込まれたすべてのサンドボックスはクリーンアップされます

ID を指定して停止する

以前のrun時に ID を保存しておいたサンドボックスを停止するには、同じ認証情報で再接続します。[SANDBOX-ID] をサンドボックス ID に置き換えてください。

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.from_id("[SANDBOX-ID]", auth=AUTH).result()
sandbox.stop(missing_ok=True).result()

停止リクエストを送る前にサンドボックスが消失していた場合は、missing_ok=True オプションによって SandboxNotFoundError が抑制されます。ただし、Sandbox.from_id() によるルックアップの失敗は抑制されません。サンドボックスがすでに存在しない場合、この呼び出しでは引き続き SandboxNotFoundError が送出されます。

Delete by ID

graceful_shutdown_seconds や snapshot_on_stop などのオプションを使用するには、サンドボックスのインスタンスに対して stop() を呼び出します。Sandbox.delete() はインスタンスを作成せず、ID を指定して直接削除します。サンドボックスの ID をすでに知っている場合は、まず list したり取り込んだりせずに削除できます：

from sandbox_auth import AUTH
from cwsandbox import Sandbox

Sandbox.delete("sandbox-abc123", auth=AUTH).result()
Sandbox.delete("sandbox-abc123", missing_ok=True, auth=AUTH).result()  # 存在しなければ無視します

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

クリーンアップパターン

認証を選択する

自動クリーンアップ

コンテキストマネージャー (推奨)

グローバルなクリーンアップハンドラ

手動クリーンアップ

サンドボックス stop()

Session close()

バッチのクリーンアップ

孤立したサンドボックス management

ディスカバリーのためのタグ付け

孤立したサンドボックスを検索する

セッションの取り込み

ID を指定して停止する

Delete by ID

​認証を選択する

​自動クリーンアップ

​コンテキストマネージャー (推奨)

​グローバルなクリーンアップハンドラ

​手動クリーンアップ

​サンドボックス stop()

​Session close()

​バッチのクリーンアップ

​孤立したサンドボックス management

​ディスカバリーのためのタグ付け

​孤立したサンドボックスを検索する

​セッションの取り込み

​ID を指定して停止する

​Delete by ID

認証を選択する

自動クリーンアップ

コンテキストマネージャー (推奨)

グローバルなクリーンアップハンドラ

手動クリーンアップ

サンドボックス stop()

Session close()

バッチのクリーンアップ

孤立したサンドボックス management

ディスカバリーのためのタグ付け

孤立したサンドボックスを検索する

セッションの取り込み

ID を指定して停止する

Delete by ID