> ## 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.

# 러너의 직접 데이터 영역 설정

> 러너 엔드포인트를 노출하여 샌드박스 exec, 로그, 파일 작업이 게이트웨이를 우회하도록 합니다.

직접 데이터 영역 엔드포인트를 사용하면 `cwsandbox` 클라이언트가 exec, 로그, 파일 작업을 러너에 직접 전달할 수 있습니다. 이러한 작업은 CoreWeave Sandboxes 게이트웨이를 거치는 대신 상호 전송 계층 보안(mTLS)을 사용합니다. 라이프사이클 및 관리 Call은 기존과 같이 게이트웨이를 거칩니다.

이 페이지는 CoreWeave Kubernetes Service(CKS) 클러스터에서 관리형 러너를 운영하는 관리자를 대상으로 하며, 다음 내용을 다룹니다.

* 직접 경로가 러너에 도달하는 방식
* 노출 모드를 선택하고 설정하는 방법
* 자체 ingress 컨트롤러를 통해 엔드포인트를 라우팅하는 방법
* 엔드포인트가 준비 완료 상태인지 확인하는 방법

## 러너로의 직접 연결 경로

각 관리형 러너는 자신의 모든 레플리카 앞단에 위치하는 안정적인 데이터 플레인 엔드포인트를 하나씩 제공할 수 있습니다. 플랫폼은 러너의 `dataPlane` 설정에서 엔드포인트 주소를 확인하고, 해당 주소에 대한 서버 인증서를 러너에 발급합니다. CoreWeave Sandboxes 게이트웨이는 이 주소를 샌드박스 범위로 제한된 클라이언트 인증서와 함께 클라이언트에 반환합니다.

```mermaid theme={"system"}
sequenceDiagram
    participant Client as cwsandbox client
    participant API as Sandbox API
    participant EP as Runner endpoint<br/>(your cluster)
    participant Pod as Sandbox pod

    Client->>API: Request a client certificate for a sandbox
    API-->>Client: Certificate + endpoint address
    Client->>EP: mTLS connection (exec, logs, files)
    EP->>Pod: Apply
    Pod-->>EP: Result
    EP-->>Client: Result
```

이 경로의 다음 속성에 따라 이 페이지에서 선택할 설정이 달라집니다.

* **TLS 세션은 러너에서 종료됩니다**: 러너는 클라이언트 인증서로 모든 연결을 인증합니다. 따라서 중간 장치는 TCP(Transmission Control Protocol) 스트림을 변경하지 않고 그대로 전달해야 합니다. 이러한 중간 장치에는 로드 밸런서, ingress 컨트롤러, VPN(가상 사설망) 등이 있습니다. TLS를 종료한 후 다시 암호화하거나 클라이언트 ID를 헤더로 대체하는 프록시를 사용하면 직접 경로가 작동하지 않습니다.
* **서버 인증서는 알려진 주소를 기준으로 발급됩니다**: 플랫폼은 설정한 주소를 기반으로 인증서의 주체 대체 이름(SAN)을 생성합니다. 클라이언트는 이 이름을 기준으로 러너를 검증하므로, 주소는 변경되지 않아야 하며 엔드포인트로 확인(resolve)되어야 합니다.
* **데이터 플레인 Service는 하나의 포트만 노출합니다**: 어떤 노출 모드를 활성화하든 데이터 플레인 리스너인 TCP 포트 `9443`에 대한 Service만 생성됩니다. 맞춤형 ingress를 사용하면 `443` 등 다른 포트를 게시하고 이 Service로 전달할 수 있습니다. 데이터 플레인 Service는 health, 메트릭, 제어 포트를 노출하지 않습니다.

기본 `AUTO` 전송 정책을 사용하는 클라이언트는 직접 연결을 설정할 수 없는 경우 게이트웨이로 폴백할 수 있습니다. 단, 사용자 인증 정보 발급 중 발생한 `PERMISSION_DENIED` 또는 `UNAUTHENTICATED` 오류는 폴백되지 않고 그대로 실패합니다. 직접 인증서에 특정 오퍼레이션에 대한 권한이 없는 경우에는 `AUTO`가 게이트웨이를 사용할 수 있습니다. 다만 폴백이 이루어진다고 해서 이미 러너로 전송된 오퍼레이션을 안전하게 재시도할 수 있다는 의미는 아닙니다.

## 사전 요구 사항

직접 데이터 영역을 설정하기 전에 다음 사전 요구 사항을 완료하세요.

* 관리형 러너를 배포하고 `installStatus`가 `RUNNER_INSTALL_STATUS_READY`인지 확인하세요. 예시의 `RUNNER_ID`는 사용자의 러너 ID로 바꾸세요. 배포 방법은 [러너 배포 및 관리](https://docs.coreweave.com/ko/products/sandboxes/operations/managed-runners.md)를 참조하세요.
* 러너 페이지의 [시작하기 전에](https://docs.coreweave.com/ko/products/sandboxes/operations/managed-runners.md#before-you-begin)에 설명된 대로 CoreWeave Intelligent CLI를 인증하거나, `curl`에서 사용할 CoreWeave API 액세스 토큰을 내보내세요. 이 페이지의 예시에서도 동일한 `$TOKEN` 변수를 사용합니다.
* 러너를 조회하거나 업데이트하려면 `sandbox_admin` 권한이 있는 토큰을 사용하세요.
* 러너를 호스팅하는 CKS 클러스터에 `kubectl`로 액세스할 수 있어야 합니다. 러너 리소스는 `cw-sandbox-system` namespace에 있습니다. 맞춤형 노출 예시를 따르려면 Helm도 설치해야 하며, CustomResourceDefinitions(CRD), `GatewayClass` 등 클러스터 범위 리소스를 관리할 권한이 필요합니다.

## 노출 모드 선택

`spec.data_plane` 필드는 정확히 하나의 노출 모드를 지정합니다. 이 필드를 설정하지 않으면 러너는 해당 출시 채널의 플랫폼 기본값을 상속합니다. 기본값이 활성화되어 있는데 사용하지 않으려면 `disabled`를 명시적으로 설정하세요.

다음 주소에서 `SERVICE_NAME`은 러너 Service 이름으로, `HOSTNAME`은 설정한 호스트 이름으로 바꾸세요.

| 모드 | 플랫폼이 클러스터에 생성하는 리소스 | 공개 주소 | 사용 시점 |
| - | - | - | - |
| `disabled` | 없음 | 없음. 클라이언트는 새 데이터 오퍼레이션에 게이트웨이를 사용해야 합니다. | 클러스터가 인바운드 연결을 받을 수 없거나, 예측 가능한 게이트웨이 전용 보안 태세를 원하는 경우 |
| `cluster_ip` | `ClusterIP` Service | `https://SERVICE_NAME.cw-sandbox-system.svc:9443` | 클라이언트가 클러스터 Service로 라우팅할 수 있고 클러스터 Service DNS 이름을 확인할 수 있는 경우 |
| `load_balancer` | `LoadBalancer` Service | `https://HOSTNAME:9443` | 경로에 다른 ingress 없이 엔드포인트 전용 공개 또는 비공개 주소가 필요한 경우 |
| `custom` | `ClusterIP` Service | 직접 지정한 `advertised_uri` | 자체 ingress 컨트롤러, VPN, 서비스 메시 또는 오버레이 네트워크를 통해 라우팅하는 경우 |

플랫폼은 러너의 내부 식별자를 기반으로 Service 이름을 지정하므로, 이름을 유추하지 말고 클러스터에서 직접 조회하세요. 해당 Service에는 `sandbox.coreweave.com/component=data-plane` 라벨이 지정되어 있습니다:

```bash theme={"system"}
kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
```

변경 시에는 다음 제약 조건이 적용됩니다.

* 비어 있지 않은 `load_balancer.load_balancer_class` 값을 한 번 설정하면, 다른 활성 노출 모드로 전환하는 경우를 포함해 해당 값을 제자리에서 변경하거나 지울 수 없습니다. 먼저 `disabled`로 설정하고 Service가 제거될 때까지 기다린 다음 새 설정을 적용하세요.
* 노출 모드를 변경하면 공개되는 주소가 바뀌고 실행 중인 직접 오퍼레이션이 중단될 수 있습니다. 변경 후에는 연결 상태를 다시 확인하세요.

## LoadBalancer Service로 엔드포인트 노출하기

`load_balancer` 모드는 TLS를 종료하지 않고 TCP 포트 `9443`을 러너로 전달하는 `LoadBalancer` Service를 생성합니다. `scope`로 원하는 접근 범위를 설정하고, `annotations` 또는 `load_balancer_class`로 공급자의 주소 선택 방식을 설정하세요. 클라이언트 네트워크 범위는 CIDR(classless inter-domain routing) 표기법으로 `source_ranges`에 전달합니다. 공급자는 이러한 소스 범위를 지원하고 강제 적용해야 합니다.

`hostname`은 필수입니다. 플랫폼은 이 값을 서버 인증서에 포함하고, 클라이언트에 `https://HOSTNAME:9443` 주소를 알리며, ExternalDNS를 실행하는 클러스터를 위해 Service에 `external-dns.alpha.kubernetes.io/hostname` 어노테이션을 설정합니다. CKS에서는 External Hostname Controller를 통해 이름을 게시하세요. `service.beta.kubernetes.io/external-hostname` 어노테이션을 추가하고, `hostname`을 CKS가 할당하는 완전 수식된 이름으로 설정하면 됩니다. 예를 들어 짧은 어노테이션 값 `runner-a`는 `runner-a.ORG_ID-CLUSTER_NAME.coreweave.app`이 됩니다. [Create a public DNS name](https://docs.coreweave.com/products/networking/ingress-service/create-public-dns-name.md)에서는 DNS 할당 관련 지침만 따르세요. 러너가 자체 TLS 인증서를 제공하므로 이 엔드포인트에는 ingress TLS 종료를 설정하지 마세요.

CKS에서 공개 주소를 사용하려면 `service.beta.kubernetes.io/coreweave-load-balancer-type: public`도 추가하세요. 기본 CKS 주소 설정에서 이 어노테이션을 생략하면 비공개 주소가 부여됩니다. 주소 선택에 대한 자세한 내용은 [Expose a Service](https://docs.coreweave.com/products/networking/ingress-service/expose-service-dns.md)를 참조하세요. `PRIVATE` 범위를 사용하려면 `load_balancer_class` 또는 공급자 어노테이션이 필요합니다. 플랫폼은 공급자가 비공개 주소를 어떻게 선택하는지 추론할 수 없기 때문입니다.

`ORG_ID`와 `CLUSTER_NAME`을 조직 ID와 클러스터 이름으로 바꾸고, `source_ranges`의 `CLIENT_CIDR`은 클라이언트가 연결하는 네트워크의 CIDR로 바꾸세요.

> [tab] CLI
>
> ```yaml title="data-plane.yaml" theme={"system"}
> spec:
>   data_plane:
>     load_balancer:
>       scope: RUNNER_DATA_PLANE_SERVICE_SCOPE_PUBLIC
>       hostname: runner-a.ORG_ID-CLUSTER_NAME.coreweave.app
>       external_traffic_policy: RUNNER_DATA_PLANE_EXTERNAL_TRAFFIC_POLICY_CLUSTER
>       source_ranges:
>         - CLIENT_CIDR
>       annotations:
>         service.beta.kubernetes.io/coreweave-load-balancer-type: public
>         service.beta.kubernetes.io/external-hostname: runner-a
> ```
>
> ```bash theme={"system"}
> cwic sandbox runner edit RUNNER_ID -f data-plane.yaml
> ```

> [tab] curl
>
> ```bash title="공개 LoadBalancer를 통해 러너 엔드포인트 노출하기" theme={"system"}
> curl --fail-with-body -X PATCH \
>   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
>   -H "Authorization: Bearer $TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "spec": {
>       "dataPlane": {
>         "loadBalancer": {
>           "scope": "RUNNER_DATA_PLANE_SERVICE_SCOPE_PUBLIC",
>           "hostname": "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app",
>           "externalTrafficPolicy": "RUNNER_DATA_PLANE_EXTERNAL_TRAFFIC_POLICY_CLUSTER",
>           "sourceRanges": [
>             "CLIENT_CIDR"
>           ],
>           "annotations": {
>             "service.beta.kubernetes.io/coreweave-load-balancer-type": "public",
>             "service.beta.kubernetes.io/external-hostname": "runner-a"
>           }
>         }
>       }
>     }
>   }'
> ```

업데이트가 끝나면 러너가 새 설정으로 롤아웃되고 `cw-sandbox-system` namespace에 Service가 생성됩니다. Service 주소와 DNS를 확인한 다음 클라이언트에서 접속을 확인하세요. 설정 업데이트가 성공했다고 해서 네트워크에 접근할 수 있다는 것이 보장되지는 않습니다.

## 자체 ingress 컨트롤러를 통해 엔드포인트 라우팅하기

클러스터에서 이미 ingress 컨트롤러가 인바운드 트래픽을 종료하고 있다면, 같은 주소 뒤에 두는 엔드포인트에는 `custom` 모드를 사용하세요. 플랫폼이 포트 `9443`에 `ClusterIP` Service를 생성하며, 클라이언트가 접속할 주소는 `advertised_uri`로 직접 지정합니다.

요구 사항은 러너 앞에 두는 다른 경로와 동일합니다.

* 연결의 TLS SNI(server name indication)를 기준으로 매칭되는 경로에 **TLS 패스스루**를 사용하세요. ingress 컨트롤러에서 TLS를 종료하지 마세요.
* `advertised_uri`는 경로, 쿼리, 사용자 인증 정보가 포함되지 않은 절대 `https://` 오리진으로 설정하세요(예: `https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443`). 호스트는 ingress 컨트롤러로 확인되어야 하며, 포트는 컨트롤러가 수신 대기하는 포트여야 합니다.
* 컨트롤러와 호환되는 Gateway API CRD를 설치하세요. CoreWeave Traefik 차트와 Envoy Gateway `v1.9.1` 예시는 모두 `TLSRoute` 버전 `v1`을 지원합니다. 다른 컴포넌트가 소유한 CRD 번들을 교체할 때는 반드시 해당 소유자와 먼저 협의하세요.

두 예시 모두 클러스터의 `.coreweave.app` 도메인에 속한 호스트 이름을 사용합니다. Traefik은 클러스터 와일드카드 레코드를 사용하고, Envoy 예시는 `external-hostname` 어노테이션으로 별도의 레코드를 생성합니다. `ORG_ID`와 `CLUSTER_NAME`을 실제 값으로 바꾸세요.

### ingress 컨트롤러 준비

사용 중인 컨트롤러를 선택하세요. 두 설정 모두 `.coreweave.app` DNS 이름이 할당된 퍼블릭 `LoadBalancer` Service를 통해 러너 호스트 이름용 TLS 패스스루 리스너를 노출합니다.

> [tab] Traefik (CoreWeave 차트)
>
> CoreWeave [Traefik](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md) 차트는 Ingress 라우트와 동일한 파드 및 동일한 `LoadBalancer` Service에서 Gateway API 라우트도 서빙할 수 있습니다. 이 차트의 Service에는 `service.beta.kubernetes.io/coreweave-load-balancer-type: public` 및 `service.beta.kubernetes.io/external-hostname: '*'`가 이미 설정되어 있습니다. 이 와일드카드 설정에 따라, 우선하는 특정 DNS 레코드가 없으면 `*.ORG_ID-CLUSTER_NAME.coreweave.app` 하위의 호스트 이름은 모두 Traefik으로 해석됩니다. 러너 호스트 이름을 사용하기 전에 해당 호스트 이름이 Traefik의 주소로 해석되는지 확인하세요. 기존 레코드가 다른 곳을 가리키고 있다면 사용하지 않는 호스트 이름을 선택하거나 해당 레코드를 업데이트하세요. 차트의 사전 요구 사항과 CRD 소유권 관련 지침은 [Gateway API](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md#gateway-api)를 참조하세요.
>
> 1. [Gateway API CRD 설치](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md#install-the-gateway-api-crds)의 안내에 따라 차트에서 지원하는 standard 채널 번들을 설치하세요. 호환되는 번들이 이미 설치되어 있으면 그대로 사용하면 됩니다.
>
> 2. Gateway API 공급자를 활성화하고 `websecure` 진입점에 TLS 패스스루 리스너를 추가하세요. 리스너의 `port`는 `LoadBalancer`가 게시하는 포트(`443`)가 아니라 Traefik의 컨테이너 포트(`8443`)입니다.
>
>    ```yaml title="traefik-values.yaml" theme={"system"}
>    traefik:
>      providers:
>        kubernetesGateway:
>          enabled: true
>      gateway:
>        enabled: true
>        listeners:
>          web:
>            port: 8000
>            protocol: HTTP
>          sandbox-data-plane:
>            port: 8443
>            protocol: TLS
>            hostname: "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
>            mode: Passthrough
>            namespacePolicy:
>              from: All
>    ```
>
>    ```bash theme={"system"}
>    helm repo add coreweave https://charts.core-services.ingress.coreweave.com
>    helm upgrade --install traefik coreweave/traefik \
>      --namespace traefik --create-namespace \
>      -f traefik-values.yaml
>    ```
>
>    이 차트로 Traefik을 이미 설치했다면 위 값을 기존 값 파일에 병합한 후 릴리스를 업그레이드하세요.
>
> 이렇게 생성된 Gateway는 `traefik` namespace에 `traefik-gateway`라는 이름으로 만들어집니다. 다음 라우트에서 `GATEWAY_NAME` 및 `GATEWAY_NAMESPACE`에 이 값을 사용하세요.

> [tab] Envoy Gateway
>
> [Envoy Gateway](https://gateway.envoyproxy.io/)는 Gateway API를 기본적으로 지원합니다. 여기서 사용하는 `v1.9.1` Helm 차트에는 `TLSRoute`를 `v1`으로 제공하는 Gateway API CRD가 포함되어 있습니다. Envoy Gateway는 기본적으로 각 `Gateway`마다 `LoadBalancer` Service를 생성합니다. CoreWeave 어노테이션을 사용하면 주소가 공개되고 DNS 이름이 할당됩니다. 이 어노테이션을 `Gateway`가 참조하는 `EnvoyProxy` 리소스에 추가하세요.
>
> 1. Envoy Gateway를 설치합니다.
>
>    ```bash theme={"system"}
>    helm upgrade --install eg oci://docker.io/envoyproxy/gateway-helm --version v1.9.1 \
>      --namespace envoy-gateway-system --create-namespace
>    ```
>
>    다른 컴포넌트가 Gateway API CRD를 관리하는 경우, 해당 번들이 Envoy Gateway `v1.9.1`과 호환되며 여기서 사용하는 라우트 버전을 제공하는지 확인하세요. `--set crds.enabled=false`를 추가하기 전에 Envoy Gateway CRD를 별도로 설치해야 합니다. 이 플래그를 사용하면 두 CRD 세트의 설치를 모두 건너뜁니다. [차트의 기존 CRD 설치 절차](https://github.com/envoyproxy/gateway/tree/v1.9.1/charts/gateway-helm#skip-install-crds)를 따르세요.
>
> 2. `GatewayClass`, CoreWeave Service 어노테이션을 포함하는 `EnvoyProxy`, 그리고 포트 `443`에 TLS 패스스루 리스너가 있는 `Gateway`를 생성합니다. `external-hostname`에 짧은 값 `runner-a`를 지정하면 `runner-a.ORG_ID-CLUSTER_NAME.coreweave.app`이 할당되며, 이 값은 리스너 호스트 이름과 일치해야 합니다.
>
>    ```yaml title="envoy-gateway.yaml" theme={"system"}
>    apiVersion: gateway.networking.k8s.io/v1
>    kind: GatewayClass
>    metadata:
>      name: envoy
>    spec:
>      controllerName: gateway.envoyproxy.io/gatewayclass-controller
>    ---
>    apiVersion: gateway.envoyproxy.io/v1alpha1
>    kind: EnvoyProxy
>    metadata:
>      name: sandbox-data-plane
>      namespace: envoy-gateway-system
>    spec:
>      provider:
>        type: Kubernetes
>        kubernetes:
>          envoyService:
>            annotations:
>              service.beta.kubernetes.io/coreweave-load-balancer-type: public
>              service.beta.kubernetes.io/external-hostname: runner-a
>    ---
>    apiVersion: gateway.networking.k8s.io/v1
>    kind: Gateway
>    metadata:
>      name: sandbox-data-plane
>      namespace: envoy-gateway-system
>    spec:
>      gatewayClassName: envoy
>      infrastructure:
>        parametersRef:
>          group: gateway.envoyproxy.io
>          kind: EnvoyProxy
>          name: sandbox-data-plane
>      listeners:
>        - name: sandbox-data-plane
>          protocol: TLS
>          port: 443
>          hostname: "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
>          tls:
>            mode: Passthrough
>          allowedRoutes:
>            namespaces:
>              from: All
>    ```
>
>    ```bash theme={"system"}
>    kubectl apply -f envoy-gateway.yaml
>    ```
>
> Gateway는 `envoy-gateway-system` namespace에 `sandbox-data-plane`이라는 이름으로 생성됩니다. 다음 라우트에서 `GATEWAY_NAME`과 `GATEWAY_NAMESPACE`에 이 값을 사용하세요.

### 러너가 ingress 주소를 가리키도록 설정

클라이언트는 `custom.advertised_uri` 값으로 접속하므로, 이 값에는 `ClusterIP` Service가 아니라 ingress 호스트 이름과 포트를 지정해야 합니다.

1. `custom.advertised_uri`를 ingress 컨트롤러가 서빙하는 주소로 설정하세요. 이 설정을 적용하면 다음 단계에서 경로의 대상이 되는 데이터 플레인 Service도 함께 생성됩니다.

   > [tab] CLI
   >
   > ```yaml title="data-plane.yaml" theme={"system"}
   > spec:
   >   data_plane:
   >     custom:
   >       advertised_uri: https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443
   > ```
   >
   > ```bash theme={"system"}
   > cwic sandbox runner edit RUNNER_ID -f data-plane.yaml
   > ```

   > [tab] curl
   >
   > ```bash title="ingress 컨트롤러를 통해 러너 엔드포인트 공개" theme={"system"}
   > curl --fail-with-body -X PATCH \
   >   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
   >   -H "Authorization: Bearer $TOKEN" \
   >   -H "Content-Type: application/json" \
   >   -d '{
   >     "spec": {
   >       "dataPlane": {
   >         "custom": {
   >           "advertisedUri": "https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443"
   >         }
   >       }
   >     }
   >   }'
   > ```

2. 러너의 단계적 배포가 완료될 때까지 기다리세요.

3. 러너가 생성한 Service의 이름을 조회하세요.

   ```bash theme={"system"}
   kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
   ```

### 러너 Service에 경로 바인딩하기

러너의 namespace에 `TLSRoute`를 생성하여 패스스루 리스너를 데이터 플레인 Service에 바인딩합니다.

1. `GATEWAY_NAME`과 `GATEWAY_NAMESPACE`는 앞서 준비한 컨트롤러의 값으로, `SERVICE_NAME`은 이전 단계에서 확인한 Service 이름으로 바꾸세요.

   ```yaml title="runner-tlsroute.yaml" theme={"system"}
   apiVersion: gateway.networking.k8s.io/v1
   kind: TLSRoute
   metadata:
     name: runner-data-plane
     namespace: cw-sandbox-system
   spec:
     parentRefs:
       - name: GATEWAY_NAME
         namespace: GATEWAY_NAMESPACE
         sectionName: sandbox-data-plane
     hostnames:
       - "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
     rules:
       - backendRefs:
           - name: SERVICE_NAME
             port: 9443
   ```

   ```bash theme={"system"}
   kubectl apply -f runner-tlsroute.yaml
   kubectl get tlsroute -n cw-sandbox-system runner-data-plane -o yaml
   ```

2. `status.parents[].conditions`에 `Accepted: True`와 `ResolvedRefs: True`가 있는지 확인하세요.

3. 엔드포인트를 사용하는 네트워크의 [클라이언트에서 확인](#verify-from-a-client)하세요.

## 엔드포인트 상태 확인

설정을 변경한 후에는 항상 러너를 점검하세요.

1. `installStatus`와 `connectionStatus`를 확인하고, `activeRevision`이 `targetRevision`에 도달했는지 확인하세요.

   > [tab] CLI
   >
   > ```bash theme={"system"}
   > cwic sandbox runner describe RUNNER_ID
   > ```

   > [tab] curl
   >
   > ```bash title="러너 설정 및 상태 조회" theme={"system"}
   > curl -H "Authorization: Bearer $TOKEN" \
   >   https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID
   > ```

2. 데이터 플레인 Service를 확인하세요.

   ```bash theme={"system"}
   kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
   ```

   `load_balancer`의 경우 Service에 주소가 할당되었는지, 그리고 설정한 호스트 이름이 해당 주소로 해석되는지 확인하세요. `custom`의 경우 ingress 컨트롤러의 주소와 `TLSRoute` 상태 조건을 확인하세요.

이 점검을 통과하더라도 클라이언트가 mTLS를 완료할 수 있다고 보장할 수는 없습니다. 이어서 클라이언트 점검을 실행하세요.

## 클라이언트에서 확인

관리 명령어에 `cwic auth login`을 사용했더라도 Python 클라이언트에는 별도의 토큰 환경 변수가 필요합니다. 다음 명령어에서 `API_ACCESS_TOKEN`을 CoreWeave API 액세스 토큰 시크릿으로 바꾸세요.

1. [Python 환경 준비](https://docs.coreweave.com/ko/products/sandboxes/client.md#prepare-your-python-environment)의 설명에 따라 활성화된 Python 가상 환경에 클라이언트를 설치하세요.

   ```bash theme={"system"}
   uv pip install 'cwsandbox>=1.14.2'
   export CWSANDBOX_API_KEY="API_ACCESS_TOKEN"
   ```

2. 클라이언트의 전송 정책을 `DIRECT`로 설정하고, 설정된 CKS 러너에서 오퍼레이션을 실행하세요. 이 모드에서는 게이트웨이로 폴백하지 않으므로, 호출이 성공하면 해당 네트워크에서 직접 경로가 정상적으로 작동하는 것입니다.

   ```python theme={"system"}
   from cwsandbox import AuthStrategy, DataPlaneMode, Sandbox

   with Sandbox.run(
       auth=AuthStrategy.COREWEAVE_API_KEY,
       placement_mode="cks",
       runner_ids=["RUNNER_ID"],
       data_plane_mode=DataPlaneMode.DIRECT,
   ) as sandbox:
       print(sandbox.exec(["echo", "direct"]).result().stdout)
   ```

호출 시 오류가 발생하는데 `DataPlaneMode.GATEWAY`에서는 같은 호출이 성공한다면 [문제 해결](#troubleshooting)을 참조하세요. 전체 클라이언트 옵션은 [직접 샌드박스 연결](https://docs.coreweave.com/ko/products/sandboxes/client/guides/direct-connections.md)을 참조하세요.

## 엔드포인트 비활성화

`disabled`를 설정하면 플랫폼이 생성한 Service가 제거됩니다. `AUTO`로 설정된 새 오퍼레이션은 직접 연결을 설정할 수 없는 경우 게이트웨이를 사용할 수 있습니다. `DIRECT`로 고정된 오퍼레이션은 직접 연결을 설정할 수 없으면 실패합니다. 진행 중인 기존 직접 오퍼레이션은 중단될 수 있습니다.

> [tab] CLI
>
> ```bash theme={"system"}
> echo 'spec: {data_plane: {disabled: {}}}' \
>   | cwic sandbox runner edit RUNNER_ID -f -
> ```

> [tab] curl
>
> ```bash title="직접 데이터 영역 비활성화" theme={"system"}
> curl --fail-with-body -X PATCH \
>   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
>   -H "Authorization: Bearer $TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "spec": {
>       "dataPlane": {
>         "disabled": {}
>       }
>     }
>   }'
> ```

## 문제 해결

| 증상 | 예상 원인 | 해결 방법 |
| - | - | - |
| `load_balancer.hostname must be a stable DNS name` 오류와 함께 업데이트가 거부됨 | `hostname`이 비어 있거나 유효한 DNS 이름이 아닙니다. | 엔드포인트로 해석되는 완전 수식된 이름을 제공하세요. |
| `private scope requires a load_balancer_class or provider annotation` 오류와 함께 업데이트가 거부됨 | `PRIVATE` 범위로 설정되어 있지만 비공개 주소를 선택할 방법이 지정되지 않았습니다. | 공급자의 클래스 또는 어노테이션을 추가하세요. 기본 CKS 주소 설정을 사용하는 경우 `coreweave-load-balancer-type`을 생략하면 비공개 주소가 할당되며, 그 밖에 필요한 어노테이션은 함께 전달하세요. |
| `advertised_uri must be an absolute https origin` 오류와 함께 업데이트가 거부됨 | URI(Uniform Resource Identifier)에 경로, 쿼리, 사용자 인증 정보 또는 `https`가 아닌 스킴이 포함되어 있습니다. | `https://HOSTNAME:PORT` 형식을 사용하세요. |
| `load_balancer_class cannot change in place` 오류와 함께 업데이트가 거부됨 | Kubernetes에서는 해당 Service 필드를 변경할 수 없습니다. | `disabled`로 설정하고 데이터 플레인 Service가 제거될 때까지 기다린 다음 새 설정을 적용하세요. |
| `load_balancer` 모드에서 엔드포인트에 연결할 수 없음 | Service에 아직 주소가 할당되지 않았거나 `hostname`의 DNS가 해당 주소로 해석되지 않습니다. | `kubectl get svc -n cw-sandbox-system`으로 대기 중인 `LoadBalancer`가 있는지 확인하고 DNS 레코드를 점검하세요. CKS에서는 `external-hostname` 어노테이션으로 설정한 이름이 생성되었는지 확인하세요. |
| `TLSRoute`가 `ResolvedRefs: False`를 보고함 | 경로가 아직 존재하지 않는 Service를 참조하고 있습니다. | 먼저 러너 업데이트를 적용한 다음 Service 이름을 `backendRefs`에 복사하세요. |
| `GATEWAY`는 작동하지만 `DIRECT`는 실패함 | 클라이언트 네트워크에서 알린 주소에 연결할 수 없거나 중간 장치에서 TLS를 종료합니다. | 클라이언트 네트워크에서 알린 호스트와 포트로 TCP 연결이 가능한지 테스트하세요. `custom` 모드에서는 경로가 패스스루로 설정되어 있고 SNI 호스트 이름과 일치하는지 확인하세요. |
| 인증서 이름 불일치로 TLS 핸드셰이크가 실패함 | 클라이언트가 서버 인증서에 포함되지 않은 이름으로 연결하고 있습니다. | `advertised_uri` 또는 `hostname`을 클라이언트가 사용하는 이름과 일치시킨 다음, 러너가 새 인증서를 사용할 때까지 기다리세요. |

## 참조

게이트웨이와 러너가 시스템에서 어디에 위치하는지 전체적으로 살펴보려면 [샌드박스 아키텍처](https://docs.coreweave.com/ko/products/sandboxes/architecture.md)를 참조하세요.
