> ## 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`가 담기며, 종료 상태가 아닌 샌드박스 하나에 바인딩할 수 있습니다. 바인딩된 설정을 업데이트하면 샌드박스를 재시작하지 않고도 해당 샌드박스에 규칙이 적용됩니다. 워크스루는 [실행 중인 샌드박스의 네트워크 액세스 변경](https://docs.coreweave.com/ko/products/sandboxes/dynamic-network-policies.md)을 참조하세요.

## 가용성 및 사전 요구 사항

`NetworkConfigService`를 사용하려면 조직에 서비스를 제공하는 API에서 `NetworkConfig` 지원이 활성화되어 있어야 합니다. 이 지원이 활성화되어 있지 않으면 해당 원격 프로시저 호출(RPC)은 `CWSANDBOX_NOT_IMPLEMENTED` 사유와 함께 `UNIMPLEMENTED`를 반환합니다. 실시간 업데이트를 사용하려면 러너에서 실시간 네트워크 업데이트도 활성화되어 있어야 합니다. 서버리스 샌드박스는 CoreWeave가 이 설정을 관리합니다. CoreWeave Kubernetes Service(CKS) 관리형 러너에서는 `spec.overrides.env.ENABLE_LIVE_NETWORK_UPDATE`를 문자열 `"true"`로 설정하세요. 자세한 내용은 [러너 관리](https://docs.coreweave.com/ko/products/sandboxes/operations/managed-runners.md)를 참조하세요. 러너에서 실시간 업데이트가 활성화되어 있지 않으면 `UpdateNetworkConfig`는 `CWSANDBOX_INVALID_REQUEST` 사유와 함께 `FAILED_PRECONDITION`을 반환합니다.

HTTPS 호스트 이름을 업데이트하려면 HTTPS 호스트 이름을 지원하는 러너와, `httpsHostname` 권한 부여가 하나 이상 포함된 상태로 생성된 샌드박스도 필요합니다. 자세한 내용은 [지원되는 변경 사항 및 제한](https://docs.coreweave.com/ko/products/sandboxes/dynamic-network-policies.md#supported-changes-and-limits)을 참조하세요.

## 작업 및 인증

이 서비스는 `https://api.cwsandbox.com`에서 호스팅됩니다. 요청하려면 `sandbox_user` 권한이 있고 해당 설정이 속한 조직에 액세스할 수 있는 Bearer 토큰이 필요합니다. 바인딩된 업데이트에는 샌드박스에 대한 액세스 권한도 필요합니다.

| 원격 프로시저 호출(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/ko/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` 입력으로 설정을 생성합니다. 이 입력도 없으면 정책 기본값으로 해석되는 빈 규칙으로 설정을 생성합니다. 두 필드를 함께 전송할 수는 없습니다.

샌드박스 조회 및 목록 응답에는 바인딩된 `networkConfigId`가 포함되며 인라인 `network`는 생략됩니다. 원하는 규칙은 `NetworkConfig.spec`에서 조회하고, 저장된 유효 상태 보고서는 샌드박스의 `status.effectiveEgress`, `status.effectiveIngress`, `status.effectiveDnsEgress`에서 조회하세요.

샌드박스 템플릿은 인라인 `spec.network`를 재사용 가능한 레시피로 유지하며, `spec.networkConfigId`는 저장할 수 없습니다. 템플릿에서 생성된 각 샌드박스에는 플랫폼에서 관리하는 고유한 설정이 할당됩니다. 템플릿 기반 생성 요청에서는 그 대신 `overrides.networkConfigId`를 제공하여 호출자가 생성했지만 아직 사용되지 않은 설정을 바인딩할 수 있습니다. 이 경우 같은 요청에 `overrides.network`를 함께 제공하지 마세요.

## 업데이트 마스크

업데이트에서는 다음 경로를 지원합니다.

| Protobuf 경로 | JSON 마스크 경로 | 효과 |
| - | - | - |
| `spec.egress` | `spec.egress` | HTTPS 호스트 이름 권한 부여를 포함해 이그레스 목록 전체를 대체합니다. |
| `spec.deny_egress` | `spec.denyEgress` | 이그레스 거부 플래그를 변경합니다. |
| `spec.ingress` | `spec.ingress` | `CUSTOM` 서비스에 선언된 ingress 목록 전체를 대체합니다. |
| `spec.deny_ingress` | `spec.denyIngress` | ingress 거부 플래그를 변경합니다. |
| `spec.dns_egress` | `spec.dnsEgress` | 아웃바운드 UDP/TCP 포트 `53` 모드를 변경합니다. |

JSON에서는 `updateMask`를 쉼표로 구분된 문자열로 인코딩하세요(예: `"spec.egress,spec.denyEgress"`).

| 마스크 | 동작 |
| - | - |
| 생략 | 값이 채워진 변경 가능 필드를 업데이트합니다. 비어 있지 않은 목록, 명시적으로 지정된 거부 플래그, `UNSPECIFIED`가 아닌 DNS 모드가 암시적 마스크에 포함됩니다. 값이 채워진 변경 가능 필드가 없는 요청은 유효하지 않습니다. |
| 명시적으로 비어 있음 | no-op입니다. 적용을 수행하거나 복구하지 않습니다. Connect JSON에서는 `"updateMask": ""`를 사용하세요. |
| 다섯 경로 모두 | `"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`인 상태에서 이그레스 또는 ingress가 비어 있으면 정책 기본값이 적용됩니다. 기본값 대신 거부하려면 한 번의 업데이트에서 목록을 지우고 거부 플래그를 설정하세요. 같은 방향에서 거부 플래그가 `true`인데 목록이 비어 있지 않으면 유효하지 않습니다.

DNS 액세스를 변경하려면 마스크에 `spec.dnsEgress`를 포함하고 `dnsEgress`를 `DNS_EGRESS_MODE_ALLOW` 또는 `DNS_EGRESS_MODE_DENY`로 설정하세요. 러너 정책에서 `DENY`를 요구하면 샌드박스는 `ALLOW`를 요청할 수 없습니다. `spec.dnsEgress`를 선택하고 값을 `DNS_EGRESS_MODE_UNSPECIFIED`로 지정하거나 값을 생략하면 러너 정책의 기본값으로 복원됩니다. 전체 대체를 위해 다섯 경로를 모두 선택할 때도 마찬가지입니다. 정책이 지정되지 않은 경우 기본값은 `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 호스트 이름 권한 부여를 강제 적용하려면 러너가 이 기능을 지원해야 합니다.