NetworkConfigService는 CoreWeave Sandboxes의 조직 범위 네트워크 설정을 관리합니다. 각 설정에는 적용하려는 NetworkOptions가 담기며, 종료 상태가 아닌 샌드박스 하나에 바인딩할 수 있습니다. 바인딩된 설정을 업데이트하면 샌드박스를 재시작하지 않고도 해당 샌드박스에 규칙이 적용됩니다. 워크스루는 실행 중인 샌드박스의 네트워크 액세스 변경을 참조하세요.
가용성 및 사전 요구 사항
NetworkConfigService를 사용하려면 조직에 서비스를 제공하는 API에서 NetworkConfig 지원이 활성화되어 있어야 합니다. 이 지원이 활성화되어 있지 않으면 해당 원격 프로시저 호출(RPC)은 CWSANDBOX_NOT_IMPLEMENTED 사유와 함께 UNIMPLEMENTED를 반환합니다. 실시간 업데이트를 사용하려면 러너에서 실시간 네트워크 업데이트도 활성화되어 있어야 합니다. 서버리스 샌드박스는 CoreWeave가 이 설정을 관리합니다. CoreWeave Kubernetes Service(CKS) 관리형 러너에서는 spec.overrides.env.ENABLE_LIVE_NETWORK_UPDATE를 문자열 "true"로 설정하세요. 자세한 내용은 러너 관리를 참조하세요. 러너에서 실시간 업데이트가 활성화되어 있지 않으면 UpdateNetworkConfig는 CWSANDBOX_INVALID_REQUEST 사유와 함께 FAILED_PRECONDITION을 반환합니다.
HTTPS 호스트 이름을 업데이트하려면 HTTPS 호스트 이름을 지원하는 러너와, httpsHostname 권한 부여가 하나 이상 포함된 상태로 생성된 샌드박스도 필요합니다. 자세한 내용은 지원되는 변경 사항 및 제한을 참조하세요.
작업 및 인증
이 서비스는https://api.cwsandbox.com에서 호스팅됩니다. 요청하려면 sandbox_user 권한이 있고 해당 설정이 속한 조직에 액세스할 수 있는 Bearer 토큰이 필요합니다. 바인딩된 업데이트에는 샌드박스에 대한 액세스 권한도 필요합니다.
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 입력으로 설정을 생성합니다. 이 입력도 없으면 정책 기본값으로 해석되는 빈 규칙으로 설정을 생성합니다. 두 필드를 함께 전송할 수는 없습니다.
샌드박스 조회 및 목록 응답에는 바인딩된 networkConfigId가 포함되며 인라인 network는 생략됩니다. 원하는 규칙은 NetworkConfig.spec에서 조회하고, 저장된 유효 상태 보고서는 샌드박스의 status.effectiveEgress, status.effectiveIngress, status.effectiveDnsEgress에서 조회하세요.
샌드박스 템플릿은 인라인 spec.network를 재사용 가능한 레시피로 유지하며, spec.networkConfigId는 저장할 수 없습니다. 템플릿에서 생성된 각 샌드박스에는 플랫폼에서 관리하는 고유한 설정이 할당됩니다. 템플릿 기반 생성 요청에서는 그 대신 overrides.networkConfigId를 제공하여 호출자가 생성했지만 아직 사용되지 않은 설정을 바인딩할 수 있습니다. 이 경우 같은 요청에 overrides.network를 함께 제공하지 마세요.
업데이트 마스크
업데이트에서는 다음 경로를 지원합니다.
JSON에서는
updateMask를 쉼표로 구분된 문자열로 인코딩하세요(예: "spec.egress,spec.denyEgress").
와일드카드
"*"는 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를 재사용하면 동일한 리소스를 재사용하게 됩니다.
오류
샌드박스의 첫 HTTPS 호스트 이름 권한 부여를 생성 시점이 아닌 업데이트로 추가하면
CWSANDBOX_INVALID_REQUEST가 반환될 수 있습니다. 또한 일부 이전 샌드박스는 제거를 포함한 모든 호스트 이름 변경을 거부합니다. 이 경우 필요한 호스트 이름 권한 부여를 포함하여 새 샌드박스를 생성하세요. HTTPS 호스트 이름 권한 부여를 강제 적용하려면 러너가 이 기능을 지원해야 합니다.