始める前に
組織内で Sandbox Admin ロールが付与されている必要があります。このロールがない状態でポリシーの読み取りまたは書き込みを行うと、PermissionDenied が返されます。
CLI のサンプルを使用するには、CoreWeave Intelligent CLI をインストールして認証してください。REST のサンプルを使用するには、CoreWeave API トークンが必要です。サンプルでは、このトークンを $TOKEN、ランナーを prod-us-east-1 と表記しています。
すべてのランナーには必ず 1 つのポリシーが設定されており、ポリシーは必須です。空のポリシーも有効ですが、その場合はベースのデフォルトも明示的な制約も適用されません。ただし、プラットフォームの安全性ゲートは引き続き適用されます。また、ランタイムクラスの許可リストがない場合、特定の runtime_class を固定指定することはできません。セキュリティポスチャーを制約するを参照してください。
現在のポリシーを読み取る
空のドキュメントから作成するのではなく、ランナーに現在設定されている内容を出発点にします。- CLI
- curl
describe を使用します。ランナーにポリシーがない場合は、未設定の状態であることが明示的に表示されます。-o json を指定すると、一度も設定されたことのないランナーでは {} ではなく null が返されます。そのため、オートメーションで「未設定」と「設定済みで制限なし」を区別できます。ポリシーを更新する
ポリシーはランナーのフィールドであるため、更新マスクpolicy を指定してランナーを更新することで設定します。
ポリシーを更新すると、常にドキュメント全体が置き換えられます。 更新マスクのパスとして実装されているのは policy のみであるため、1 つの制約グループだけを変更して残りをそのまま維持することはできません。現在のポリシーを読み取り、必要な箇所を変更してから、ドキュメント全体を送信してください。
- CLI
- curl
ランナーの現在のドキュメントが入力された状態の ファイルから、または 送信前にドキュメントを検証します。
$EDITOR でポリシーを編集します。- を指定して標準入力からドキュメントを適用します。-f を指定した場合、cwic は送信時点でランナーの現在のリビジョンを読み取ります。そのため、それより前に読み取った内容をもとに編集したファイルで、他の管理者の変更を上書きしてしまう可能性があります。ファイルの基になったリビジョンを固定するには、ランナーを 1 回読み取り、その結果からポリシーとその etag を取得します。policy.json を編集し、同じ読み取りで得た etag を指定して送信します。etag は必ずドキュメントを取得したときと同じ読み取りから取得し、後の読み取りから取得しないでください。policy get はポリシーを etag なしでエクスポートします。また、エクスポート後に policy describe を実行すると、より新しいトークンが返される場合があります。このトークンはチェックを通過してしまうため、その間に行われた変更がファイルの内容で上書きされます。curl タブとポリシーを置き換えるでも、同様に 1 つのレスポンスから両方を取得しています。エディターモードでは、エディターに読み込むために取得した etag がそのまま送信されるため、フラグは不要です。現在のドキュメントではなくひな形から作成するには、テンプレートを出力します。- 有効期間の上限は、ポリシーではなくプラットフォームによって決まります。 ポリシーで指定できるのは
constraints.lifecycle.defaultLifetimeSecondsのみで、この値は作成リクエストで有効期間が省略された場合に使用されます。プラットフォームは作成時に、上限 (現在は 30 日) を超える有効期間を拒否します。以前のバージョンのポリシーにはmaxLifetimeSecondsによる上限がありましたが、現在のcwicはこれを含むドキュメントを拒否します。 - 一度設定したポリシーはクリアできません。 削除操作はなく、ポリシーを null に設定する更新は API によって拒否されます。ポスチャーを緩和するには、より制限の緩いドキュメントに置き換えてください。
- ポリシードキュメントのサイズ上限は、エンコード後で 256 KiB です。
ポリシー関連のコマンドは v1 API に対して読み書きを行いますが、その他の
cwic sandbox runner および cwic sandbox profile コマンドは引き続き v1beta2 を使用します。どちらも同じ --api-url 経由でアクセスします。送信元 IP による Sandbox API へのアクセス制限
control_plane_access.source_ip_allowlist を使用すると、送信元アドレスに基づいて Sandbox API リクエストを制限できます。CoreWeave 側で観測されるクライアントの送信元アドレスが、IPv4 または IPv6 の CIDR (Classless Inter-Domain Routing) 範囲に一致している必要があります。この許可リストは、認証、アイデンティティとアクセス管理 (IAM) の権限、および組織の所有権チェックを補完するものです。共有の API endpoint を非公開にするものではなく、サンドボックスが公開するサービスに直接送信されるトラフィックを制限するものでもありません。
API リクエストを送信するクライアントについては、CoreWeave 側で観測されるパブリックな外向き通信のアドレスを指定してください。標準のパブリック NAT (ネットワークアドレス変換) ルーティングを使用する CoreWeave Kubernetes Service (CKS) の Pod 内のクライアントの場合は、その Availability Zone の NAT Egress 範囲を指定します。社内ネットワークまたは VPN (仮想プライベートネットワーク) 上のクライアントの場合は、組織のパブリックな外向き通信の範囲を指定します。Pod やワークステーションのプライベートアドレスは、観測される送信元アドレスの代わりには使用できません。
ランナーのその他のポリシー設定を維持したまま許可リストを追加するには、次の手順を実行します。
-
現在のポリシーをエディターで開きます。
エディターモードでは、ドキュメントを開いた時点の読み取りで取得した
etagが保持されます。そのため、編集中に別の管理者がポリシーを更新した場合、その変更が上書きされることはなく、競合として検出されます。 -
現在のポリシーの最上位に次のフラグメントを追加します。プレースホルダーは、クライアントが実際に使用するパブリックな外向き通信の CIDR に置き換えてください。クライアントが使用しないアドレスファミリーは省略します。その他のポリシーフィールドはそのまま残してください。
-
ドキュメント全体を保存し、エディターを終了します。
etagが古いことを示すエラーが API から返された場合は、現在のポリシーを開き直して変更を再適用し、もう一度保存してください。
source_ip_allowlistが存在しない場合、送信元アドレスによる制限は適用されません。- 許可リストが存在する場合、観測された送信元アドレスが少なくとも 1 つの CIDR に一致する必要があります。
0.0.0.0/0はすべての IPv4 アドレスを、::/0はすべての IPv6 アドレスを許可します。- 入力できるのは、正規化前の時点で最大 256 個の CIDR、CIDR テキスト全体で 16 KiB までです。API は接頭辞を正規化したうえで、重複する接頭辞と、より広いエントリに包含される接頭辞を削除します。
ポリシーの変更とリクエストの動作
ポリシーキャッシュが収束すると、ゲートウェイは、ランナーを選択する際と、既存のサンドボックスに対して新しい操作を実行する前に、更新された許可リストを確認します。対象となるのは、読み取り、コマンド、ファイル転送、ライフサイクル操作、スナップショット、ストリーミングリクエストです。新しいストリーム、再開されたストリーム、別のゲートウェイに転送されたリクエストも確認の対象です。確立済みのストリームは接続が維持されます。 リストリクエストとディスカバリーリクエストでは、送信元アドレスによって拒否されたリソースは結果から除外されます。必須のポリシーをゲートウェイが評価できない場合、アクセス判定を行わないままリソースを返すことはなく、リクエストは失敗します。 ストリーム再開以外のリクエストでは、API は送信元による拒否と、ポリシーの状態を取得できない場合とを区別します。
ストリーム再開時には、送信元アドレスによる拒否が、ストリーム内の
SESSION_NOT_FOUND レスポンスとして返される場合があります。アクセスポリシーを利用できない場合は、この場合も Unavailable (CWSANDBOX_ACCESS_POLICY_UNAVAILABLE) が返されます。
作成リクエストでは、送信元アドレスを許可している別の適切なランナーが引き続き使用される可能性があります。その場合も、認証、リソースの適合性、キャパシティの確認は通常どおり適用されます。
送信元アクセスの制限を解除する
ポリシーの管理には Sandbox Admin ロールが必要ですが、ランナー自体の送信元 IP 許可リストによる制限は受けません。ロックアウトから復旧するには、前述のエディターコマンドで現在のポリシーを開きます。source_ip_allowlist フィールド、またはそれを含む control_plane_access フィールドを削除し、ドキュメント全体を保存します。その他のポリシー設定は変更しないでください。
ポリシーのキャッシュが収束すると、新しいリクエストは送信元アドレスによって制限されなくなります。ただし、認証と認可は引き続き適用されます。フィールドのタイプと検証ルールについては、ポリシーリファレンスの control_plane_access を参照してください。
新しいランナーのデフォルトポリシーを設定する
CoreWeave のホスト型サービスでは、新しいランナー向けのデフォルトポリシーを CoreWeave が設定しています。それ以外のデプロイメントでは、独自のデフォルトを定義できます。ゲートウェイは、ランナーが接続したとき、または v1 配置がポリシーのないランナーを初めて選択したときに、そのポリシーを書き込みます。すでにポリシーがあるランナーでは、既存のポリシーがそのまま維持されます。 デフォルトはゲートウェイのインフラストラクチャー設定gateway.infraConfig.default_runner_policy で定義します。変更を反映するにはゲートウェイの再起動が必要です。組み込みのデフォルトはありません。この設定が存在しないか null の場合は何も書き込まれず、サンドボックスは引き続き CWSANDBOX_POOL_POLICY_NOT_CONFIGURED で拒否されます。
この機能を利用する前に、次の 2 つの動作を把握しておいてください。
- デフォルトはリンクではなく、スナップショットです。 ランナーに書き込まれた時点で、そのポリシーは通常のランナーのポリシーとして扱われます。その後
default_runner_policyを変更しても、すでにポリシーが設定されているランナーには反映されません。それらのランナーはUpdateManagedRunnerで更新してください。 - デフォルトが無効な場合、サンドボックスを作成できなくなります。 ゲートウェイは起動時に設定されたポリシーを検証します。検証に失敗してもゲートウェイ自体は起動しますが、サンドボックスの作成は
CWSANDBOX_SERVERLESS_MISCONFIGUREDで失敗します。
コンピュートを制限する
resources は、コンテナーが要求できるリソースの上限を定めるとともに、サンドボックスで何も要求が指定されていない場合に使用されるデフォルト値を提供します。
requireLimits を true に設定すると、各コンテナーの解決後の割り当てで制限の指定が必須になります。コンテナーでリソース割り当てが省略されている場合、defaultCpu と defaultMemory の両方が 0 より大きい値に設定されていれば、これらの値がリクエストと制限の両方に使用されます。デフォルトが一部しか設定されていない場合、この要件は満たされません。この設定では、制限とリクエストを同じ値にする必要はありません。cpuCeiling と memoryCeiling を使用すると、サンドボックスごとに解決後の合計値の上限を設定できます。これは、ベースレイヤー側でも独自のコンテナーが追加される場合に重要になります。
maxGpuCount は、各コンテナーが要求できる GPU 数の上限を設定します。省略すると上限は適用されません。0 に設定するとすべての GPU リクエストが拒否されるため、GPU を使用しないプールとして構成できます。上限を超えるリクエストは CWSANDBOX_RESOURCE_CEILING_EXCEEDED エラーで失敗します。maxGpuCount を、組織で定められたサンドボックスあたりの GPU 数の最大値より大きく設定しても、その最大値が引き上げられることはありません。詳細については、次を参照してください: GPU リクエストの仕組み。
イメージを制限する
image は、サンドボックスのイメージの取得元を制限します。グループが空の場合は、すべてのイメージが許可されます。[GITHUB-ORG] は、GitHub Container Registry の組織名またはユーザー名に置き換えてください。
ネットワークアクセスを制約する
ネットワーク制約は、許容範囲として機能します。サンドボックスが外向き通信を宣言した場合、ポリシーはその宣言を広げることなく、受け入れるか拒否するかを判定します。サンドボックスが外向き通信を宣言しない場合、ポリシーは外向き通信のデフォルトを適用します。ただし、サンドボックスがdeny_egress を設定している場合は除きます。
2 つの設定は、それぞれ別の役割を担います。
allowedEgressは外向き通信の許可リストで、サンドボックスの作成時にチェックされます。空でない場合、サンドボックスが宣言するすべてのルールがこの範囲内に収まる必要があります。範囲外のルールは、範囲を狭めて受け入れられるのではなく、拒否されます。空の場合は、任意のルールを宣言できます。defaultEgressは、リクエストがない場合の扱いを定義します。サンドボックスが独自の外向き通信を宣言しておらず、かつdeny_egressを設定していない場合にのみ適用されます。何らかの宣言があれば、その宣言に完全に置き換えられます。
cidr(オプションで except による除外範囲を指定可能)、他のサンドボックスとの関係を表す tenant、ラベルで選択したワークロードを表す selector、HTTPS ホスト名を表す httpsHostname、または any を使用します。オプションの ports を指定すると、ルールをさらに絞り込めます。ホスト名ルールで許可されるのは TCP 443 のみで、ホスト名ルールをサポートするランナーが必要です。ホスト名ルールは allowedEgress とサンドボックスのリクエストで指定するもので、defaultEgress には指定できません。
TENANT_SCOPE_SAME_USER と TENANT_SCOPE_SAME_ORG があります。3 つ目の値である TENANT_SCOPE_SANDBOX_NETWORK はまだサポートされておらず、これを使用する外向き通信ルールは拒否されます。
イングレスでは、可視性が CUSTOM のポートに対して allowedIngress と defaultIngress を使用します。許可リストが空でない場合、宣言されたすべてのイングレスルールはその範囲内に収まる必要があります。サンドボックスがイングレスルールを宣言せずに CUSTOM ポートを公開した場合は、deny_ingress が設定されていない限り、defaultIngress が適用されます。明示的なイングレスルールを指定すると、このデフォルトは置き換えられます。イングレスルールで指定できるのは cidr、tenant、any のみで、名前ベースのソースは指定できません。
ホスト名ベースの HTTPS ルールを拒否するには、denyHttpsHostnameRules を設定します。この設定では、DNS クエリや、CIDR ルールで許可された HTTPS はブロックされません。外向きの UDP/TCP ポート 53 をブロックするには、dnsEgress を DNS_EGRESS_MODE_DENY に設定します。省略した場合は、プラットフォームのリゾルバーへの DNS アクセスが許可されます。プラットフォームの DNS とストレージへのアクセスは、送信先ルールとは別に許可されます。包含ルールと DNS の動作については、ネットワーク制約を参照してください。
セキュリティポスチャーを制限する
security は、ゲスト内の権限と、サンドボックスの実行時に適用される分離を制御します。
allowedRuntimeClasses はフェイルクローズで動作します。リストが空または未指定の場合、具体的なランタイムクラスの固定は許可されません。そのため、サンドボックスがクラスを固定できるのは、リストにクラスを明示的に記載した場合のみです。サンドボックスが何も固定しない場合に適用されるクラスを指定するには、defaultCpuRuntimeClass と defaultGpuRuntimeClass を設定します。
または、runtimeClassMappings を設定して、ポータブルなランタイムクラスを実行ターゲットにマッピングすることもできます。マッピングのリストが空でない場合、runtime_class_selection による選択が有効になり、具体的な runtime_class の固定は拒否されます。マッピングは、allowedRuntimeClasses、defaultCpuRuntimeClass、defaultGpuRuntimeClass と併用できません。フィールドと選択ルールについては、RuntimeClassMapping を参照してください。
インスタンス、有効期間、メタデータ、ボリュームを制限する
残りのグループは、いずれも設定項目が少数です。ベースレイヤー
制約は、サンドボックスが要求できる範囲を制限します。一方、base レイヤーは、サンドボックスが要求しなくても一律に付与される設定を提供します。具体的には、スケジューラー、ノードセレクター、トレランス、イメージプルシークレットといったデフォルト値や付加設定です。その形式はランナーのランタイムによって異なり、Kubernetes ランナーでは Pod spec の一部 (フラグメント) となります。デフォルト以外のサービスアカウントは拒否されます。使用可能なフィールドと制限事項については、ベースレイヤーで管理者のデフォルトを固定する を参照してください。
次のステップ
- ポリシーの概要: サンドボックスに適用されるポリシーの解決方法と、プロフィールからの変更点について説明します。
- ランナーのデプロイと管理: ランナーのライフサイクルと、その他のランナー設定について説明します。
- コントロールプレーン API の概要: 認証、フィールドマスク、エンドポイントの仕様について説明します。