> ## 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. # NetworkConfig API > サンドボックスの動的ネットワークポリシーに関する NetworkConfig のオペレーション、フィールド、更新マスク、ライフサイクル、エラーについて説明します。 `NetworkConfigService` は、CoreWeave Sandboxes の組織スコープのネットワーク設定を管理します。各設定は適用したい `NetworkOptions` を保持し、終了状態ではないサンドボックス 1 つにバインドできます。バインド済みの設定を更新すると、サンドボックスを再起動することなく、そのサンドボックスにルールが適用されます。手順ガイドについては、[実行中のサンドボックスのネットワークアクセスを変更する](https://docs.coreweave.com/ja/products/sandboxes/dynamic-network-policies.md) を参照してください。 ## 可用性と前提条件 `NetworkConfigService` を使用するには、組織にサービスを提供している API で `NetworkConfig` のサポートが有効になっている必要があります。このサポートが有効になっていない場合、そのリモートプロシージャコール (RPC) は `UNIMPLEMENTED` (理由: `CWSANDBOX_NOT_IMPLEMENTED`) を返します。また、ライブ更新を行うには、ランナーでライブネットワーク更新が有効になっている必要があります。サーバーレスのサンドボックスでは、これらの設定は CoreWeave が管理します。CoreWeave Kubernetes Service (CKS) のマネージドランナーでは、`spec.overrides.env.ENABLE_LIVE_NETWORK_UPDATE` を string `"true"` に設定してください。詳しくは、[ランナーを管理する](https://docs.coreweave.com/ja/products/sandboxes/operations/managed-runners.md)を参照してください。ランナーでライブ更新が有効になっていない場合、`UpdateNetworkConfig` は `FAILED_PRECONDITION` (理由: `CWSANDBOX_INVALID_REQUEST`) を返します。 HTTPS ホスト名を更新するには、さらに HTTPS ホスト名をサポートするランナーと、`httpsHostname` グラントを 1 つ以上指定して作成されたサンドボックスが必要です。詳しくは、[サポートされる変更と制限](https://docs.coreweave.com/ja/products/sandboxes/dynamic-network-policies.md#supported-changes-and-limits)を参照してください。 ## オペレーションと認証 このサービスは `https://api.cwsandbox.com` でホストされています。リクエストには、`sandbox_user` 権限を持ち、設定が属する組織へのアクセス権がある Bearer token が必要です。サンドボックスにバインドされた設定を更新する場合は、そのサンドボックスへのアクセス権も必要です。 | リモートプロシージャコール (RPC) | HTTP アノテーション | 結果 | | - | - | - | | `CreateNetworkConfig` | `POST /v1/networkConfigs` | 呼び出し元が所有する設定を作成して返します。 | | `GetNetworkConfig` | `GET /v1/networkConfigs/{networkConfigId}` | 指定した設定の内容とステータスを返します。 | | `ListNetworkConfigs` | `GET /v1/networkConfigs` | `networkConfigs` と、省略可能な `nextPageToken` を返します。 | | `UpdateNetworkConfig` | `PATCH /v1/networkConfigs/{networkConfigId}` | 更新マスクを適用し、設定を返します。 | | `DeleteNetworkConfig` | `DELETE /v1/networkConfigs/{networkConfigId}` | 使用されていない設定を削除し、空の応答を返します。 | Connect 経由で JSON を使用する場合は、完全なリクエストメッセージを `Content-Type: application/json` と `Connect-Protocol-Version: 1` ヘッダー付きで、`/coreweave.sandbox.v1.NetworkConfigService/[RPC-NAME]` に `POST` で送信します。`[RPC-NAME]` は表のメソッド名に置き換えてください。これに対して、REST の作成および更新バインディングでは、`NetworkConfig` リソースをリクエスト本文として受け付けます。`updateMask` などのリクエストオプションはクエリパラメーターとして指定します。生成されたクライアントについては、[Protobuf](https://docs.coreweave.com/ja/products/sandboxes/reference/protos.md) を参照してください。 `NetworkConfigService` は、共有サンドボックスネットワークを扱う `NetworkService` (現在利用不可) とは別のサービスです。 ## リソースフィールド 次の表のフィールド名は JSON の camelCase で表記しています。Protobuf のフィールドは snake\_case を使用します。 | フィールド | 意味 | | - | - | | `networkConfigId` | `^[a-z][a-z0-9-]{2,62}$` に一致する、組織内で一意の不変の ID です。呼び出し元が指定する ID は、予約済みの `nc-` 接頭辞で始めることはできません。 | | `spec` | 目的の `NetworkOptions` (`egress`、`ingress`、`denyEgress`、`denyIngress`、`dnsEgress`) です。 | | `etag` | 目的の状態を書き込む際に使用する、省略可能な同時実行トークンです。古い書き込みを拒否するには、最後に返された値を更新リソースに含めて送信します。変更のない目的のルールを再適用するバインド済みの更新では、トークンはチェックされません。省略すると、最後に永続化された書き込みが優先されます。 | | `status.sandboxId` | 最後にバインドされたサンドボックスです。クリーンアップが完了するまでの短い間、終了状態のサンドボックスを指す場合があります。 | | `status.platformManaged` | プラットフォームがサンドボックス用にこの設定を自動作成したかどうかを示します。 | | `status.createTime`、`status.updateTime` | 出力専用の作成および更新のタイムスタンプです。 | 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 は次のパスをサポートしています。 | Protobuf パス | JSON マスクパス | 効果 | | - | - | - | | `spec.egress` | `spec.egress` | HTTPS ホスト名のグラントを含め、外向き通信のリスト全体を置き換えます。 | | `spec.deny_egress` | `spec.denyEgress` | 外向き通信の拒否フラグを変更します。 | | `spec.ingress` | `spec.ingress` | `CUSTOM` サービス向けに宣言されたイングレスのリスト全体を置き換えます。 | | `spec.deny_ingress` | `spec.denyIngress` | イングレスの拒否フラグを変更します。 | | `spec.dns_egress` | `spec.dnsEgress` | 送信方向の UDP/TCP ポート `53` のモードを変更します。 | JSON では、`updateMask` をカンマ区切りの文字列としてエンコードします (例: `"spec.egress,spec.denyEgress"`) 。 | マスク | 動作 | | - | - | | 省略 | 値が設定されている変更可能なフィールドを更新します。空でないリスト、明示的に指定された拒否フラグ、および `UNSPECIFIED` 以外の DNS モードが暗黙のマスクに含まれます。値が設定された変更可能なフィールドを含まないリクエストは無効です。 | | 明示的に空 | no-op です。適用の実施や修復は行いません。Connect JSON では `"updateMask": ""` を使用します。 | | 5 つのパスすべて | `"spec.egress,spec.denyEgress,spec.ingress,spec.denyIngress,spec.dnsEgress"` を指定すると、変更可能なすべてのフィールドが置き換えられます。省略された値はデフォルトにリセットされます。バイナリ protobuf では `"*"` も同じ意味になります。 | | 明示的なパス | 指定したフィールドのみを置き換えます。その他のフィールドは現在の値を保持します。不明なパスは無効です。 | ワイルドカード `"*"` は、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 を再利用すると、同じリソースが再利用されます。 ## エラー | 理由 | 意味と対処 | | - | - | | `CWSANDBOX_INVALID_REQUEST` | ルール、マスク、作成フィールドの組み合わせが無効であるか、ランナーまたはそのポリシーでサポートされていないルールが指定されています。ライブ更新をサポートしていないランナーは、この理由を `FAILED_PRECONDITION` とともに返します。リクエストを修正するか、ライブ更新が有効なランナーを使用してください。 | | `CWSANDBOX_RESOURCE_EXISTS` | 呼び出し元が指定した ID はすでに存在します。新しい ID を選択するか、既存の設定を読み取ってください。 | | `CWSANDBOX_REQUEST_ID_CONFLICT` | 作成リクエストが、異なる本文で `requestId` を再利用しています。変更したリクエストには新しい `requestId` を使用してください。 | | `CWSANDBOX_NETWORK_CONFIG_NOT_FOUND` | 設定が存在しないか、呼び出し元の組織外にあります。ID と組織を確認してください。 | | `CWSANDBOX_NETWORK_CONFIG_IN_USE` | 終了状態でない別のサンドボックスがこの設定を使用しているか、使用中に削除が試みられました。別の設定を使用するか、終了するまで待ってください。 | | `CWSANDBOX_ETAG_MISMATCH` | 指定されたトークンが古くなっています (`ABORTED`) 。最新の設定を読み取り、変更をリコンサイルしてから再試行してください。 | | `CWSANDBOX_SANDBOX_NOT_READY` | `CREATING` または `PREPARING` のサンドボックスが `RUNNING` になるのを待機中に、リクエストがタイムアウトしました。変更は保存されていません。再試行する前にサンドボックスの状態を確認してください。 | | `CWSANDBOX_SANDBOX_NOT_RUNNING` | サンドボックスが終了処理中または終了状態のため、ライブ更新を受け付けられません。必要なルールを指定して新しいサンドボックスを作成してください。 | | `CWSANDBOX_RUNNER_UNAVAILABLE` | サンドボックスのランナーが一時的に利用できないか、接続されていません。返された再試行ガイダンスに従って再試行してください。 | | `CWSANDBOX_BACKEND_UNAVAILABLE` | バックエンドの操作が失敗しました。有効状態レポートの保存に失敗した場合でも、実際の適用内容はすでに変更されている可能性があります。現在の設定を読み取り、意図したルールを再適用して、トラフィックを検証してください。 | | `CWSANDBOX_COMMAND_TIMEOUT` | ランナーでのルールの適用がタイムアウトしました。目的のルールがすでに保存され、適用内容が部分的に変更されている可能性があります。現在の設定を読み取り、意図したルールを再適用して、トラフィックを検証してください。 | | `CWSANDBOX_DNS_EGRESS_UNAVAILABLE` | 許可範囲を広げる更新に必要な HTTPS ホスト名適用の依存関係が利用できません。返された再試行ガイダンスに従って再試行してください。 | サンドボックスの最初の HTTPS ホスト名グラントを作成時ではなく更新で追加すると、`CWSANDBOX_INVALID_REQUEST` が返されることがあります。また、一部の古いサンドボックスでは、削除を含むホスト名の変更が拒否されます。このような場合は、必要なホスト名グラントを指定して新しいサンドボックスを作成してください。HTTPS ホスト名グラントを適用するには、ランナーがこれをサポートしている必要があります。