> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 再利用可能なサンドボックステンプレートを作成し、そこからサンドボックスを開始し、CKS クラスターに管理者 Pod 設定をアタッチします。

サンドボックステンプレートは、組織スコープの再利用可能な部分的なサンドボックスの spec です。毎回同じコンテナーイメージ、リソース、サービス、ネットワークルールを作成リクエストで繰り返す代わりに、一度テンプレートとして保存し、そこからサンドボックスを開始して、run ごとに異なる部分のみを上書きします。

テンプレートには権限がありません。これらはサンドボックスの spec の出発点であり、[ランナーのポリシー](/ja/products/sandboxes/profiles/configure) が唯一強制力を持つものです。テンプレートから作成されたサンドボックスは、手動で完全な spec を書いた場合とまったく同じように、ポリシーに対して検証されます。

このページでは、テンプレートの作成と管理方法、テンプレートからのサンドボックスの開始方法、一般的なユースケース向けの完全なテンプレートドキュメントを示します。`[TEMPLATE-ID]` をテンプレートの UUID に、`[SNAPSHOT-ID]` をファイルシステムスナップショット ID に、`[GITHUB-ORG]` を GitHub Container Registry の組織またはユーザー名に置き換えてください。

<h2 id="create-a-template">
  テンプレートを作成する
</h2>

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

<Tabs>
  <Tab title="CLI">
    ファイルからテンプレートを作成します:

    ```bash theme={"system"}
    cwic sandbox template create -f template.json
    ```

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

    ```bash theme={"system"}
    cwic sandbox template describe [TEMPLATE-ID]
    ```

    ```bash theme={"system"}
    cwic sandbox template get
    ```
  </Tab>

  <Tab title="curl">
    ```bash title="テンプレートを作成する" theme={"system"}
    curl -X POST https://api.coreweave.com/v1/sandboxTemplates \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d @template.json
    ```

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

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

```json title="template.json" theme={"system"}
{
  "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` を設定するテンプレートは、未実装として拒否されます。
* **テンプレートの内容は組織内のすべてのサンドボックス ユーザーに表示されます。** テンプレートはシークレット配布チャネルではありません。リテラルの認証情報は含めないでください。

<h2 id="start-a-sandbox-from-a-template">
  テンプレートからサンドボックスを起動する
</h2>

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

```bash title="Create a sandbox from a template" theme={"system"}
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` を含む完全なコンテナーを保持する必要があります。

```bash title="Override the container per run" theme={"system"}
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 のワークフローについては、[クライアントドキュメント](/ja/products/sandboxes/client) を参照してください。

<h2 id="example-templates">
  テンプレートのサンプル
</h2>

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

<h3 id="web-service-with-a-public-https-endpoint">
  パブリック HTTPS エンドポイントを持つ Web サービス
</h3>

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

```json title="template.json" theme={"system"}
{
  "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"
        }
      }
    ]
  }
}
```

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

<h3 id="workspace-restored-from-a-snapshot">
  Workspace restored from a snapshot
</h3>

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

```json title="template.json" theme={"system"}
{
  "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]"
        }
      }
    ]
  }
}
```

[ファイルシステムスナップショット](/ja/products/sandboxes/file-system-snapshots) を参照して、このテンプレートがリストアするスナップショットを生成する方法を確認してください。

<h3 id="curated-egress">
  キュレートされた外向き通信
</h3>

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

```json title="template.json" theme={"system"}
{
  "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` が代わりに使用されます。ワークロードの送信先がわかっている場合はテンプレートの外向き通信リストを保持し、ポリシーのデフォルトが適切なポスチャーである場合は空のままにしてください。

<h3 id="cks-only-pod-attachments">
  CKS のみ: Pod のアタッチメント
</h3>

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

```json title="template.json" theme={"system"}
{
  "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 つのレイヤー間で同じ名前のボリューム、環境変数、またはマウントパスの競合がある場合、作成は拒否されます。

<h2 id="manage-templates">
  テンプレートを管理する
</h2>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    cwic sandbox template edit [TEMPLATE-ID] -f template.json
    ```

    ```bash theme={"system"}
    cwic sandbox template delete [TEMPLATE-ID]
    ```
  </Tab>

  <Tab title="curl">
    ```bash title="テンプレートを更新する" theme={"system"}
    curl -X PATCH https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d @template.json
    ```

    ```bash title="テンプレートを削除する" theme={"system"}
    curl -X DELETE https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>
</Tabs>

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

<h2 id="next-steps">
  次のステップ
</h2>

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