Docker Sandboxes SDK 쿡북

Docker Sandboxes SDK 쿡북

이 레시피들을 사용해 파일 전송, 프로세스, 스토리지, 기타 샌드박스 연산을 애플리케이션에 추가해 보세요. 각 레시피는 관련 SDK 호출과 펼칠 수 있는 완전한 TypeScript 예시를 보여줘요.

출처: 문서

본문

시작하기부터 첫 번째 샌드박스를 실행하거나, SDK를 설치해 기존 프로젝트에서 이 예시들을 사용하세요. HTTP 연산과 요청 필드는 API 레퍼런스를 참고해 주세요.

시작하기

개별 SDK 연산을 살펴보기 전에 인증하고 키트를 실행하세요.

• Docker에 인증하기: 인터랙티브하게 로그인하거나, Docker 개인 접근 토큰을 사용하거나, 애플리케이션에서 액세스 토큰을 제공하세요.
• 완전한 예시 실행하기: 하나의 실행 가능한 프로그램으로 로그인, shell 키트 실행, 인사말 출력, 정리를 해 보세요.
• 첫 번째 샌드박스 만들기: 키트를 실행하고, 그 샌드박스에서 명령을 실행하고, 결과를 검사해요.
• 키트로 에이전트 실행하기: 사용 가능한 키트를 발견하고, 에이전트 샌드박스를 실행하고, 그 안에서 작업을 실행해요.
• 첫 명령 실행하기: 실행 중인 샌드박스에 연결하고, 그 안에서 명령을 실행하고, 실패한 명령과 실패한 호출을 구분해요.
• 클라우드 샌드박스 삭제하기: 다시 읽어 온 샌드박스를 삭제하고 사라질 때까지 기다리며, 현재 상태에 기반한 거부를 덮어쓸 수 있어요.

샌드박스에서 작업하기

실행 중인 샌드박스를 명령, 프로젝트 파일, 웹 애플리케이션에 사용하세요.

• 클라우드 샌드박스에서 인터랙티브 셸 실행하기: 의사 터미널에서 셸을 시작하고, 한 연결로 입력을 보내고 출력을 읽고, 다시 연결해 서비스가 보관한 출력을 이어받고, 중지해요.
• 파일을 클라우드 샌드박스로 복사하기: 실행 중인 클라우드 샌드박스 안에 디렉터리를 만들고, 메모리에서 파일 하나를 그 안에 쓰고, 쓰기가 보고한 크기를 읽어요.
• 샌드박스에서 파일 읽어 내기: 실행 중인 클라우드 샌드박스에서 디렉터리를 나열하고, 그 파일들을 메모리로 다운로드한 뒤, 안의 경로를 이동하거나 제거해요.
• 클라우드 샌드박스에서 포트 노출하기: 클라우드 샌드박스 안의 프로그램이 듣는 TCP 포트를 게시하고, 그 포트에 도달하는 URL을 읽어 보고, 샌드박스의 게시된 포트를 나열하고, 게시를 철회해요.
• 샌드박스 중지하고 다시 시작하기: 실행 중인 샌드박스를 삭제하지 않고 중지하고, 중지가 안정될 때까지 기다리고, 필요할 때 같은 샌드박스를 다시 시작해요.
• 워크로드가 시작될 때 무엇을 가지는지: 샌드박스의 모든 명령이 시작할 때 가지는 환경 변수를 읽고, 둘이 같은 이름을 설정하면 어느 쪽이 이기는지 확인해요.
• 실제 출력을 만드는 것 실행하기: 끝날 때 명령의 캡처된 출력을 반환하는 호출과, 실행되는 동안 출력을 읽는 프로세스를 선택해요.

패키징과 상태

나중에 작업을 위해 환경이나 그 상태를 보존해요.

• 이미지 등록과 관리하기: 이미지를 Cloud Sandboxes에 등록하고, 그 콘텐츠를 푸시할 대상을 얻고, 준비되었는지 확인하고, 이미지를 나열하고, 더 이상 필요 없는 하나를 삭제해요.
• 샌드박스 스냅샷과 포크하기: 실행 중인 샌드박스의 상태를 스냅샷으로 캡처한 뒤 그 스냅샷에서 새 샌드박스를 시작해요.

보안과 정책

애플리케이션 코드에 자격 증명을 넣지 않고 에이전트에 필요한 접근을 부여하세요.

• 샌드박스가 도달할 수 있는 것 제어하기: 새 샌드박스에 계정의 네트워크 정책을 첨부하고, 서비스가 시행하는 정책을 읽고, 허용하거나 차단한 대상을 검토해요.
• 클라우드 시크릿 관리하기: 토큰을 저장된 시크릿으로 저장하고, 시크릿 메타데이터를 나열하고, 토큰을 교체하고, 시크릿을 삭제해요.
• 샌드박스에 MCP 게이트웨이 부여하기: 키트 실행 시 MCP 도구를 구성한 뒤 게이트웨이를 검사, 승인, 관리해요.
• 클라우드 샌드박스용 Docker 자격 증명 추가하기: Docker OIDC ID 토큰을 서비스가 샌드박스가 사용하도록 저장하는 자격 증명으로 교환해요.
• 저장된 시크릿을 샌드박스로 가져오기: 자격 증명을 한 번 저장한 뒤 샌드박스를 만들 때 그 리소스 이름을 전달해 샌드박스가 그 시크릿을 첨부한 채 시작하게 해요.
• 네트워크 정책 관리하기: SDK로 개인 네트워크 정책을 만들고, 읽고, 업데이트하고, 삭제해요.

연결과 구성

다른 이미지를 선택하고, 수명을 제어하고, 추가 스토리지와 클라이언트를 연결해요.

• 자체 컨테이너 이미지 실행하기: 관리되는 이미지 대신 이름을 지정한 레지스트리의 컨테이너 이미지에서 샌드박스를 시작해요.
• 클라우드 샌드박스 계속 실행하기: 샌드박스의 수명과 끝날 때 일어날 일을 선택하고, 마감 전에 수명을 갱신해요.
• 영구 스토리지 첨부하기: 볼륨을 만들고, 그 데이터가 샌드박스보다 오래 지속되도록 새 샌드박스에 마운트하고, 더 이상 필요 없을 때 볼륨을 삭제해요.
• SSH 인증서 받기: 서비스가 한 샌드박스에 대해 SSH 공개 키에 서명하고, SSH 클라이언트가 필요로 하는 호스트, 포트, 사용자 이름, 호스트 키를 반환하게 해요.
• 이미지 풀 URL 받기: 관리되는 이미지의 매니페스트 세부 정보와 단기 다운로드 URL을 가져와 레지스트리 도구가 그 콘텐츠를 풀할 수 있게 해요.
• 중지된 샌드박스 주문형 재개하기: 생성 시 중지된 클라우드 샌드박스가 게시된 포트 중 하나에 요청이 오면 스스로 시작할지 선택하고, 시행 중인 설정을 다시 읽어 확인해요.

요청과 응답

요청 옵션과 실패를 의도적으로 처리해요.

• 오류와 성능 저하 처리하기: API 거부, 실패한 샌드박스 전환, 0이 아닌 명령 종료를 구분하고, 각각이 옮기는 코드와 세부 정보를 읽어요.
• 중복 없이 재시도하기: 해석할 수 없는 실패가 두 복사본을 남기지 않도록 한 요청 ID로 샌드박스나 프로세스 생성을 재시도해요.
• 목록 페이지 매김과 필터링하기: SDK의 반복자로 목록의 모든 페이지를 돌고, 서버에서 필터와 정렬로 목록을 좁혀요.
• API가 받아들이는 값 보내기: 기간, 횟수, 플래그가 의도한 의미를 갖는 생성 요청을 만들고, 서비스가 정한 값을 다시 읽어 확인해요.
• 제한 안에서 작업하기: 지원되는 컴퓨트 크기를 선택하고, 계정 할당량을 이해하고, 끝없는 재시도 없이 거부를 처리해요.

장기 실행 작업

연결이 끊겨도 작업을 계속하거나 여러 샌드박스를 조정해요.

• 놓친 프로세스 찾기: 만들 때 준 세션 태그로 실행 중인 프로세스를 검색하고, 자체 보고서가 게시하는 재개 지점부터 출력을 이어받아요.
• 클라우드 샌드박스 클론하기: 실행 중인 샌드박스가 어떻게 구성되었는지 읽고, 같은 이미지와 환경으로 두 번째 샌드박스를 만들어요.
• 여러 샌드박스에 걸쳐 작업 실행하기: 보유한 모든 실행 중인 샌드박스에 한 번에 제한된 수씩 명령 하나를 실행하고, 일부가 실패해도 샌드박스당 하나의 답을 읽어요.
• 엔드포인트가 움직일 때 복구하기: 현재 엔드포인트를 알기 위해 샌드박스를 다시 읽고, 그 엔드포인트를 위해 만든 연결로 명령 하나를 실행해요.

더 알아보기 (Learn more)