Cloud Run 샌드박스는 에이전트 코드를 실행하고, 데이터 변환을 수행하고, 기존 작업 내에서 스크립트를 안전하게 실행할 수 있는 빠르고 안전하며 격리된 환경을 제공합니다. 샌드박스는 지연 시간에 최적화되어 있으며 컨테이너와 동일한 인스턴스 내에서 실행되어 할당된 CPU 및 메모리를 공유합니다.
이 페이지에서는 컨테이너에서 샌드박스를 구성하는 방법을 설명합니다. CLI를 사용하여 샌드박스와 상호작용하는 코드를 작성하는 방법에 관한 자세한 내용은 Cloud Run에서 코드 실행을 참고하세요.
시작하기 전에
- Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- gcloud CLI를 설치하고 초기화합니다.
- Cloud Run 작업을 만듭니다.
필요한 역할
Cloud Run 작업을 구성하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.
- Cloud Run 작업에 대한 Cloud Run 개발자(
roles/run.developer) 역할 - 서비스 ID에 대한 서비스 계정 사용자(
roles/iam.serviceAccountUser) 역할
Cloud Run과 연결된 IAM 역할 및 권한 목록은 Cloud Run IAM 역할 및 Cloud Run IAM 권한을 참조하세요. Cloud Run 작업이 Cloud 클라이언트 라이브러리와 같은Google Cloud API와 상호작용하는 경우에는 서비스 ID 구성 가이드를 참조하세요. 역할 부여에 대한 자세한 내용은 배포 권한 및 액세스 관리를 참조하세요.
샌드박스 사용 설정
Cloud Run 작업에서 샌드박스를 사용 설정하려면 Google Cloud CLI, YAML 구성 또는 Terraform을 사용합니다.
gcloud
작업을 만들거나 업데이트하려면 --sandbox-launcher 플래그를 지정합니다.
작업을 만들려면 다음 명령어를 실행합니다.
gcloud beta run jobs create JOB --image IMAGE_URL --sandbox-launcher
다음을 바꿉니다.
- JOB: Cloud Run 작업의 이름
IMAGE_URL: 컨테이너 이미지에 대한 참조(예:us-docker.pkg.dev/cloudrun/container/job:latest)
기존 작업을 업데이트하려면 다음 명령어를 실행합니다.
gcloud beta run jobs update JOB --sandbox-launcher
YAML
새 작업을 만드는 경우에는 이 단계를 건너뜁니다. 기존 작업을 업데이트하는 경우 YAML 구성을 다운로드합니다.
gcloud run jobs describe JOB --format export > job.yaml
컨테이너 구성 내에서
true로 설정된sandboxLauncher속성을 포함하도록 YAML 파일을 업데이트합니다.apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB annotations: run.googleapis.com/launch-stage: BETA spec: template: spec: template: spec: containers: - name: CONTAINER image: IMAGE_URL sandboxLauncher: true다음을 바꿉니다.
- JOB: Cloud Run 작업의 이름
- CONTAINER: 컨테이너의 이름입니다.
IMAGE_URL: 컨테이너 이미지에 대한 참조(예:us-docker.pkg.dev/cloudrun/container/job:latest)
다음 명령어를 사용하여 작업을 만들거나 업데이트합니다.
gcloud run jobs replace job.yaml
gcloud run jobs replace명령어는job.yaml파일이 있는 경우 기본적으로 이 파일을 사용합니다.
Terraform
Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요.
Terraform 구성에서 다음을google_cloud_run_v2_job 리소스에 추가합니다.resource "google_cloud_run_v2_job" "default" {
name = "JOB"
location = "REGION"
template {
template {
containers {
image = "IMAGE_URL"
sandbox_launcher = true
}
}
}
}
다음을 바꿉니다.
- JOB: Cloud Run 작업의 이름
- REGION: Google Cloud 리전입니다. 예를 들면
europe-west1입니다. IMAGE_URL: 컨테이너 이미지에 대한 참조(예:us-docker.pkg.dev/cloudrun/container/job:latest)
샌드박스는 호스트 컨테이너에 할당된 CPU와 메모리를 공유합니다. 기본 컨테이너의 CPU 및 메모리 한도가 애플리케이션과 동시에 실행하는 활성 샌드박스를 모두 수용할 수 있는지 확인합니다.
샌드박스 사용 중지
작업에서 샌드박스를 실행하는 기능을 사용 중지하려면 Google Cloud CLI 또는 YAML 구성을 사용합니다.
gcloud
다음 명령어를 실행하여 --no-sandbox-launcher 플래그를 사용하여 작업을 업데이트합니다.
gcloud beta run jobs update JOB --no-sandbox-launcher
JOB을 작업 이름으로 바꿉니다.
YAML
새 작업을 만드는 경우에는 이 단계를 건너뜁니다. 기존 작업을 업데이트하는 경우 YAML 구성을 다운로드합니다.
gcloud run jobs describe JOB --format export > job.yaml
컨테이너 구성 내에서
sandboxLauncher속성을 삭제하도록 YAML 파일을 업데이트합니다.apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB spec: template: spec: template: spec: containers: - name: CONTAINER image: IMAGE_URL다음을 바꿉니다.
- JOB: Cloud Run 작업의 이름
- CONTAINER: 컨테이너의 이름입니다.
IMAGE_URL: 컨테이너 이미지에 대한 참조(예:us-docker.pkg.dev/cloudrun/container/job:latest)
다음 명령어를 사용하여 작업을 만들거나 업데이트합니다.
gcloud run jobs replace job.yaml
gcloud run jobs replace명령어는job.yaml파일이 있는 경우 기본적으로 이 파일을 사용합니다.
샌드박스 설정 보기
Cloud Run 작업의 현재 샌드박스 설정을 보려면 다음 안내를 따르세요.
콘솔
Google Cloud 콘솔에서 Cloud Run 작업 페이지로 이동합니다.
작업을 클릭하여 작업 세부정보 페이지를 엽니다.
기록 탭의 목록에서 실행된 작업의 ID를 클릭합니다.
컨테이너 탭에서 샌드박스 런처 설정을 찾아 샌드박스 처리된 컨테이너가 사용 설정되어 있는지 또는 사용 중지되어 있는지 확인합니다.
gcloud
다음 명령어를 사용하세요.
gcloud run jobs executions describe EXECUTION_NAME --format yaml
EXECUTION_NAME을 작업 실행 이름으로 바꿉니다.
샌드박스 컨테이너가 사용 설정되었는지 확인하려면 반환된 구성에서
sandboxLauncher: true속성을 찾습니다.
작업에서 샌드박스의 신뢰할 수 없는 코드를 실행하려면 Cloud Run의 코드 실행을 참조하세요.
샌드박스 템플릿 구성
샌드박스 템플릿을 사용하면 샌드박스의 컨테이너 이미지를 정의할 수 있습니다. 기본 애플리케이션 컨테이너 내에서 샌드박스 세션을 실행하는 대신 sandbox do
--template 및 sandbox run --template 명령어는 Python, Node.js 또는 커스텀 실행 환경과 같은 지정된 이미지를 사용하여 새 컨테이너를 실행합니다.
이러한 샌드박스는 자체 컨테이너에서 실행되며 기본 컨테이너의 CPU 및 메모리 한도를 공유합니다. 템플릿에 별도의 CPU 및 메모리 한도를 설정할 수 없습니다. Cloud Run은 최대 10개의 샌드박스 템플릿을 지원합니다.
볼륨 마운트는 Cloud Run 리소스의 인메모리 볼륨을 참조해야 합니다.
샌드박스 템플릿은 다음과 같은 기능을 제공합니다.
전용 컨테이너 이미지:
python:3.12-slim또는busybox:latest와 같은 고유한 컨테이너 이미지를 샌드박스 템플릿으로 선언합니다. 기본 컨테이너에 필요하지 않은 샌드박스에 다른 런타임 및 도구를 사용할 수도 있습니다. 이렇게 하면 샌드박스에만 사용되는 도구와 런타임을 격리하여 기본 컨테이너를 가볍게 유지할 수 있습니다.주문형 인스턴스화: 샌드박스 CLI(
/usr/local/gcp/bin/sandbox)는 새 VM을 프로비저닝하거나 새 인스턴스에 대한 요금을 청구하지 않고 템플릿에서 새 샌드박스 컨테이너를 생성합니다.샌드박스별 격리된 파일 공유: 각 샌드박스가 자체 격리된 하위 디렉터리로 제한되어 샌드박스가 다른 파일을 보거나 수정하지 못하도록 하면서 기본 컨테이너와 여러 샌드박스 간에 메모리 내 볼륨을 공유합니다.
YAML 구성 또는 Cloud Run Admin API를 사용하여 샌드박스 템플릿을 구성할 수 있습니다.
YAML
새 작업을 만드는 경우에는 이 단계를 건너뜁니다. 기존 작업을 업데이트하는 경우 YAML 구성을 다운로드합니다.
gcloud run jobs describe JOB --format export > job.yaml
sandboxes템플릿 구성을 포함하도록 작업 YAML 파일을 업데이트합니다.apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB annotations: run.googleapis.com/launch-stage: BETA spec: template: spec: template: spec: containers: - image: IMAGE_URL sandboxLauncher: true volumeMounts: - name: VOLUME_NAME mountPath: CONTAINER_MOUNT_PATH volumes: - name: VOLUME_NAME emptyDir: medium: Memory sandboxes: templates: - name: TEMPLATE_NAME image: TEMPLATE_IMAGE_URL volumeMounts: - name: VOLUME_NAME mountPath: SANDBOX_MOUNT_PATH subPath: SUBPATH다음을 바꿉니다.
- JOB: Cloud Run 작업의 이름
- IMAGE_URL: 기본 컨테이너에 사용할 컨테이너 이미지 URL입니다.
- TEMPLATE_NAME: 템플릿 이름입니다.
- TEMPLATE_IMAGE_URL: 샌드박스 템플릿에 사용할 컨테이너 이미지 URL입니다.
- 선택사항: VOLUME_NAME: 마운트할 볼륨의 이름입니다.
- 선택사항: CONTAINER_MOUNT_PATH: 기본 컨테이너 내부에 볼륨이 마운트되는 경로입니다.
- 선택사항: SANDBOX_MOUNT_PATH: 볼륨이 샌드박스 컨테이너 내부에 마운트되는 경로입니다.
- 선택사항: SUBPATH: 샌드박스 컨테이너에 마운트할 볼륨 내의 상대 하위 디렉터리 경로(예:
my-subdir) 런타임에 각 샌드박스에 다른 하위 디렉터리를 설정하려면$(VARIABLE_NAME)자리표시자(예:$(SANDBOX_DIR))를 사용합니다.- VARIABLE_NAME에는 ASCII 문자 및 밑줄만 포함할 수 있으며 숫자와 하이픈은 지원되지 않습니다.
- 런타임에 자리표시자를 확인하려면
--template와 함께--template-var=VARIABLE_NAME=VALUE플래그를 전달합니다. subPath는 디렉터리를 자동으로 만들지 않습니다.sandbox do또는sandbox run를 실행하기 전에 기본 컨테이너의 볼륨에 확인된 SUBPATH 디렉터리를 만듭니다(예:mkdir -p사용).
다음 명령어를 사용하여 작업을 만들거나 업데이트합니다.
gcloud run jobs replace job.yaml
gcloud run jobs replace명령어는job.yaml파일이 있는 경우 기본적으로 이 파일을 사용합니다.
REST API
샌드박스 템플릿을 구성하려면 Cloud Run Admin API에 PATCH 요청을 보냅니다.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -X PATCH \ "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB" \ -d '{ "launchStage": "BETA", "template": { "template": { "containers": [ { "image": "IMAGE_URL", "sandboxLauncher": true, "volumeMounts": [ { "name": "VOLUME_NAME", "mountPath": "CONTAINER_MOUNT_PATH" } ] } ], "sandboxes": { "templates": [ { "name": "TEMPLATE_NAME", "image": "TEMPLATE_IMAGE_URL", "volumeMounts": [ { "name": "VOLUME_NAME", "mountPath": "SANDBOX_MOUNT_PATH", "subPath": "SUBPATH" } ] } ] }, "volumes": [ { "name": "VOLUME_NAME", "emptyDir": { "medium": "MEMORY" } } ] } } }'
다음을 바꿉니다.
- JOB: Cloud Run 작업의 이름
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- REGION: Cloud Run 리소스가 배포된 리전
- IMAGE_URL: 기본 컨테이너에 사용할 컨테이너 이미지 URL입니다.
- TEMPLATE_NAME: 템플릿 이름입니다.
- TEMPLATE_IMAGE_URL: 샌드박스 템플릿에 사용할 컨테이너 이미지 URL입니다.
- 선택사항: VOLUME_NAME: 마운트할 볼륨의 이름입니다.
- 선택사항: CONTAINER_MOUNT_PATH: 기본 컨테이너 내부에 볼륨이 마운트되는 경로입니다.
- 선택사항: SANDBOX_MOUNT_PATH: 볼륨이 샌드박스 컨테이너 내부에 마운트되는 경로입니다.
- 선택사항: SUBPATH: 샌드박스 컨테이너에 마운트할 볼륨 내의 상대 하위 디렉터리 경로(예:
my-subdir) 런타임에 각 샌드박스에 다른 하위 디렉터리를 설정하려면$(VARIABLE_NAME)자리표시자(예:$(SANDBOX_DIR))를 사용합니다.- VARIABLE_NAME에는 ASCII 문자 및 밑줄만 포함할 수 있으며 숫자와 하이픈은 지원되지 않습니다.
- 런타임에 자리표시자를 확인하려면
--template와 함께--template-var=VARIABLE_NAME=VALUE플래그를 전달합니다. subPath는 디렉터리를 자동으로 만들지 않습니다.sandbox do또는sandbox run를 실행하기 전에 기본 컨테이너의 볼륨에 확인된 SUBPATH 디렉터리를 만듭니다(예:mkdir -p사용).
작업 컨테이너 내에서 CLI를 사용하여 템플릿을 실행하려면 샌드박스 템플릿을 사용하여 명령어 실행을 참고하세요.