cwsandbox Python SDK를 사용하여 샌드박스를 시작하고 관리하는 개발자를 위한 내용입니다. 데이터 오퍼레이션에 대한 전송 정책 선택 방법, SDK가 직접 연결을 설정하는 방식, 그리고 오퍼레이션이 어떤 전송 방식을 사용했는지 확인하는 방법을 설명합니다.
인증 선택
섹션에서 CKS를 지정하지 않는 한, 이 예시는 서버리스 용량에서 실행됩니다. 샌드박스를 소유한 계정의 사용자 인증 정보를 선택하세요. 키 또는 토큰을 획득하는 방법은 사용자 인증 정보 선택 및 조회를 참조하세요. 설치 명령어는 활성화된 Python 가상 환경에서 실행하세요. 사용할 사용자 인증 정보 탭의 Python 코드를sandbox_auth.py로 저장하세요. 이 파일은 이 페이지에서 실행할 Python script와 같은 위치에 두어야 합니다. 이 파일에는 사용자 인증 정보 자체가 아니라 어떤 인증 방식을 사용할지만 저장됩니다. 예시에서는 이 파일에서 AUTH를 임포트한 다음, 새로 만드는 각 샌드박스 또는 세션에 명시적으로 전달합니다.
- Forge API 키
- CoreWeave API 액세스 토큰
SDK의 W&B 인증 전략으로 Forge API 키를 사용하세요.
sandbox_auth.py
SandboxDefaults에서 placement_mode="cks"를 설정하세요. auth=AUTH로 세션을 생성하면 해당 세션이 소유한 샌드박스도 함께 인증됩니다. 샌드박스에 다시 연결하거나, 샌드박스 목록을 조회하거나, 샌드박스를 정리할 때도 같은 사용자 인증 정보를 사용하세요.
개요
DataPlaneMode 열거형은 데이터 오퍼레이션의 전송 정책을 설정합니다. SDK는 달리 선택하지 않는 한 AUTO를 사용하므로 대부분의 호출자는 코드를 변경하지 않고도 직접 연결을 얻을 수 있습니다.
전송 정책 설정
단일 샌드박스의 전송 정책을 설정하려면Sandbox.run()에 data_plane_mode를 전달하세요. 샌드박스 그룹의 전송 정책을 설정하려면 SandboxDefaults에 data_plane_mode를 전달하세요.
직접 연결이 설정되는 방식
샌드박스가 실행 중인 상태에서 첫 번째 데이터 오퍼레이션을 수행하면, SDK는 메모리에 P-256 개인 키를 생성하고 CoreWeave Sandboxes API에 인증서 서명 요청만 전송합니다. API는 해당 샌드박스에서만 사용할 수 있는 인증서를 반환하며, SDK는 이를 사용하여 샌드박스 자체에 mTLS 연결을 설정합니다. 자격 증명을 이해할 때 이 교환 과정에서 중요한 점은 다음 두 가지입니다.- 개인 키는 클라이언트 프로세스 외부로 절대 전달되지 않습니다. SDK는 키가 아닌 인증서 서명 요청을 전송합니다.
- API Bearer 토큰은 샌드박스 데이터 엔드포인트로 절대 전송되지 않습니다. 샌드박스는 인증서만으로 클라이언트를 인증합니다.
대기 시간 및 폴백
AUTO와 DIRECT는 대기 시간과 설정이 제한 시간 내에 완료되지 않았을 때의 동작이 다릅니다.
AUTO에서는 자격 증명 발급과 채널 준비에 총 1초의 제한 시간이 적용됩니다. 이 시간이 지나면 오퍼레이션은 게이트웨이를 통해 진행되며 SDK는 30초를 기다린 후 다시 직접 연결을 시도합니다. 폴백은 사용자 개입 없이 이루어지며 오퍼레이션은 정상적으로 성공합니다.DIRECT에서는 연결 설정에 최대 10초가 주어지며 폴백은 지원되지 않습니다. 설정이 완료되지 않으면 오퍼레이션에서 오류가 발생합니다.
연결 재사용
SDK는 프로세스 전체에서 공유하는 유휴 직접 채널 풀을 유지하며, 최대 64개로 제한합니다. 풀 크기를 제한하면 비활성 샌드박스 객체로 이루어진 대규모 컬렉션을 보유한 프로그램이 샌드박스마다 소켓을 하나씩 유지하지 않습니다. 활성 스트림은 시작 시 사용한 채널을 계속 사용합니다. 채널이 오래된 것으로 표시되면 기존 스트림은 해당 채널에서 처리를 마무리하고, 새로운 Call은 대체 채널을 생성합니다.오퍼레이션이 사용한 전송 방식 확인
환경에서 직접 연결이 작동하는지 확인하려면DIRECT 모드에서 오퍼레이션을 실행하세요. 이 모드는 대체 경로로 전환하지 않으므로 성공적으로 반환된 오퍼레이션은 직접 전송 방식을 사용한 것입니다. 연결을 설정할 수 없는 오퍼레이션은 게이트웨이를 자동으로 사용하는 대신 오류를 발생시킵니다.
GATEWAY 아래의 동일한 호출이 성공한다면, 샌드박스 데이터 엔드포인트가 네트워크에서 도달할 수 없는 것입니다. 호출자를 AUTO에 유지하여 게이트웨이를 통해 계속 작동하게 하고, 클라이언트와 샌드박스 사이의 egress 제한을 확인하세요.