- HTTPS: プラットフォームが発行・更新する証明書を使用して、エッジで TLS を終端し、リクエストを平文の HTTP として指定したポートに転送します。
- TLS パススルー: プラットフォームは、接続を復号せずに、Server Name Indication (SNI) に基づいて指定したポートにルーティングします。ワークロードが TLS を終端し、独自の証明書を管理します。
認証の選択
これらの例は、セクション内で CoreWeave Kubernetes Service (CKS) が指定されていない限り、サーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンの取得方法については、認証情報の選択と取得を参照してください。 使用する言語に対応した設定ファイルを、このページのスクリプトを実行する場所と同じディレクトリに保存します。Python の例ではsandbox_auth.py から AUTH をインポートします。TypeScript の例では sandbox-client.mts から client をインポートします。これらのファイルは認証方式を選択するだけで、認証情報そのものは保存しません。Python の場合は、有効化された仮想環境を使用してください。TypeScript の場合は、まず npm install @coreweave/cwsandbox@1.0.0 でクライアントをインストールしてください。
- Forge APIキー
- CoreWeave API アクセストークン
SDK の
wandb インテグレーションで Forge APIキーを使用します。[WANDB-API-KEY] をお使いの APIキーに置き換えてください。- Python
- TypeScript
sandbox_auth.py
SandboxDefaults で placement_mode="cks" を設定します。TypeScript で CKS を選択するには、CoreWeave トークンを選択し、空でない runnerIds 配列を設定します。auth=AUTH を指定して Python のセッションを作成すると、そのセッションが所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップを行う際は、同じ認証情報を使用してください。
Python の共有トークンの例を実行するには、cwsandbox 1.16.0 以降と、HTTPS 共有トークンをサポートするデプロイメントが必要です。このセクションで設定する認証情報は、サンドボックスの作成や削除などの SDK 操作の認証に使用されます。呼び出し元が保護された HTTPS URL へのアクセスに使用するエンドポイント共有トークンとは別のものです。
2 種類の比較
エンドポイントを宣言する
サンドボックスを作成するときにservices リストでエンドポイントを宣言します。ポートはサンドボックスの有効期間中固定されており、実行中のサンドボックスに対してポートを公開する呼び出しはありません。
サービスに公開エンドポイントを付与するには、visibility=ServiceVisibility.PUBLIC と endpoint の値を設定します。通常のサービスには endpoint の値がありません。たとえば、Service(port=8080, name="web") では可視性とエンドポイントが未設定のままです。この場合、外部への公開は要求されず、コンテナー内部からのみアクセス可能なポートが宣言されます。通常のサービスに設定した可視性は、デプロイメントのサービス ネットワークを介した到達性を制御するものであり、パブリック HTTPS URL や TLS パススルー アドレスを要求するものではありません。
トークンを必須にするには、共有トークンで接続する に示すように EndpointAuth.SHARE_TOKEN を使用します。プラットフォームによる呼び出し元の認証を行わない HTTPS エンドポイントの場合は、kind=EndpointKind.HTTPS と auth=EndpointAuth.OPEN を設定します:
- Python
- TypeScript
kind=EndpointKind.TLS_PASSTHROUGH を設定し、auth を未設定のままにします。プラットフォームは接続を復号せずに転送するため、実行するコマンドはポート自体で TLS を終端する必要があります:
- Python
- TypeScript
OPEN と SHARE_TOKEN の HTTPS エンドポイントを含め、両方の種類のエンドポイントを組み合わせることができます。次のルールが適用されます。
- ポートと名前は、すべての
servicesエントリ間で一意である必要があります。 名前のないポートに対して自動生成される名前も対象です。 endpointを持つエントリにはvisibility=PUBLICが必要です。protocol=TCPを設定するか、protocolを未設定のままにしてください。UDPおよびSCTPのエンドポイントはプラットフォームによって拒否されます。endpointを持たない通常のエントリでは、可視性を未設定のままにするか、PRIVATE、PUBLIC、CUSTOMのいずれかを使用できます。 これらのエントリではTCP、UDP、SCTPを宣言できます。プロトコルを指定しない場合、デフォルトはTCPです。実際の公開範囲は、デプロイメントの機能とポリシーによって決まります。これらのフィールドを設定しても、公開エンドポイントは作成されません。既存のCUSTOMサービスで許可されるソースを変更する方法については、動的ネットワークポリシーを参照してください。- 公開する通常のサービスとエンドポイントエントリを混在させないでください。 エンドポイントを持つサンドボックスでは、通常のサービスの可視性はすべて未設定のままにしてください。エンドポイントがない場合、通常のサービス全体で使用できる公開用の可視性の値は 1 種類までです。
- TLS パススルーの場合は、
authとrequest_timeout_secondsを省略してください。 Python では、0ではなくNoneを渡してください。タイムアウトが設定されていると、値が0であっても SDK によって拒否されます。 - 1 つのサンドボックスで宣言できるサービスの数には、プラットフォームの上限があります。 この上限は、オペレーターがデプロイメントごとに設定します。
共有トークンで接続する
HTTPS エンドポイントでプラットフォームによる認証を必須にするには、auth=EndpointAuth.SHARE_TOKEN を設定します。サンドボックスを作成したハンドルから sandbox.endpoint_share_token を読み取り、その as_headers() の結果を各リクエストに付けて送信します。このヘルパーは X-Sandbox-Share-Token ヘッダーを設定します。プラットフォームは、リクエストを HTTP サービスに転送する前にトークンを検証します。
TypeScript では、auth: "share_token" を設定し、sandbox.endpointShareToken を X-Sandbox-Share-Token リクエストヘッダーに含めて送信します。
トークンは作成時にのみ返されます。取得、リスト、Sandbox.from_id() ではトークンは返されません。元のハンドルは、wait() や get_status() を呼び出した後もトークンを保持します。最初のレスポンスにトークンが含まれていない場合は、sandbox.start().result() が同じ作成ハンドルで復旧を再試行します。それでもトークンが返されない場合は、サンドボックスを停止して新しく作成してください。
トークンは秘密にしてください。as_headers() が返す辞書には認証情報が含まれているため、この辞書はログしないでください。
次の Python の例では、保護された HTTPS エンドポイントの背後で 5 分間動作する HTTP サービスを起動します。URL が割り当てられるのを待機し、アプリケーションとルートが準備完了になるまで、認証付きリクエストを再試行します。リクエストが成功したら、匿名リクエストが拒否されることを確認します。例の終了時には、コンテキストマネージャーがサンドボックスを停止します。
auth=EndpointAuth.OPEN を指定した場合は、サービスが準備完了になれば匿名リクエストが成功します。共有トークンは必要ありません。認証モードを変更するには、サンドボックスを新規作成してください。1 つのサンドボックスに両方のモードを混在させることができ、トークンで保護されるのは SHARE_TOKEN のエンドポイントのみです。
自動生成された エンドポイントリファレンス は Python SDK バージョン 1.14.2 を対象としています。このバージョンは OPEN をサポートしていますが、SHARE_TOKEN が導入される前のものです。
割り当てられたアドレスを取得する
プラットフォームがアドレスを割り当てます。ホスト名を選択したり、独自のドメインを指定したりすることはできません。DNS ゾーンはクラスターごとに異なり、API の契約に含まれないため、アドレスを組み立てるのではなく、サンドボックスから取得してください。 TLS パススルーのアドレスはservice_addresses に host:port 形式で返され、HTTPS URL は service_urls に返されます。これらのリストは別々に保持されます。TLS エンドポイントが service_urls に含まれることはありません。
- Python
- TypeScript
8443 でリッスンし、クライアントは 443 に接続します。
2 種類のアドレスは、サンドボックスの起動時の異なる時点で読み取り可能になります。
- TLS パススルーアドレスは、サンドボックスが作成されたときに割り当てられます。そのため、作成レスポンスに含まれ、サンドボックスが作成中または実行中は利用可能です。
- HTTPS URL は、ルートにホスト名が設定されると利用可能になります。利用できるのは、サンドボックスが作成中または実行中の間です。URL が表示されるか、独自の期限が切れるまで、Python では
get_status()、TypeScript ではinspect()をループで呼び出します。 - どちらも、アプリケーションがサービスを提供していることを意味するわけではありません。 プラットフォームは、プロセスがポートにバインドするのを待たずにサンドボックスを実行中として報告するため、最初の接続を再試行してください。
serviceEndpoints に HTTPS のメタデータが残っている場合でも、停止中または完了したサンドボックスには到達可能なエンドポイントがありません。
TLS パススルー エンドポイントへの接続
プラットフォームは接続を復号しないため、クライアントが受け取る証明書はワークロードが提示するものです。クライアントには以下の 2 点が該当します。- エンドポイント ホストを SNI サーバー名として送信します。 プラットフォームは SNI のみでルーティングするため、これを省略したり別の名前を送信したりすると、サンドボックスに到達しません。
- ワークロードの証明書を信頼します。 エンドポイント ホスト名はプラットフォームが割り当てるため、自分で発行した証明書は、そのホスト名用に発行しない限り一致しません。クライアントを自分の証明書機関を信頼するように設定するか、証明書をピン留めしてください。
[ENDPOINT-ADDRESS] を service_addresses から読み取ったアドレスに置き換え、[PATH-TO-CA-CERT] をワークロードの証明書に署名した証明書機関へのパスに置き換えてください。
エンドポイントの有効期間
エンドポイントは、それを所有するサンドボックスの有効期間と同じだけ存続します:- サンドボックスに紐づけられており、Pod には紐づけられていません。 基盤となる Pod が再起動しても、アドレスは変わりません。
- サンドボックスを削除すると、エンドポイントも削除されます。 アドレスは別のサンドボックスに移行せず、新しいサンドボックスには新しいアドレスが割り当てられます。
- サンドボックス間で何も予約されません。 ホスト名を再利用のために保持することはできません。
作成リクエストの失敗をトラブルシュートする
フリート内のどのランナーもリクエストされたエンドポイントの種類をサポートしていない場合、作成リクエストは失敗し、エンドポイントがサイレントでドロップされた状態でサンドボックスが開始されることはありません。関連ページ
- サンドボックスの設定: リソース、ポート、シークレット、およびタイムアウト。
- サンドボックスのアーキテクチャ: ランナー、プロフィール、およびコントロールプレーンがどのように相互作用するか。
- サンドボックスから tailnet サービスにアクセスする: Tailscale 経由で非公開サービスに外向きに接続する方法。
- サンドボックスのライフサイクル: サンドボックスが経る状態。