Skip to main content
이 페이지는 퍼블릭 엔드포인트의 작동 방식, 샌드박스 생성 시 선언하는 방법, 그리고 연결하는 방법을 설명합니다. 퍼블릭 엔드포인트는 샌드박스 내부에서 실행되는 서비스에 인터넷에서 클라이언트가 접근할 수 있는 주소를 제공합니다. 샌드박스를 생성할 때 요청하며, 플랫폼은 라우팅, DNS 및 네트워크 액세스를 프로비저닝합니다. 주소는 샌드박스가 실행되는 동안 샌드박스에 속합니다. 엔드포인트는 TLS가 종료되는 위치에 따라 두 가지 종류가 있습니다:
  • HTTPS: 플랫폼은 에지에서 프로비저닝하고 갱신하는 인증서로 TLS를 종료한 다음, 요청을 일반 텍스트 HTTP로 포트에 전달합니다.
  • TLS passthrough: 플랫폼은 Server Name Indication (SNI)를 사용하여 연결을 포트로 라우팅하며, 복호화하지 않습니다. 워크로드는 TLS를 종료하고 자체 인증서를 소유합니다.
워크로드가 개인 키를 직접 보유해야 하는 경우 TLS passthrough를 선택하세요: 상호 TLS, 인증서를 고정하는 클라이언트, 또는 HTTP가 아닌 프로토콜.

인증 선택

섹션에서 CoreWeave Kubernetes Service(CKS)를 지정하지 않는 한, 이 예시는 서버리스 용량에서 실행됩니다. 샌드박스를 소유한 계정의 사용자 인증 정보를 선택하세요. 키 또는 토큰을 획득하는 방법은 사용자 인증 정보 선택 및 가져오기를 참조하세요. 사용하는 언어에 맞는 설정 파일을 이 페이지에서 실행할 스크립트와 같은 위치에 저장하세요. Python 예시는 sandbox_auth.py에서 AUTH를 임포트하고, TypeScript 예시는 sandbox-client.mts에서 client를 임포트합니다. 이 파일들은 사용자 인증 정보를 저장하지 않고 인증 방식만 선택합니다. Python에서는 활성화된 가상 환경을 사용하세요. TypeScript에서는 먼저 npm install @coreweave/cwsandbox@1.0.0로 클라이언트를 설치하세요.
SDK의 wandb 인테그레이션으로 Forge API 키를 사용하세요. [WANDB-API-KEY]를 API 키로 바꾸세요.
sandbox_auth.py
CKS 배치를 사용하려면 CoreWeave 토큰을 선택하고 러너를 활성화한 다음, 샌드박스를 생성할 때 또는 SandboxDefaults에서 placement_mode="cks"를 설정하세요. TypeScript에서는 CoreWeave 토큰을 선택하고 runnerIds 배열을 비어 있지 않게 설정하면 CKS가 선택됩니다. auth=AUTH로 Python 세션을 생성하면 해당 세션이 소유한 샌드박스도 함께 인증됩니다. 샌드박스에 다시 연결하거나, 목록을 조회하거나, 정리할 때도 동일한 사용자 인증 정보를 사용하세요. Python 공유 토큰 예시를 사용하려면 cwsandbox 1.16.0 이상과 HTTPS 공유 토큰을 지원하는 배포가 필요합니다. 이 섹션에서 설정하는 사용자 인증 정보는 샌드박스 생성 및 삭제와 같은 SDK 오퍼레이션을 인증하는 데 사용됩니다. 이는 호출자가 보호된 HTTPS URL에 액세스할 때 사용하는 엔드포인트 공유 토큰과는 별개입니다.

두 종류 비교

두 종류 모두 인터넷에서 접근할 수 있습니다. OPEN을 사용하는 HTTPS와 TLS 패스스루는 플랫폼에서 호출자 인증을 수행하지 않으므로, 필요한 액세스 제어는 워크로드에서 강제 적용해야 합니다. SHARE_TOKEN을 사용하는 HTTPS는 모든 요청에 발급된 토큰이 있어야 합니다. 이 토큰을 가진 사람은 누구나 보호된 엔드포인트에 액세스할 수 있습니다.

Declare an 엔드포인트

샌드박스를 생성할 때 services 목록에 엔드포인트를 선언하세요. 포트는 샌드박스의 수명 동안 고정되며, 이미 실행 중인 샌드박스에 포트를 노출하는 호출은 없습니다. 서비스에 퍼블릭 엔드포인트를 부여하려면 해당 서비스에 visibility=ServiceVisibility.PUBLIC과 endpoint 값을 설정하세요. 일반 서비스에는 endpoint 값이 없습니다. 예를 들어 Service(port=8080, name="web")은 공개 범위와 엔드포인트를 설정하지 않으므로, 외부 노출을 요청하지 않고 컨테이너 내부 포트만 선언합니다. 일반 서비스의 공개 범위는 배포의 서비스 네트워킹을 통해 접근할 수 있는지를 제어할 뿐, 공개 HTTPS URL이나 TLS 패스스루 주소를 요청하지는 않습니다. 토큰을 요구하려면 공유 토큰으로 연결하기에 나온 것처럼 EndpointAuth.SHARE_TOKEN을 사용하세요. 플랫폼 호출자 인증 없이 HTTPS 엔드포인트를 만들려면 kind=EndpointKind.HTTPS와 auth=EndpointAuth.OPEN을 설정하세요:
TLS 패스스루 엔드포인트의 경우 kind=EndpointKind.TLS_PASSTHROUGH로 설정하고 auth는 설정하지 않은 상태로 두세요. run하는 command는 포트 자체에서 TLS를 종료해야 합니다. 플랫폼이 연결을 복호화하지 않고 전달하기 때문입니다:
하나의 샌드박스에서 OPEN 및 SHARE_TOKEN HTTPS 엔드포인트를 포함해 HTTPS 엔드포인트와 TLS 패스스루 엔드포인트를 함께 사용할 수 있습니다. 다음 규칙이 적용됩니다:
  • 포트와 이름은 모든 services 항목에서 고유해야 합니다. 이름 없는 포트에 자동 생성된 이름도 여기에 포함됩니다.
  • endpoint가 있는 항목에는 visibility=PUBLIC이 필요합니다. protocol=TCP로 설정하거나 protocol을 설정하지 않은 채로 두세요. 플랫폼은 UDP 및 SCTP 엔드포인트를 허용하지 않습니다.
  • endpoint가 없는 일반 항목은 공개 범위를 설정하지 않거나 PRIVATE, PUBLIC, CUSTOM 중 하나를 사용할 수 있습니다. 이러한 항목에는 TCP, UDP, SCTP를 선언할 수 있습니다. 프로토콜을 설정하지 않으면 기본값으로 TCP가 사용됩니다. 실제 노출 여부는 배포의 지원 사양과 정책에 따라 달라집니다. 이 필드만으로는 퍼블릭 엔드포인트가 생성되지 않습니다. 기존 CUSTOM 서비스의 허용 소스를 변경하려면 동적 네트워크 정책을 참조하세요.
  • 노출된 일반 서비스와 엔드포인트 항목을 함께 사용하지 마세요. 엔드포인트가 있는 샌드박스에서는 모든 일반 서비스의 공개 범위를 설정하지 않은 채로 두세요. 엔드포인트가 없다면 일반 서비스 전체에 걸쳐 노출용 공개 범위 값을 한 가지만 사용하세요.
  • TLS 패스스루에서는 auth와 request_timeout_seconds를 생략하세요. Python에서는 0 대신 None을 전달하세요. timeout이 설정되어 있으면 0이라도 SDK에서 거부합니다.
  • 샌드박스 하나에 선언할 수 있는 서비스 수는 플랫폼 한도로 제한됩니다. 이 한도는 Operator가 각 배포에 맞게 설정합니다.

공유 토큰으로 연결

HTTPS 엔드포인트에 플랫폼 인증을 적용하려면 auth=EndpointAuth.SHARE_TOKEN을 설정하세요. 샌드박스를 생성한 핸들에서 sandbox.endpoint_share_token을 읽은 다음, 요청할 때마다 as_headers() 결과를 함께 보내세요. 이 도우미는 X-Sandbox-Share-Token 헤더를 설정합니다. 플랫폼은 요청을 HTTP 서비스로 전달하기 전에 토큰을 확인합니다. TypeScript에서는 auth: "share_token"을 설정하고 X-Sandbox-Share-Token 요청 헤더에 sandbox.endpointShareToken을 담아 보내세요. 토큰은 생성 시점에만 반환됩니다. 조회, 목록, Sandbox.from_id()는 토큰을 반환하지 않습니다. 원본 핸들은 wait() 및 get_status()를 호출한 후에도 토큰을 유지합니다. 초기 응답에 토큰이 없으면 sandbox.start().result()가 동일한 생성 핸들에서 복구를 재시도합니다. 복구 후에도 토큰이 반환되지 않으면 샌드박스를 중지하고 새로 생성하세요. 토큰이 노출되지 않도록 주의하세요. as_headers()가 반환하는 딕셔너리에는 사용자 인증 정보가 포함되어 있으므로 이 딕셔너리를 로깅하지 마세요. 다음 Python 예시는 보호된 HTTPS 엔드포인트 뒤에서 5분 동안 실행되는 HTTP 서비스를 시작합니다. URL이 부여될 때까지 기다린 다음, 애플리케이션과 경로가 준비 완료 상태가 될 때까지 인증된 요청을 재시도합니다. 요청이 성공하면 익명 요청이 거부되는지 확인합니다. 예시가 종료되면 컨텍스트 관리자가 샌드박스를 중지합니다.
auth=EndpointAuth.OPEN으로 설정한 동일한 HTTP 서비스에서는 서비스가 준비 완료 상태가 되면 익명 요청이 성공합니다. 공유 토큰은 필요하지 않습니다. 인증 모드를 변경하려면 샌드박스를 새로 만드세요. 하나의 샌드박스에서 두 모드를 함께 사용할 수 있으며, 토큰은 해당 샌드박스의 SHARE_TOKEN 엔드포인트만 보호합니다. 자동 생성된 엔드포인트 레퍼런스는 Python SDK 버전 1.14.2를 기준으로 합니다. 이 버전은 OPEN을 지원하지만, SHARE_TOKEN이 도입되기 전에 출시되었습니다.

부여된 주소 조회

플랫폼이 주소를 부여합니다. 호스트 이름을 선택하거나 자체 도메인을 제공할 수 없습니다. 주소를 구성하는 대신 샌드박스에서 조회하세요. DNS 존은 클러스터마다 다르며 API 계약의 일부가 아니기 때문입니다. TLS 패스스루 주소는 service_addresses에 host:port 형식으로 도착하고, HTTPS URL은 service_urls에 도착합니다. 두 목록은 별도로 유지됩니다. TLS 엔드포인트는 service_urls에 절대 나타나지 않습니다.
TLS 패스스루의 경우 다음과 유사한 출력을 볼 수 있습니다:
광고된 포트는 플랫폼의 TLS 리스너 포트이며, 샌드박스 내부에서 프로세스가 바인딩하는 포트가 아닙니다. 이 예제에서 워크로드는 8443에서 수신 대기하고 클라이언트는 443에 연결합니다. 샌드박스 시작 과정에서 두 종류의 주소는 서로 다른 시점에 확인할 수 있습니다.
  • TLS 패스스루 주소는 샌드박스가 생성될 때 부여되므로, 생성 응답에 포함되며 샌드박스가 생성 중이거나 실행 중인 동안 계속 사용할 수 있습니다.
  • HTTPS URL은 경로에 호스트 이름이 할당되면 사용할 수 있으며, 샌드박스가 생성 중이거나 실행 중인 동안 유지됩니다. URL이 나타나거나 사용자가 설정한 기한이 지날 때까지 Python에서는 get_status()를, TypeScript에서는 inspect()를 반복 호출하세요.
  • 어느 쪽이든 애플리케이션이 서비스 중임을 의미하지는 않습니다. 플랫폼은 프로세스가 포트를 바인딩하기 전에 샌드박스를 실행 중으로 보고하므로, 첫 연결 시 재시도해야 합니다.
플랫폼은 샌드박스가 생성 중이거나 실행 중일 때 엔드포인트 주소를 보고하며, 그 외 상태에서는 모두 지웁니다. serviceEndpoints에 HTTPS 메타데이터가 남아 있더라도 일시 중지되거나 완료된 샌드박스에는 연결 가능한 엔드포인트가 없습니다.

TLS passthrough 엔드포인트에 연결

플랫폼은 연결을 복호화하지 않으므로 클라이언트가 받는 인증서는 워크로드가 제시하는 인증서입니다. 클라이언트에게는 두 가지가 따릅니다:
  • 엔드포인트 호스트를 SNI 서버 이름으로 전송하세요. 플랫폼은 SNI만으로 라우팅하므로 이를 생략하거나 다른 이름을 전송하는 연결은 샌드박스에 도달하지 않습니다.
  • 워크로드의 인증서를 신뢰하세요. 엔드포인트 호스트 이름은 플랫폼이 할당하므로, 직접 발급한 인증서는 해당 호스트 이름으로 발급하지 않는 한 일치하지 않습니다. 클라이언트를 설정하여 자체 인증 기관을 신뢰하거나 인증서를 고정하세요.
다음 클라이언트는 광고된 주소에 연결하면서 엔드포인트 호스트를 SNI로 전송합니다. [ENDPOINT-ADDRESS]를 service_addresses에서 조회한 주소로, [PATH-TO-CA-CERT]를 워크로드의 인증서에 서명한 인증 기관의 경로로 바꾸세요:

엔드포인트 lifetime

엔드포인트는 이를 소유한 샌드박스가 존재하는 한 유지됩니다:
  • 샌드박스에 키가 지정되며, 파드에는 지정되지 않습니다. 기본 파드가 재시작되더라도 주소는 동일하게 유지됩니다.
  • 샌드박스를 삭제하면 엔드포인트가 제거됩니다. 주소는 다른 샌드박스로 이동하지 않으며, 새 샌드박스는 새 주소를 받습니다.
  • 샌드박스 간에 예약된 것은 없습니다. 호스트 이름을 재사용하기 위해 보유할 수 없습니다.

create 실패 문제 해결

요청한 엔드포인트 종류를 fleet의 러너가 지원하지 않으면, 엔드포인트가 조용히 제외된 상태로 샌드박스를 시작하는 대신 create call이 실패합니다.
마지막 수정일 2026년 11월 4일