cwsandbox 클라이언트가 exec, 로그, 파일 작업을 러너에 직접 전달할 수 있습니다. 이러한 작업은 CoreWeave Sandboxes 게이트웨이를 거치는 대신 상호 전송 계층 보안(mTLS)을 사용합니다. 라이프사이클 및 관리 Call은 기존과 같이 게이트웨이를 거칩니다.
이 페이지는 CoreWeave Kubernetes Service(CKS) 클러스터에서 관리형 러너를 운영하는 관리자를 대상으로 하며, 다음 내용을 다룹니다.
- 직접 경로가 러너에 도달하는 방식
- 노출 모드를 선택하고 설정하는 방법
- 자체 ingress 컨트롤러를 통해 엔드포인트를 라우팅하는 방법
- 엔드포인트가 준비 완료 상태인지 확인하는 방법
러너로의 직접 연결 경로
각 관리형 러너는 자신의 모든 레플리카 앞단에 위치하는 안정적인 데이터 플레인 엔드포인트를 하나씩 제공할 수 있습니다. 플랫폼은 러너의dataPlane 설정에서 엔드포인트 주소를 확인하고, 해당 주소에 대한 서버 인증서를 러너에 발급합니다. CoreWeave Sandboxes 게이트웨이는 이 주소를 샌드박스 범위로 제한된 클라이언트 인증서와 함께 클라이언트에 반환합니다.
이 경로의 다음 속성에 따라 이 페이지에서 선택할 설정이 달라집니다.
- 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로 바꾸세요. 배포 방법은 러너 배포 및 관리를 참조하세요. - 러너 페이지의 시작하기 전에에 설명된 대로 CoreWeave Intelligent CLI를 인증하거나,
curl에서 사용할 CoreWeave API 액세스 토큰을 내보내세요. 이 페이지의 예시에서도 동일한$TOKEN변수를 사용합니다. - 러너를 조회하거나 업데이트하려면
sandbox_admin권한이 있는 토큰을 사용하세요. - 러너를 호스팅하는 CKS 클러스터에
kubectl로 액세스할 수 있어야 합니다. 러너 리소스는cw-sandbox-systemnamespace에 있습니다. 맞춤형 노출 예시를 따르려면 Helm도 설치해야 하며, CustomResourceDefinitions(CRD),GatewayClass등 클러스터 범위 리소스를 관리할 권한이 필요합니다.
노출 모드 선택
spec.data_plane 필드는 정확히 하나의 노출 모드를 지정합니다. 이 필드를 설정하지 않으면 러너는 해당 출시 채널의 플랫폼 기본값을 상속합니다. 기본값이 활성화되어 있는데 사용하지 않으려면 disabled를 명시적으로 설정하세요.
다음 주소에서 SERVICE_NAME은 러너 Service 이름으로, HOSTNAME은 설정한 호스트 이름으로 바꾸세요.
플랫폼은 러너의 내부 식별자를 기반으로 Service 이름을 지정하므로, 이름을 유추하지 말고 클러스터에서 직접 조회하세요. 해당 Service에는
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에서는 DNS 할당 관련 지침만 따르세요. 러너가 자체 TLS 인증서를 제공하므로 이 엔드포인트에는 ingress TLS 종료를 설정하지 마세요.
CKS에서 공개 주소를 사용하려면 service.beta.kubernetes.io/coreweave-load-balancer-type: public도 추가하세요. 기본 CKS 주소 설정에서 이 어노테이션을 생략하면 비공개 주소가 부여됩니다. 주소 선택에 대한 자세한 내용은 Expose a Service를 참조하세요. PRIVATE 범위를 사용하려면 load_balancer_class 또는 공급자 어노테이션이 필요합니다. 플랫폼은 공급자가 비공개 주소를 어떻게 선택하는지 추론할 수 없기 때문입니다.
ORG_ID와 CLUSTER_NAME을 조직 ID와 클러스터 이름으로 바꾸고, source_ranges의 CLIENT_CIDR은 클라이언트가 연결하는 네트워크의 CIDR로 바꾸세요.
- CLI
- curl
data-plane.yaml
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 패스스루 리스너를 노출합니다.
- Traefik (CoreWeave 차트)
- Envoy Gateway
CoreWeave Traefik 차트는 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를 참조하세요.- Gateway API CRD 설치의 안내에 따라 차트에서 지원하는 standard 채널 번들을 설치하세요. 호환되는 번들이 이미 설치되어 있으면 그대로 사용하면 됩니다.
-
Gateway API 공급자를 활성화하고
websecure진입점에 TLS 패스스루 리스너를 추가하세요. 리스너의port는LoadBalancer가 게시하는 포트(443)가 아니라 Traefik의 컨테이너 포트(8443)입니다.traefik-values.yaml이 차트로 Traefik을 이미 설치했다면 위 값을 기존 값 파일에 병합한 후 릴리스를 업그레이드하세요.
traefik namespace에 traefik-gateway라는 이름으로 만들어집니다. 다음 라우트에서 GATEWAY_NAME 및 GATEWAY_NAMESPACE에 이 값을 사용하세요.러너가 ingress 주소를 가리키도록 설정
클라이언트는custom.advertised_uri 값으로 접속하므로, 이 값에는 ClusterIP Service가 아니라 ingress 호스트 이름과 포트를 지정해야 합니다.
-
custom.advertised_uri를 ingress 컨트롤러가 서빙하는 주소로 설정하세요. 이 설정을 적용하면 다음 단계에서 경로의 대상이 되는 데이터 플레인 Service도 함께 생성됩니다.- CLI
- curl
data-plane.yaml - 러너의 단계적 배포가 완료될 때까지 기다리세요.
-
러너가 생성한 Service의 이름을 조회하세요.
러너 Service에 경로 바인딩하기
러너의 namespace에TLSRoute를 생성하여 패스스루 리스너를 데이터 플레인 Service에 바인딩합니다.
-
GATEWAY_NAME과GATEWAY_NAMESPACE는 앞서 준비한 컨트롤러의 값으로,SERVICE_NAME은 이전 단계에서 확인한 Service 이름으로 바꾸세요.runner-tlsroute.yaml -
status.parents[].conditions에Accepted: True와ResolvedRefs: True가 있는지 확인하세요. - 엔드포인트를 사용하는 네트워크의 클라이언트에서 확인하세요.
엔드포인트 상태 확인
설정을 변경한 후에는 항상 러너를 점검하세요.-
installStatus와connectionStatus를 확인하고,activeRevision이targetRevision에 도달했는지 확인하세요.- CLI
- curl
-
데이터 플레인 Service를 확인하세요.
load_balancer의 경우 Service에 주소가 할당되었는지, 그리고 설정한 호스트 이름이 해당 주소로 해석되는지 확인하세요.custom의 경우 ingress 컨트롤러의 주소와TLSRoute상태 조건을 확인하세요.
클라이언트에서 확인
관리 명령어에cwic auth login을 사용했더라도 Python 클라이언트에는 별도의 토큰 환경 변수가 필요합니다. 다음 명령어에서 API_ACCESS_TOKEN을 CoreWeave API 액세스 토큰 시크릿으로 바꾸세요.
-
Python 환경 준비의 설명에 따라 활성화된 Python 가상 환경에 클라이언트를 설치하세요.
-
클라이언트의 전송 정책을
DIRECT로 설정하고, 설정된 CKS 러너에서 오퍼레이션을 실행하세요. 이 모드에서는 게이트웨이로 폴백하지 않으므로, 호출이 성공하면 해당 네트워크에서 직접 경로가 정상적으로 작동하는 것입니다.
DataPlaneMode.GATEWAY에서는 같은 호출이 성공한다면 문제 해결을 참조하세요. 전체 클라이언트 옵션은 직접 샌드박스 연결을 참조하세요.
엔드포인트 비활성화
disabled를 설정하면 플랫폼이 생성한 Service가 제거됩니다. AUTO로 설정된 새 오퍼레이션은 직접 연결을 설정할 수 없는 경우 게이트웨이를 사용할 수 있습니다. DIRECT로 고정된 오퍼레이션은 직접 연결을 설정할 수 없으면 실패합니다. 진행 중인 기존 직접 오퍼레이션은 중단될 수 있습니다.
- CLI
- curl