Forge シークレットを使用する

Forge Secret Manager を使用すると、サーバーレスキャパシティ上のサンドボックス内で API トークンなどの認証情報を利用できるようになります。アプリケーションからシークレット名を Sandboxes API に渡すと、API はサンドボックスの作成時に Forge チームから値を取得し、環境変数として注入します。

始める前に

Forge のシークレット注入を使用するには、Forge APIキーで認証されたサンドボックスが必要です。この機能はサーバーレスのサンドボックスで利用できますが、お客様自身の CoreWeave Kubernetes Service (CKS) クラスター上のサンドボックスでは利用できません。CKS への配置では CoreWeave API アクセストークンを使用します。このトークンと別途用意した Forge APIキーを組み合わせて、CKS サンドボックスのシークレットを解決することはできません。

サンドボックスの配置	サンドボックスの認証情報	Forge のシークレット注入
サーバーレス	Forge APIキー	サポートされています。`wandb` ストアを使用します。
サーバーレス	CoreWeave API アクセストークン	サポートされていません。
お客様の CKS クラスター	CoreWeave API アクセストークン	サポートされていません。`FORGE_API_KEY` を追加しても有効にはなりません。

例を実行するには、以下が必要です。

サーバーレスサンドボックスへのアクセス権を持つ Forge の SaaS (Software as a Service) アカウント。
Forge チームの Secret Manager に登録された HF_TOKEN という名前のシークレット。このシークレットが存在しない場合は、Forge の管理者にシークレットの追加を依頼してください。
そのチームへのアクセス権を持つ Forge APIキー。

サンドボックスを作成するプロセスの環境で FORGE_API_KEY を設定します。[FORGE-API-KEY] はお使いの Forge APIキーに置き換えてください。

export FORGE_API_KEY="[FORGE-API-KEY]"

FORGE_TEAM を設定しない場合、各例では APIキーのデフォルトのチームが使用されます。シークレットが別のチームに属している場合は、FORGE_TEAM にそのチームを設定してください。[FORGE-TEAM] はチーム名に置き換えてください。

export FORGE_TEAM="[FORGE-TEAM]"

例では、これらの変数をクライアントに明示的に渡しています。SDK は FORGE_API_KEY や FORGE_TEAM を自動的には検出しません。使用する言語に対応したクライアントをインストールします。

Python
TypeScript

Python 3.11 以降を使用し、必要に応じて uv をインストールします。Python 環境にクライアントをインストールします。

uv pip install 'cwsandbox>=1.14.2'

Node.js 22 以降を使用します。TypeScript クライアントと、例の実行に使用する tsx をインストールします。

npm install @coreweave/cwsandbox
npm install --save-dev tsx

実行する TypeScript の例を secrets.mts として保存し、npx tsx secrets.mts を実行します。

シークレットを注入する

Python では store="wandb"、TypeScript では store: "wandb" を使用します。このストアは、認証済みの Forge チームのシークレットを解決します。この手順では、組織のシークレットストアを登録する必要はありません。以下のサンプルでは、HF_TOKEN を注入し、値を出力せずに存在を確認します。サンドボックス内では、環境変数名はデフォルトでシークレット名になります。

Python
TypeScript

Forge のAPIキーと、必要に応じてチームを AuthHeaders で渡します。

import os
from cwsandbox import AuthHeaders, Sandbox, Secret

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

with Sandbox.run(
  auth=forge_auth,
  placement_mode="serverless",
  container_image="python:3.11",
  resources={"cpu": "1", "memory": "1Gi"},
  secrets=[Secret(store="wandb", name="HF_TOKEN")],
) as sandbox:
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]).result()
  print(result.stdout)

Forge エントリポイントからクライアントをインポートします。runnerIds を省略すると、クライアントはサーバーレスの配置を使用します。

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]),
  {
    containerImage: "python:3.11",
    resources: { cpu: "1", memory: "1Gi" },
    secrets: [{ store: "wandb", name: "HF_TOKEN" }],
  },
);

console.log(result.stdout);

どちらのサンプルも Secret is available を出力し、操作が完了するとサンドボックスを停止します。サンドボックス内で実行されるコードは、HF_TOKEN から値を読み取れます。 secrets には、シークレットの値ではなく名を渡してください。サーバーが値を解決します。値を出力したり、ログに書き込んだりしないでください。

シークレット参照フィールド

Python の Secret または TypeScript の secrets エントリで、次のフィールドを使用します:

Python フィールド	TypeScript フィールド	必須	説明
`store`	`store`	はい	シークレットストア名。Forge Secret Manager には `wandb` を使用します。
`name`	`name`	はい	選択した Forge チームの Secret Manager にあるシークレットの名。
`field`	`field`	いいえ	値が JSON オブジェクトであるシークレットから選択するトップレベルキー。シークレットの値全体を注入するには省略します。
`env_var`	`envVar`	いいえ	値を受け取る環境変数。デフォルトは `name` です。

カスタム環境変数名を使用する

シークレットを受け取る環境変数を指定するには、Python では env_var、TypeScript では envVar を設定します。次の例では、HF_TOKEN シークレットを HUGGINGFACE_TOKEN として公開します。

Python
TypeScript

import os
from cwsandbox import AuthHeaders, Sandbox, Secret

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

with Sandbox.run(
  auth=forge_auth,
  placement_mode="serverless",
  container_image="python:3.11",
  secrets=[Secret(
    store="wandb",
    name="HF_TOKEN",
    env_var="HUGGINGFACE_TOKEN",
  )],
) as sandbox:
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('HUGGINGFACE_TOKEN'); print('Secret is available')",
  ]).result()
  print(result.stdout)

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('HUGGINGFACE_TOKEN'); print('Secret is available')",
  ]),
  {
    containerImage: "python:3.11",
    secrets: [{
      store: "wandb",
      name: "HF_TOKEN",
      envVar: "HUGGINGFACE_TOKEN",
    }],
  },
);

console.log(result.stdout);

どちらの例も、HUGGINGFACE_TOKEN が存在することを確認してから Secret is available を出力します。

構造化されたシークレットからフィールドを選択する

JSON オブジェクトから値を 1 つ注入するには、field にそのトップレベルキーを設定します。ネストされたパスはサポートされません。JSON string の場合、注入される値には JSON の引用符は付きません。この例では、{"password":"[DB-PASSWORD]"} のような JSON オブジェクトを値とする、DB_CREDENTIALS という名のチームシークレットを追加します。シークレットを保存する前に、[DB-PASSWORD] をパスワードに置き換えてください。以下のサンプルでは、その password フィールドを DB_PASSWORD に注入します。

Python
TypeScript

import os
from cwsandbox import AuthHeaders, Sandbox, Secret

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

with Sandbox.run(
  auth=forge_auth,
  placement_mode="serverless",
  container_image="python:3.11",
  secrets=[Secret(
    store="wandb",
    name="DB_CREDENTIALS",
    field="password",
    env_var="DB_PASSWORD",
  )],
) as sandbox:
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('DB_PASSWORD'); print('Secret is available')",
  ]).result()
  print(result.stdout)

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('DB_PASSWORD'); print('Secret is available')",
  ]),
  {
    containerImage: "python:3.11",
    secrets: [{
      store: "wandb",
      name: "DB_CREDENTIALS",
      field: "password",
      envVar: "DB_PASSWORD",
    }],
  },
);

console.log(result.stdout);

どちらのサンプルも、パスワードを出力せずに Secret is available を出力します。シークレットが JSON オブジェクトでない場合、キーが存在しない場合、またはその値が null の場合、フィールドの選択は失敗します。

シークレット参照の再利用

Python セッションの場合、共有シークレット参照を SandboxDefaults に配置します。TypeScript の場合は、サンドボックスを作成するときに secrets 配列を再利用します:

Python
TypeScript

import os
from cwsandbox import AuthHeaders, SandboxDefaults, Secret, Session

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

defaults = SandboxDefaults(
  auth=forge_auth,
  placement_mode="serverless",
  secrets=(Secret(store="wandb", name="HF_TOKEN"),),
)

with Session(defaults) as session:
  sandbox = session.sandbox()
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]).result()
  print(result.stdout)

Python クライアントは、セッションのデフォルトをサンドボックスごとの secrets とマージし、完全に同一のものは無視します。異なる参照が同じ環境変数をターゲットにする場合、クライアントはサンドボックスを作成する前に ValueError を送出します。Python のタイプシグネチャについては、Secret reference を参照してください。

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});
const secrets = [{ store: "wandb", name: "HF_TOKEN" }];

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]),
  { containerImage: "python:3.11", secrets },
);

console.log(result.stdout);

シークレット注入のトラブルシューティング

シークレット参照を指定したサンドボックスが起動しない場合は、エラーテキストに基づいて認証、選択したチーム、配置を確認します。

エラーテキスト	確認事項
`secret store "wandb" not found`	クライアントが CoreWeave 認証を選択しているか確認します。サーバーレス配置の場合は、例に示すように、Python では `AuthHeaders`、TypeScript では `@coreweave/cwsandbox/wandb` の `createSandboxClient` を使用して Forge の認証情報を渡します。`FORGE_API_KEY` を設定するだけでは、CoreWeave 認証を使用するクライアントは Forge 認証に切り替わりません。ストアを登録する必要はありません。
`one or more W&B secrets not found`	シークレット名と選択した Forge チームを確認します。シークレットが APIキーのデフォルトの entity とは異なるチームに属する場合は、`FORGE_TEAM` を設定し、Forge アカウントからアクセスできることを確認します。
`entity not found`	`FORGE_TEAM` に入力ミスがないか確認し、チームが存在することと、Forge アカウントからアクセスできることを確認します。
`no eligible runner is available on this replica right now; retry shortly`	Forge 認証で CKS ランナーを選択した場合、この組み合わせはサポートされていません。再試行しても有効にはなりません。シークレット注入には、Forge 認証とサーバーレス配置を使用してください。サーバーレスのリクエストでは、このエラーはランナーが一時的に利用できないことを示している場合があります。

CoreWeave API アクセストークンと Forge APIキーの両方を設定した場合も含め、CKS 配置では Forge シークレット注入を利用できません。

サンドボックス

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

サンドボックスの管理

リファレンス

Forge シークレットを使用する

始める前に

シークレットを注入する

シークレット参照フィールド

カスタム環境変数名を使用する

構造化されたシークレットからフィールドを選択する

シークレット参照の再利用

シークレット注入のトラブルシューティング

​始める前に

​シークレットを注入する

​シークレット参照フィールド

​カスタム環境変数名を使用する

​構造化されたシークレットからフィールドを選択する

​シークレット参照の再利用

​シークレット注入のトラブルシューティング

始める前に

シークレットを注入する

シークレット参照フィールド

カスタム環境変数名を使用する

構造化されたシークレットからフィールドを選択する

シークレット参照の再利用

シークレット注入のトラブルシューティング