サンドボックステンプレート

サンドボックステンプレートは、組織スコープの再利用可能な部分的なサンドボックスの spec です。毎回同じコンテナーイメージ、リソース、サービス、ネットワークルールを作成リクエストで繰り返す代わりに、一度テンプレートとして保存し、そこからサンドボックスを開始して、run ごとに異なる部分のみを上書きします。テンプレートには権限がありません。これらはサンドボックスの spec の出発点であり、ランナーのポリシーが唯一強制力を持つものです。テンプレートから作成されたサンドボックスは、手動で完全な spec を書いた場合とまったく同じように、ポリシーに対して検証されます。このページでは、テンプレートの作成と管理方法、テンプレートからのサンドボックスの開始方法、一般的なユースケース向けの完全なテンプレートドキュメントを示します。[TEMPLATE-ID] をテンプレートの UUID に、[SNAPSHOT-ID] をファイルシステムスナップショット ID に、[GITHUB-ORG] を GitHub Container Registry の組織またはユーザー名に置き換えてください。

テンプレートを作成する

テンプレートは組織管理者が管理します。書き込み操作には sandbox_admin ロールが必要です。組織内のすべてのサンドボックスユーザーはテンプレートを読み取り、それらからサンドボックスを開始できます。

CLI
curl

ファイルからテンプレートを作成します:

cwic sandbox template create -f template.json

既存のテンプレートを検査および一覧表示します:

cwic sandbox template describe [TEMPLATE-ID]

cwic sandbox template get

テンプレートを作成する

curl -X POST https://api.coreweave.com/v1/sandboxTemplates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @template.json

リクエストボディはラッパーオブジェクトではなく、テンプレートドキュメント自体です。

最小限の development-box テンプレートは次のようになります:

template.json

{
  "displayName": "python-dev-box",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "python:3.11",
        "resourceRequirements": {
          "requests": { "cpu": "1", "memory": "2Gi" },
          "limits": { "cpu": "2", "memory": "4Gi" }
        }
      }
    ],
    "maxLifetimeSeconds": 14400,
    "tags": ["dev-box"]
  }
}

すべてのテンプレート書き込みに適用されるルール:

displayName は必須 で、組織のアクティブなテンプレートの中で一意である必要があります。トリミング後 1 ～ 128 文字。UUID 形式の名前は避け、ID 優先のルックアップと衝突しないようにしてください。
spec は部分的なサンドボックスの spec で、最大 1 MiB です。作成リクエストと同じフィールドを使用し、その内容は作成時にすべて上書きできます。
spec はまだインスタンスタイプを選択したり、サンドボックスのネットワークをアタッチしたりできません。 instanceType または networkIds を設定するテンプレートは、未実装として拒否されます。
テンプレートの内容は組織内のすべてのサンドボックスユーザーに表示されます。 テンプレートはシークレット配布チャネルではありません。リテラルの認証情報は含めないでください。

テンプレートからサンドボックスを起動する

ID を使用してテンプレートからサンドボックスを起動します。選択は UUID のみで行えます。表示名はルックアップと一覧表示には使用できますが、作成には使用できません。

Create a sandbox from a template

curl -X POST https://api.cwsandbox.com/v1/sandboxes:createFromTemplate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "[TEMPLATE-ID]" }'

run ごとに何かを変更するには、サンドボックスの spec と同じ形状の overrides を渡します。オーバーライドは存在するフィールド全体を置き換え、マージされません：

設定したメッセージは template のメッセージ全体を置き換えます。省略したメッセージは template の値を保持します。
設定したリストまたはマップは、template のコレクション全体を置き換えます (空に設定した場合も含む) 。1 つのエントリを削除することは、希望する内容の完全なコレクションを送信することを意味します。
任意のコンテナーフィールドをオーバーライドすると、コンテナーリスト全体が置き換えられます。template コンテナーのスパースパッチは存在しないため、コンテナーに触れるオーバーライドは image を含む完全なコンテナーを保持する必要があります。

Override the container per run

curl -X POST https://api.cwsandbox.com/v1/sandboxes:createFromTemplate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "[TEMPLATE-ID]",
    "overrides": {
      "containers": [
        {
          "name": "main",
          "image": "python:3.12",
          "command": "sleep",
          "args": ["infinity"]
        }
      ]
    }
  }'

サンドボックスは、作成時にマテリアライズされた仕様をソーステンプレートのIDとリビジョンとともに保存します。後でテンプレートを編集または削除しても、すでに存在するサンドボックスは変更されません。 Python および TypeScript クライアントは、このエンドポイントを Sandbox.run_from_template() および client.runFromTemplate() としてラップします。SDK のワークフローについては、クライアントドキュメントを参照してください。

テンプレートのサンプル

以下のサンプルは、cwic sandbox template create -f template.json で使用する完全なドキュメントです。ポリシーとは異なり、1 つの組織で複数のテンプレートを保持できるため、繰り返し発生するワークロードの構成ごとに 1 つ作成できます。

パブリック HTTPS エンドポイントを持つ Web サービス

プラットフォームが発行した HTTPS エンドポイントを通じてパブリックインターネットに HTTP を提供するサンドボックス用のテンプレートです。割り当てられた URL は、作成後にサンドボックス上でエコーされます。

template.json

{
  "displayName": "public-http-service",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "python:3.11",
        "command": "python",
        "args": ["-m", "http.server", "8000"]
      }
    ],
    "services": [
      {
        "name": "http",
        "port": 8000,
        "visibility": "VISIBILITY_PUBLIC",
        "endpoint": {
          "kind": "ENDPOINT_KIND_HTTPS",
          "auth": "ENDPOINT_AUTH_OPEN"
        }
      }
    ]
  }
}

選択したランナーのアドバタイズされたネットワーク機能によって公開範囲が決まるため、このテンプレートはパブリックエンドポイント用に設定されたランナーでのみ動作します。

Workspace restored from a snapshot

毎回同じファイルシステムスナップショットから開始するスクラッチボリュームを持つテンプレート：各サンドボックスがプライベートにフォークするゴールデンWorkspace。

template.json

{
  "displayName": "golden-workspace",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "python:3.11",
        "volumeMounts": [{ "volume": "workspace", "mountPath": "/workspace" }]
      }
    ],
    "volumes": [
      {
        "name": "workspace",
        "scratch": {
          "size": "10Gi",
          "restoreFromSnapshotId": "[SNAPSHOT-ID]"
        }
      }
    ]
  }
}

ファイルシステムスナップショットを参照して、このテンプレートがリストアするスナップショットを生成する方法を確認してください。

キュレートされた外向き通信

固定された送信先のセットをグラントするテンプレートです: ポート 443 上の 1 つの CIDR 範囲と、同じ組織内の兄弟サンドボックスです。すべてのルールはランナーのポリシーの allowedEgress 範囲内に当てはまる必要があります。そうでない場合、作成は拒否されます。

template.json

{
  "displayName": "curated-egress",
  "spec": {
    "containers": [{ "name": "main", "image": "python:3.11" }],
    "network": {
      "egress": [
        { "cidr": { "cidr": "140.82.112.0/20" }, "ports": [{ "port": 443 }] },
        { "tenant": "TENANT_SCOPE_SAME_ORG" }
      ]
    }
  }
}

テンプレートで network.egress が空または省略されている場合、ポリシーの defaultEgress が代わりに使用されます。ワークロードの送信先がわかっている場合はテンプレートの外向き通信リストを保持し、ポリシーのデフォルトが適切なポスチャーである場合は空のままにしてください。

CKS のみ: Pod のアタッチメント

ご自身の CKS クラスターでは、Admin がテンプレートに attachments ブロックを配置できます。これは、Kubernetes の Pod 仕様フラグメントで、このテンプレートから作成されるすべてのサンドボックスに適用されます。これにより、テンプレートはノード選択、トレランス、またはサンドボックス仕様自体にフィールドがないプルシークレットを固定できます。

template.json

{
  "displayName": "gpu-training",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "ghcr.io/[GITHUB-ORG]/train:latest",
        "resourceRequirements": {
          "requests": { "cpu": "8", "memory": "32Gi" },
          "limits": { "cpu": "8", "memory": "32Gi" }
        }
      }
    ]
  },
  "attachments": {
    "spec": {
      "nodeSelector": { "workload": "gpu" },
      "tolerations": [
        { "key": "nvidia.com/gpu", "operator": "Exists", "effect": "NoSchedule" }
      ],
      "imagePullSecrets": [{ "name": "regcred" }]
    },
    "metadata": {
      "labels": { "team": "ml" }
    }
  }
}

アタッチメントはテンプレートの動作を変更します：

アタッチメント付きのテンプレートは CKS のみです。 その requiresCks 出力フィールドは true であり、mode を SANDBOX_MODE_SERVERLESS に設定して作成すると FailedPrecondition で失敗します。モードが未設定の場合は CKS として扱われます。
アタッチメントは Admin 所有です。 sandbox_admin のみが書き込み可能で、通常の作成リクエストでは提供できず、作成時のオーバーライドで変更または削除できません。
フラグメントは Kubernetes JSON を使用します。spec および metadata の下に camelCase のキーを使用し、テンプレート内の他のサンドボックス仕様フィールドとは異なります。不明なキーは拒否されます。
許可される範囲は意図的に狭く制限されています：nodeSelector、tolerations、imagePullSecrets、volumes、topologySpreadConstraints、hostAliases、DNS 設定などのスケジューリングおよびランタイム関連の設定と、name、env、envFrom、volumeMounts、volumeDevices に限定された単一の containers エントリに加え、Pod のラベルとアノテーションです。セキュリティに関わるフィールドは拒否されます：securityContext、runtimeClassName、initContainers、affinity、ホスト名前空間、hostPath ボリューム、デフォルト以外のサービスアカウントなど。
アタッチメントはポリシーの base フラグメントの上に重ねられます。 リスト値のフィールドはポリシーのベースと結合されます：imagePullSecrets と tolerations は重複排除され、topologySpreadConstraints、hostAliases、readinessGates は追加されます。nodeSelector キーなどの単一値のフィールドはベースを特化します。2 つのレイヤー間で同じ名前のボリューム、環境変数、またはマウントパスの競合がある場合、作成は拒否されます。

テンプレートを管理する

CLI
curl

cwic sandbox template edit [TEMPLATE-ID] -f template.json

cwic sandbox template delete [TEMPLATE-ID]

テンプレートを更新する

curl -X PATCH https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @template.json

テンプレートを削除する

curl -X DELETE https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
  -H "Authorization: Bearer $TOKEN"

読み取りには ID または表示名を指定できます。 パスの該当部分を UUID として解析できる場合は ID で検索し、それ以外の場合は実行中のテンプレートの表示名として検索します。
更新が成功するたびに、テンプレートの revision が 1 増分されます。 サンドボックスには作成元のリビジョンが記録されるため、テンプレートの変更前に作成されたサンドボックスを特定できます。
削除は論理削除です。 既存のサンドボックスには影響せず、新規作成時にはそのテンプレートを選択できなくなります。また、その表示名を新しいテンプレートに再利用できるようになります。

次のステップ

ポリシーの例: これらのテンプレートと組み合わせる完全なランナーポリシー。
サンドボックスポリシーを設定する: テンプレートの spec が検証される制約グループ。
ポリシー概要: テンプレートとポリシーがプロフィールの作業をどのように分担するか。
独自のコンピュートを使用する: ランナーのセットアップと最初のサンドボックス。