NetworkConfigService は、CoreWeave Sandboxes の組織スコープのネットワーク設定を管理します。各設定は適用したい NetworkOptions を保持し、終了状態ではないサンドボックス 1 つにバインドできます。バインド済みの設定を更新すると、サンドボックスを再起動することなく、そのサンドボックスにルールが適用されます。手順ガイドについては、実行中のサンドボックスのネットワークアクセスを変更する を参照してください。
可用性と前提条件
NetworkConfigService を使用するには、組織にサービスを提供している API で NetworkConfig のサポートが有効になっている必要があります。このサポートが有効になっていない場合、そのリモートプロシージャコール (RPC) は UNIMPLEMENTED (理由: CWSANDBOX_NOT_IMPLEMENTED) を返します。また、ライブ更新を行うには、ランナーでライブネットワーク更新が有効になっている必要があります。サーバーレスのサンドボックスでは、これらの設定は CoreWeave が管理します。CoreWeave Kubernetes Service (CKS) のマネージドランナーでは、spec.overrides.env.ENABLE_LIVE_NETWORK_UPDATE を string "true" に設定してください。詳しくは、ランナーを管理するを参照してください。ランナーでライブ更新が有効になっていない場合、UpdateNetworkConfig は FAILED_PRECONDITION (理由: CWSANDBOX_INVALID_REQUEST) を返します。
HTTPS ホスト名を更新するには、さらに HTTPS ホスト名をサポートするランナーと、httpsHostname グラントを 1 つ以上指定して作成されたサンドボックスが必要です。詳しくは、サポートされる変更と制限を参照してください。
オペレーションと認証
このサービスはhttps://api.cwsandbox.com でホストされています。リクエストには、sandbox_user 権限を持ち、設定が属する組織へのアクセス権がある Bearer token が必要です。サンドボックスにバインドされた設定を更新する場合は、そのサンドボックスへのアクセス権も必要です。
Connect 経由で JSON を使用する場合は、完全なリクエストメッセージを
Content-Type: application/json と Connect-Protocol-Version: 1 ヘッダー付きで、/coreweave.sandbox.v1.NetworkConfigService/[RPC-NAME] に POST で送信します。[RPC-NAME] は表のメソッド名に置き換えてください。これに対して、REST の作成および更新バインディングでは、NetworkConfig リソースをリクエスト本文として受け付けます。updateMask などのリクエストオプションはクエリパラメーターとして指定します。生成されたクライアントについては、Protobuf を参照してください。
NetworkConfigService は、共有サンドボックスネットワークを扱う NetworkService (現在利用不可) とは別のサービスです。
リソースフィールド
次の表のフィールド名は JSON の camelCase で表記しています。Protobuf のフィールドは snake_case を使用します。
Create は省略可能な
requestId を受け入れます。List は pageSize、pageToken、および省略可能なブール値フィルター platformManaged を受け入れます。両方の所有タイプを対象にする場合は、フィルターを省略します。Delete に allowMissing: true を指定すると、ID が存在しない場合でも成功します。
サンドボックスおよびテンプレートのフィールド
SandboxSpec.networkConfigId は作成時には省略可能で、作成後は変更できません (不変) 。ID を指定しない場合、プラットフォームは省略可能な書き込み専用の SandboxSpec.network 入力から設定を作成します。この入力もない場合は、ポリシーのデフォルトに解決される空のルールから設定を作成します。両方のフィールドを同時に送信することはできません。
サンドボックスの Get および List の応答には、バインドされた networkConfigId が含まれ、インラインの network は含まれません。目的のルールは NetworkConfig.spec で確認できます。保存された有効状態のレポートは、サンドボックスの status.effectiveEgress、status.effectiveIngress、status.effectiveDnsEgress で確認できます。
サンドボックステンプレートは、再利用可能なレシピとしてインラインの spec.network を保持します。spec.networkConfigId は保存できません。テンプレートから作成された各サンドボックスには、それぞれ専用のプラットフォームマネージドの設定が割り当てられます。または、テンプレートからの作成リクエストで overrides.networkConfigId を指定し、呼び出し元が作成した未使用の設定をバインドすることもできます。その場合は、同じリクエストで overrides.network を指定しないでください。
更新マスク
Update は次のパスをサポートしています。
JSON では、
updateMask をカンマ区切りの文字列としてエンコードします (例: "spec.egress,spec.denyEgress") 。
ワイルドカード
"*" は、gRPC や protobuf エンコードの Connect など、バイナリ protobuf でのみ機能します。JSON の Connect リクエストや REST の updateMask クエリ値では、ハンドラに到達する前のデコード段階で INVALID_ARGUMENT により失敗します。このデコードエラーには CWSANDBOX_* の理由は含まれません。
マスクを省略した場合、繰り返しリストはクリアできません。外向き通信をクリアするには、spec.egress を明示的に選択してください。対応する拒否フラグが未設定または false のまま外向き通信またはイングレスを空にすると、ポリシーのデフォルトが適用されます。拒否したい場合は、同じ更新内でリストをクリアし、拒否フラグを設定してください。同じ方向で拒否フラグを true にし、かつリストを空にしない指定は無効です。
DNS アクセスを変更するには、マスクに spec.dnsEgress を含め、dnsEgress を DNS_EGRESS_MODE_ALLOW または DNS_EGRESS_MODE_DENY に設定します。ランナーのポリシーで DENY が必須とされている場合、サンドボックスは ALLOW をリクエストできません。DNS_EGRESS_MODE_UNSPECIFIED を指定して spec.dnsEgress を選択した場合や、このパスを選択して値を省略した場合は、ランナーのポリシーのデフォルトに戻ります。完全な置き換えのために 5 つのパスすべてを選択した場合も同様です。ポリシーで指定がない場合のデフォルトは ALLOW です。マスクに spec.dnsEgress を含めなければ、保存済みのモードがそのまま保持されます。
DNS モードが制御するのは UDP/TCP の宛先ポート 53 のトラフィックであり、クエリ名の認可や、許可された他のトランスポート経由の DNS は対象外です。HTTPS ホスト名のグラントには egress[].httpsHostname を使用し、TCP ポート 443 に対する別個の権限として扱われます。プラットフォームが必要とする他のポートのトラフィックは、denyEgress を設定していても引き続き利用できる場合があります。
適用の動作とライフサイクル
バインドされていない設定を作成または更新すると、構文が検証され、目的のルールが保存されます。ランナーのポリシーに対する検証は、サンドボックスが設定をバインドしたときに行われ、ライブ更新時にも再度行われます。ライブ更新では、ゲートウェイが現在キャッシュしているランナーのポリシーが使用されるため、ポリシーへの書き込みがすぐには反映されない場合があります。ポリシーの範囲外にあるルールは、暗黙的に範囲を絞り込まれることなく拒否されます。 バインド済みの設定を更新する場合、CREATING または PREPARING 状態のサンドボックスが RUNNING になるまで、リクエストの期限内で待機します。先に期限を過ぎた場合、リクエストは CWSANDBOX_SANDBOX_NOT_READY で失敗し、変更は保存されません。終了処理中または終了済みのサンドボックスに対する更新は CWSANDBOX_SANDBOX_NOT_RUNNING で失敗します。実行中のサンドボックスの場合、更新はルールを解決し、目的の状態を永続化したうえで適用を行います。ルールのリストは対応するグラントを置き換えるもので、追加されるわけではありません。サービスとその可視性は変更されません。
永続化と適用は別々のステップです。永続化の後に失敗が発生すると、目的のルール、実際のトラフィック権限、サンドボックスの有効状態のレポートが一致しなくなる可能性があります。一時的な適用の失敗が発生した場合、一部の適用変更がすでに有効になっていることがあり、それらは自動的にはロールバックされません。
同じ目的のルールで再試行すると、保存済みのルールがすでに一致している場合でも適用が再実行されます。再試行可能なエラーを解決した後は、現在の設定を読み取り、意図したルールを再適用してください。再試行する前に、etag の不一致をリコンサイルしてください。このトークンが保護するのは目的の状態の書き込みであり、複数の適用システムにまたがるアトミックなトランザクションではありません。
バインド済みの設定の更新結果である spec が、保存済みの目的の状態とすでに一致している場合、etag は確認されずに適用が再実行されます。spec が変更されていない再試行をトークンによって拒否できるとは考えないでください。明示的に空の更新マスクを指定した場合は引き続き no-op となり、適用は再実行されません。
ランナーによる恒久的な CWSANDBOX_INVALID_REQUEST の拒否は、適用の変更が行われる前に発生します。更新によって新しい目的のルールが永続化されていた場合、API は以前の目的の設定のリストアを試みます。このリストアは保証されず、同時に行われたより新しい更新を上書きすることもありません。エラーが発生した後は、設定を再度読み取ってください。リストアが行われると etag が変わります。
プラットフォームによって管理される設定は、対応するサンドボックスの終了後に削除されます。呼び出し元が作成した設定は削除されずに残り、終了していないサンドボックスで使用されなくなった時点で、再バインドまたは削除できます。ルールをクローンするには、spec を新しい設定にコピーしてください。ID を再利用すると、同じリソースが再利用されます。
エラー
サンドボックスの最初の HTTPS ホスト名グラントを作成時ではなく更新で追加すると、
CWSANDBOX_INVALID_REQUEST が返されることがあります。また、一部の古いサンドボックスでは、削除を含むホスト名の変更が拒否されます。このような場合は、必要なホスト名グラントを指定して新しいサンドボックスを作成してください。HTTPS ホスト名グラントを適用するには、ランナーがこれをサポートしている必要があります。