> ## 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를 통해 샌드박스의 이그레스 규칙과 선언된 ingress 규칙을 업데이트합니다.

CoreWeave Sandboxes의 동적 네트워크 정책을 사용하면 실행 중인 샌드박스의 워크로드를 다시 시작하지 않고도 네트워크 액세스를 변경할 수 있습니다. 예를 들어 에이전트가 의존성을 다운로드한 후, 신뢰할 수 없는 코드를 실행하기 전에 아웃바운드 트래픽을 제한하도록 할 수 있습니다.

각 샌드박스는 원하는 네트워크 규칙이 담긴 `NetworkConfig` 하나를 참조합니다. 액세스를 변경하려면 이 리소스를 업데이트하세요. 단, 요청할 수 있는 규칙의 범위는 배치 위치의 네트워크 정책에 따라 제한됩니다. 서버리스 샌드박스에서는 CoreWeave가 이 정책을 관리하고, CoreWeave Kubernetes Service(CKS) 러너에서는 Admin이 이 정책을 설정합니다.

## 시작하기 전에

선택한 러너에서 이 기능을 사용할 수 있다면 동적 네트워크 정책은 서버리스 샌드박스와 CKS 샌드박스를 모두 지원합니다. 서버리스는 CoreWeave에서 관리하는 러너를 사용하므로 별도의 CKS 클러스터나 러너가 필요하지 않습니다.

시작하기 전에 다음 항목이 준비되어 있는지 확인하세요.

* `sandbox_user` 권한이 있는 CoreWeave API 액세스 토큰. [API 액세스 토큰 관리](https://docs.coreweave.com/security/authn-authz/manage-api-access-tokens.md)를 참조하세요.
* 조직에 서비스를 제공하는 API에서 활성화된 `NetworkConfig` 지원. [가용성 및 사전 요구 사항](https://docs.coreweave.com/ko/products/sandboxes/reference/network-configs.md#availability-and-prerequisites)을 참조하세요.
* 샌드박스가 사용하는 러너에서 활성화된 실시간 네트워크 업데이트. 서버리스 러너는 CoreWeave가 관리합니다. CKS 관리형 러너의 경우 `spec.overrides.env.ENABLE_LIVE_NETWORK_UPDATE`를 문자열 `"true"`로 설정하세요. [러너 관리](https://docs.coreweave.com/ko/products/sandboxes/operations/managed-runners.md)를 참조하세요.
* 배치의 네트워크 정책에서 지원 및 허용되는 HTTPS 호스트 이름 권한 부여(이 가이드의 예시에 필요).
* 로컬에 설치된 `curl` 및 `jq`.

예시에서는 서버리스 배치를 사용하며, [Connect](https://docs.coreweave.com/ko/products/sandboxes/reference/protos.md)를 통해 `https://api.cwsandbox.com`으로 JSON 요청을 보냅니다. Python 및 TypeScript 클라이언트에서는 `NetworkConfig` 오퍼레이션을 사용할 수 없습니다.

토큰을 설정하세요. `[API-ACCESS-TOKEN]`을 CoreWeave API 액세스 토큰으로 바꾸세요.

```bash title="Set the API token" theme={"system"}
export TOKEN="[API-ACCESS-TOKEN]"
```

## 네트워크 설정 생성 및 바인딩

Python 패키지 인덱스와 해당 다운로드 호스트로의 HTTPS 연결을 허용하는 호출자 소유 설정을 생성하세요. ID는 조직 내에서 고유한 값으로 선택하세요. 이 예제에서는 `build-egress`를 사용합니다.

```bash title="Create a network configuration" theme={"system"}
curl --fail-with-body -sS \
  'https://api.cwsandbox.com/coreweave.sandbox.v1.NetworkConfigService/CreateNetworkConfig' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  -d '{
    "networkConfig": {
      "networkConfigId": "build-egress",
      "spec": {
        "egress": [
          {"httpsHostname": "pypi.org"},
          {"httpsHostname": "files.pythonhosted.org"}
        ]
      }
    }
  }'
```

응답으로는 ID, 원하는 `spec`, `etag`, `status`가 포함된 `NetworkConfig`가 반환됩니다. 생성 시 규칙 구문의 유효성이 검사됩니다. 설정을 샌드박스에 바인딩하면 플랫폼에서 러너 정책을 확인합니다.

이 설정을 사용하는 서버리스 샌드박스를 생성하세요. 이 예제에서는 CPU 1개와 메모리 1GiB를 할당합니다.

```bash title="Create a sandbox with the configuration" theme={"system"}
curl --fail-with-body -sS \
  'https://api.cwsandbox.com/coreweave.sandbox.v1.SandboxService/CreateSandbox' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  -d '{
    "sandbox": {
      "spec": {
        "containers": [{
          "name": "main",
          "image": "python:3.12-slim",
          "command": "sleep",
          "args": ["3600"],
          "resources": {"cpu": "1", "memory": "1Gi"}
        }],
        "mode": "SANDBOX_MODE_SERVERLESS",
        "networkConfigId": "build-egress",
        "maxLifetimeSeconds": 3600
      }
    }
  }'
```

반환된 `sandboxId`를 저장하세요. 플랫폼은 샌드박스가 `RUNNING` 상태가 되기 전에 초기 규칙을 적용합니다. CKS의 경우 `spec.mode`를 `SANDBOX_MODE_CKS`로 변경하고, 필요하면 `spec.runnerIds`를 선택하세요.

하나의 설정은 한 번에 종료되지 않은 샌드박스 하나에만 바인딩할 수 있습니다. 하나의 생성 요청에 `spec.networkConfigId`와 인라인 `spec.network`를 함께 보내지 마세요.

`networkConfigId`를 생략하면 플랫폼이 샌드박스용 설정을 생성합니다. 이때 인라인 `spec.network` 규칙이 있으면 이를 복사하고, 없으면 정책 기본값이 적용되는 빈 설정을 사용합니다. 부여된 ID는 `GetSandbox.spec.networkConfigId`에서 조회하세요.

## 실행 중인 샌드박스의 규칙 업데이트

규칙을 변경하기 전에 실행 중인 샌드박스 내부에서 `pypi.org` 및 `files.pythonhosted.org`에 대한 새 HTTPS 연결을 테스트하세요. 방법은 [실행 가이드](https://docs.coreweave.com/ko/products/sandboxes/client/guides/execution.md)를 참조하세요. 두 연결이 모두 성공하는지 확인한 후, 업데이트 후에 다시 실행할 수 있도록 프로브 명령어를 저장해 두세요. 연결에 실패한 경우 문제를 모두 해결한 후 계속 진행하세요.

액세스를 제한할 준비가 되면 샌드박스의 이그레스 권한 부여를 지우고, UDP 및 TCP 포트 `53`의 아웃바운드 DNS를 거부하세요. 이 업데이트는 선언된 ingress를 변경하지 않습니다.

최신 상태가 아닌 desired-state 쓰기를 거부하려면 현재 설정을 조회한 후 업데이트할 때 해당 `etag`를 함께 전달하세요.

```bash title="Restrict outbound access" theme={"system"}
config=$(curl --fail-with-body -sS \
  'https://api.cwsandbox.com/coreweave.sandbox.v1.NetworkConfigService/GetNetworkConfig' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  -d '{"networkConfigId":"build-egress"}') &&
etag=$(printf '%s' "$config" | jq -er '.etag') &&
jq -n --arg etag "$etag" '{
  networkConfigId: "build-egress",
  networkConfig: {
    etag: $etag,
    spec: {egress: [], denyEgress: true, dnsEgress: "DNS_EGRESS_MODE_DENY"}
  },
  updateMask: "spec.egress,spec.denyEgress,spec.dnsEgress"
}' | curl --fail-with-body -sS \
  'https://api.cwsandbox.com/coreweave.sandbox.v1.NetworkConfigService/UpdateNetworkConfig' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  --data-binary @-
```

응답으로는 업데이트된 `NetworkConfig`가 반환됩니다. 샌드박스는 동일한 ID와 프로세스 상태를 유지한 채 계속 실행됩니다. 다른 포트를 통한 허용된 저장소 액세스처럼 플랫폼에 필요한 트래픽은 계속 사용 가능할 수 있습니다. `denyEgress`가 네트워크를 완전히 격리하는 것은 아닙니다.

목록을 지울 때는 명시적인 마스크를 사용하세요. `denyEgress`가 설정되지 않았거나 `false`인 상태에서 이그레스 목록을 비우면 정책 기본값으로 복원됩니다. 모든 트래픽을 거부한다는 의미가 아닙니다.

## 결과 확인

`[SANDBOX-ID]`를 샌드박스 생성 시 반환된 ID로 바꾼 후 샌드박스를 확인하세요.

```bash title="Inspect sandbox network status" theme={"system"}
curl --fail-with-body -sS \
  'https://api.cwsandbox.com/coreweave.sandbox.v1.SandboxService/GetSandbox' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  -d '{"sandboxId":"[SANDBOX-ID]"}'
```

샌드박스가 `RUNNING` 상태를 유지하고, 동일한 `spec.networkConfigId`를 참조하며, 업데이트된 `status.effectiveEgress`, `status.effectiveIngress`, `status.effectiveDnsEgress`를 보고하는지 확인하세요. JSON 응답에서는 비어 있는 반복 필드가 생략될 수 있습니다.

업데이트 전에 성공했던 연결 프로브를 다시 실행하세요. 이전에 권한이 부여되었던 두 호스트로의 새 아웃바운드 HTTPS 연결이 모두 실패하는지, 그리고 기존 워크로드가 계속 실행되는지 확인하세요. 프로브 실패를 적용이 완료되었다는 근거로 판단하기 전에, 대상에 접근할 수 없는 경우처럼 무관한 실패 원인이 없는지 먼저 조사하세요. 상태 필드는 마지막으로 성공한 업데이트를 기준으로 저장된 보고 내용일 뿐, 적용 여부를 실시간으로 측정한 값이 아닙니다.

> [!WARNING]
>
> 업데이트 시 적용이 완료되기 전에 원하는 설정이 먼저 저장될 수 있습니다. 일시적인 실패가 발생하면 이전 적용 상태가 복원되지 않은 채 일부 변경 사항만 적용된 상태로 남을 수 있습니다. 제한이 동작한다고 판단하기 전에 현재 설정을 조회하고, 해당 설정의 현재 `etag`로 의도한 규칙을 다시 적용한 다음 트래픽을 확인하세요. 러너가 영구적으로 거부하는 경우 API는 이전에 원했던 설정으로 복원을 시도합니다. [적용 동작 및 라이프사이클](https://docs.coreweave.com/ko/products/sandboxes/reference/network-configs.md#apply-behavior-and-lifecycle)을 참조하세요. `etag`가 일치하지 않으면 설정을 다시 조회한 뒤 동시에 발생한 변경 사항을 조정해야 합니다.

## 설정 재사용 또는 삭제

샌드박스가 종료되면 호출자가 생성한 설정을 다시 사용할 수 있습니다. 정리 작업이 완료되는 동안에는 `status.sandboxId`에 이전 ID가 잠시 남아 있을 수 있습니다. 이 설정을 새 샌드박스에 바인딩하거나 삭제할 수 있습니다.

```bash title="Delete an unused network configuration" theme={"system"}
curl --fail-with-body -sS \
  'https://api.cwsandbox.com/coreweave.sandbox.v1.NetworkConfigService/DeleteNetworkConfig' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  -d '{"networkConfigId":"build-egress","allowMissing":true}'
```

종료 상태가 아닌 샌드박스가 설정을 사용하는 동안에는 삭제할 수 없습니다. 플랫폼에서 생성한 설정은 해당 샌드박스가 종료되면 자동으로 삭제됩니다.

동일한 네트워크 구성을 다른 샌드박스에 적용하려면 설정의 `spec`을 새 설정이나 인라인 생성 입력에 복사하세요. `GetSandbox.spec`을 복사하면 독립된 규칙 집합이 아니라 설정 ID만 복사됩니다.

## 지원되는 변경 사항 및 제한

동적 네트워크 정책에는 다음과 같은 변경 사항 및 제한이 적용됩니다.

* 이그레스 대상 권한 부여, 기존 `CUSTOM` 서비스에 선언된 ingress 소스, `denyEgress`, `denyIngress`, `dnsEgress`를 업데이트할 수 있습니다. 단, 규칙은 러너 정책 범위를 벗어날 수 없습니다.
* 서비스 포트와 공개 범위는 여전히 생성 시점에만 설정할 수 있습니다. 자세한 내용은 [퍼블릭 엔드포인트](https://docs.coreweave.com/ko/products/sandboxes/public-endpoints.md)를 참조하세요.
* HTTPS 호스트 이름 권한 부여는 여전히 TCP 포트 `443`의 HTTPS에만 적용됩니다. 호스트 이름 권한 부여는 `httpsHostname` 권한 부여를 하나 이상 포함하여 생성한 샌드박스에서만 실시간으로 변경할 수 있습니다. 호스트 이름 권한 부여 없이 생성한 샌드박스에 이를 추가하려면 새 샌드박스를 만드세요.
* 일부 이전 샌드박스에서는 호스트 이름 권한 부여를 실시간으로 변경할 수 없으며, 제거도 불가능합니다. 업데이트가 `CWSANDBOX_INVALID_REQUEST`로 거부되면 필요한 권한 부여를 포함하여 새 샌드박스를 만드세요.
* 러너가 HTTPS 호스트 이름 권한 부여를 지원해야 합니다. 러너가 이를 강제 적용할 수 없으면 해당 권한 부여를 추가하거나 변경하는 요청은 `CWSANDBOX_INVALID_REQUEST`를 반환합니다.

리소스 필드, 업데이트 마스크, 오류 처리에 대한 자세한 내용은 [NetworkConfig API 참조](https://docs.coreweave.com/ko/products/sandboxes/reference/network-configs.md)를 참조하세요.