이 문서에서는 Google Kubernetes Engine (GKE) 클러스터에 에이전트 샌드박스 컨트롤러를 설치하고 실행하는 방법을 설명합니다. 또한 신뢰할 수 없는 셸 명령어를 테스트할 수 있는 샌드박스 환경을 클러스터에 배포하는 방법을 설명합니다.
에이전트 샌드박스 컨트롤러는 임시 런타임 환경을 만들고 관리하는 프레임워크를 제공합니다. 이 방법을 사용하면 앱 환경의 템플릿을 정의한 다음 필요에 따라 인스턴스를 만들 수 있습니다.
에이전트 샌드박스는 대규모 언어 모델 (LLM)이 생성한 코드와 같은 신뢰할 수 없는 코드를 실행할 수 있는 안전하고 격리된 환경을 제공합니다. 이러한 유형의 코드를 클러스터에서 직접 실행하면 신뢰할 수 없는 코드가 다른 앱이나 기본 클러스터 노드 자체에 액세스하거나 이를 방해할 수 있으므로 보안 위험이 발생합니다.
에이전트 샌드박스는 실행하는 코드에 강력한 프로세스, 스토리지, 네트워크 격리를 제공하여 이러한 위험을 완화합니다. 이 격리는 애플리케이션과 클러스터 노드의 운영체제 사이에 안전한 장벽을 만드는 기술인 gVisor를 사용하여 이루어집니다. Kata 컨테이너와 같은 다른 샌드박스 기술을 대신 사용할 수 있지만 이 문서의 예에서는 gVisor만 사용합니다.
이 문서에서는 GKE Autopilot 클러스터 또는 Standard 클러스터에서 에이전트 샌드박스를 실행하는 방법을 설명합니다.
에이전트 샌드박스는 오픈소스 프로젝트입니다. 프로젝트에 참여하거나 자세한 기술 정보를 확인하려면 Agent Sandbox 오픈소스 프로젝트를 참고하세요.
비용
이 문서의 단계를 따르면 Google Cloud계정에 비용이 청구됩니다. GKE 클러스터를 만들면 비용이 청구되기 시작합니다. 이 비용에는 가격 책정 페이지에 설명된 대로 GKE의 클러스터당 요금과 Compute Engine VM 실행 요금이 포함됩니다.
불필요한 요금이 청구되지 않도록 이 문서를 완료한 후 GKE를 중지하거나 프로젝트를 삭제하세요.
시작하기 전에
-
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.
-
Enable the Artifact Registry, Google Kubernetes Engine APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. -
In the Google Cloud console, activate Cloud Shell.
환경 변수 정의
이 문서에서 실행하는 명령어를 간소화하려면 Cloud Shell에서 환경 변수를 설정하면 됩니다. Cloud Shell에서 다음 명령어를 실행하여 유용한 환경 변수를 정의합니다.
export PROJECT_ID=$(gcloud config get project) export CLUSTER_NAME="agent-sandbox-cluster" export GKE_LOCATION="us-central1" export AGENT_SANDBOX_VERSION="v0.1.0" export NODE_POOL_NAME="agent-sandbox-node-pool" export MACHINE_TYPE="e2-standard-2" export PYTHON_CLIENT_VERSION="main"다음은 이러한 환경 변수에 대한 설명입니다.
PROJECT_ID: 현재 Google Cloud 프로젝트의 ID입니다. 이 변수를 정의하면 GKE 클러스터와 같은 모든 리소스가 올바른 프로젝트에 생성됩니다.CLUSTER_NAME: GKE 클러스터의 이름입니다(예:agent-sandbox-cluster).GKE_LOCATION: GKE 클러스터 및 Artifact Registry 저장소가 생성될 Google Cloud 리전입니다(예:us-central1). 이미지 가져오기 지연 시간을 줄이므로 함께 배치하는 것이 좋습니다.AGENT_SANDBOX_VERSION: 클러스터에 배포할 에이전트 샌드박스 컨트롤러의 버전입니다.NODE_POOL_NAME: 샌드박스 처리된 워크로드를 실행할 노드 풀의 이름입니다(예:agent-sandbox-node-pool).MACHINE_TYPE: 노드 풀에 있는 노드의 머신 유형입니다(예:e2-standard-2). 다양한 머신 시리즈 및 옵션 선택에 대한 자세한 내용은 머신 계열 리소스 및 비교 가이드를 참고하세요.PYTHON_CLIENT_VERSION: 설치할 Agentic Sandbox Python 클라이언트 버전입니다.
에이전트 샌드박스 배포
이제 Google Cloud 프로젝트와 Cloud Shell 환경이 설정되었으므로 필요한 인프라를 프로비저닝하고 에이전트 샌드박스를 배포할 수 있습니다.
GKE 클러스터 만들기
다음으로 gVisor가 사용 설정된 GKE 클러스터를 만듭니다. 이 클러스터는 에이전트 샌드박스 컨트롤러와 샘플 샌드박스 앱을 배포하고 실행할 Kubernetes 환경을 제공합니다. gVisor는 신뢰할 수 없는 코드를 안전하게 실행하는 샌드박스 기술을 제공합니다.
Autopilot 또는 Standard 클러스터를 만들 수 있습니다. Autopilot은 gVisor를 자동으로 사용 설정하는 반면 Standard 클러스터에서는 gVisor 지원 노드 풀을 수동으로 만들어야 합니다.
Autopilot
gcloud CLI를 사용하여 Autopilot 클러스터를 만들려면 다음 명령어를 실행합니다.
gcloud container clusters create-auto ${CLUSTER_NAME} \ --location=${GKE_LOCATION} \ --project=${PROJECT_ID}표준
gcloud CLI를 사용하여 Standard 클러스터를 만들려면 다음 단계를 따르세요.
클러스터를 만듭니다.
gcloud container clusters create ${CLUSTER_NAME} \ --location=${GKE_LOCATION}gVisor가 사용 설정된 별도의 노드 풀을 만듭니다.
gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --location=${GKE_LOCATION} \ --machine-type=${MACHINE_TYPE} \ --image-type=cos_containerd \ --sandbox type=gvisor
kubectlCLI가 클러스터에 연결할 수 있도록 클러스터의 사용자 인증 정보를 검색합니다. 이 명령어는 기본적으로~/.kube/config디렉터리에 저장된 Kubernetes 구성 파일을 업데이트합니다. 이 구성 파일에는kubectl이 GKE 클러스터와 상호작용하는 데 필요한 사용자 인증 정보가 포함되어 있습니다.gcloud container clusters get-credentials ${CLUSTER_NAME} \ --location=${GKE_LOCATION}클러스터에 에이전트 샌드박스 컨트롤러 배포
공식 출시 매니페스트를 클러스터에 적용하여 에이전트 샌드박스 컨트롤러와 필수 구성요소를 배포할 수 있습니다. 이러한 매니페스트는 클러스터에 에이전트 샌드박스 컨트롤러를 배포하고 실행하는 데 필요한 모든 구성요소를 다운로드하도록 Kubernetes에 지시하는 구성 파일입니다.
다음 명령어를 실행하여 에이전트 샌드박스 컨트롤러를 GKE 클러스터에 배포합니다.
kubectl apply \ -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \ -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml에이전트 샌드박스 컨트롤러 확인
매니페스트를 적용한 후 에이전트 샌드박스 컨트롤러 포드가
agent-sandbox-system네임스페이스에서 올바르게 실행되고 있는지 확인합니다.kubectl get pods -n agent-sandbox-systemSTATUS 열에 'Running'이 표시되고 READY 열에 '1/1'이 표시될 때까지 기다립니다. 포드가 올바르게 실행되면 출력은 다음과 비슷합니다.
NAME READY STATUS RESTARTS AGE agent-sandbox-controller-0 1/1 Running 0 44d이제 에이전트 샌드박스 컨트롤러가 실행되므로 클러스터에서 만드는 모든
Sandbox리소스의 샌드박스 환경을 자동으로 만들고 관리할 수 있습니다.샌드박스 환경 배포
이제 GKE 클러스터에서 에이전트 샌드박스 컨트롤러가 실행되므로 샘플 샌드박스 환경의 구성요소를 배포해야 합니다. 이 섹션에서는 샌드박스 청사진(
SandboxTemplate)을 만들고, 필요한 네트워킹 라우터를 배포하고, 샌드박스와 상호작용하는 데 사용할 Python 클라이언트를 설치하는 방법을 보여줍니다.샌드박스를 만들고 샌드박스와 상호작용하는 데는 Agentic Sandbox Python 클라이언트를 사용하는 것이 좋습니다. 이 클라이언트는 생성부터 정리까지 샌드박스의 전체 수명 주기를 간소화하는 인터페이스를 제공합니다. 샌드박스를 프로그래매틱 방식으로 만들고, 사용하고, 삭제하는 데 사용할 수 있는 Python 라이브러리입니다.
클라이언트는 샌드박스 라우터를 모든 트래픽의 중앙 진입점으로 사용합니다. 이 문서에 설명된 예시에서 클라이언트는
kubectl port-forward명령어를 사용하여 이 라우터에 터널을 만드므로 공개 IP 주소를 노출할 필요가 없습니다.kubectl port-forward를 사용하는 것은 안전한 솔루션이 아니며 개발 환경으로 사용을 제한해야 합니다.SandboxTemplate및SandboxWarmPool만들기이제
SandboxTemplate및SandboxWarmPool리소스를 만들어 샌드박스의 구성을 정의합니다.SandboxTemplate는 에이전트 샌드박스 컨트롤러가 일관된 사전 구성된 샌드박스 환경을 만드는 데 사용하는 재사용 가능한 청사진 역할을 합니다.SandboxWarmPool리소스는 지정된 수의 예열된 포드가 항상 실행 중이고 클레임할 준비가 되어 있는지 확인합니다. 사전 워밍된 샌드박스는 이미 초기화된 실행 중인 포드입니다. 이 사전 초기화를 통해 1초 이내에 새 샌드박스를 만들 수 있으며 일반 샌드박스 실행의 시작 지연 시간을 방지할 수 있습니다.Cloud Shell에서 다음 콘텐츠가 포함된
sandbox-template-and-pool.yaml파일을 만듭니다.apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxTemplate metadata: name: python-runtime-template namespace: default spec: podTemplate: metadata: labels: sandbox: python-sandbox-example spec: runtimeClassName: gvisor containers: - name: python-runtime image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0 ports: - containerPort: 8888 readinessProbe: httpGet: path: "/" port: 8888 initialDelaySeconds: 0 periodSeconds: 1 resources: requests: cpu: "250m" memory: "512Mi" ephemeral-storage: "512Mi" restartPolicy: "OnFailure" --- apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxWarmPool metadata: name: python-sandbox-warmpool namespace: default spec: replicas: 2 sandboxTemplateRef: name: python-runtime-templateSandboxTemplate및SandboxWarmPool매니페스트를 적용합니다.kubectl apply -f sandbox-template-and-pool.yaml
샌드박스 라우터 배포
샌드박스 환경을 만들고 상호작용하는 데 사용할 Python 클라이언트는 샌드박스와 통신하기 위해 샌드박스 라우터라는 구성요소를 사용합니다.
이 예시에서는 테스트를 위해 클라이언트의 개발자 모드를 사용합니다. 이 모드는 로컬 개발을 위한 것으로,
kubectl port-forward명령어를 사용하여 로컬 머신에서 클러스터에서 실행되는 샌드박스 라우터 서비스로 직접 터널을 설정합니다. 이 터널링 접근 방식을 사용하면 공개 IP 주소나 복잡한 인그레스 설정이 필요하지 않으며 로컬 환경에서 샌드박스와의 상호작용이 간소화됩니다.샌드박스 라우터를 배포하려면 다음 단계를 따르세요.
Cloud Shell에서 다음 콘텐츠가 포함된
sandbox-router.yaml파일을 만듭니다.# A ClusterIP Service to provide a stable endpoint for the router pods. apiVersion: v1 kind: Service metadata: name: sandbox-router-svc namespace: default spec: type: ClusterIP selector: app: sandbox-router ports: - name: http protocol: TCP port: 8080 # The port the service will listen on targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile) --- # The Deployment to manage and run the router pods. apiVersion: apps/v1 kind: Deployment metadata: name: sandbox-router-deployment namespace: default spec: replicas: 2 # Run at least two replicas for high availability selector: matchLabels: app: sandbox-router template: metadata: labels: app: sandbox-router spec: # Ensure pods are spread across different zones for HA topologySpreadConstraints: - maxSkew: 1 topologyKey: topology.kubernetes.io/zone whenUnsatisfiable: ScheduleAnyway labelSelector: matchLabels: app: sandbox-router containers: - name: router image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:v20251124-v0.1.0-10-ge26ddb2 ports: - containerPort: 8080 readinessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 5 periodSeconds: 5 livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 10 periodSeconds: 10 resources: requests: cpu: "250m" memory: "512Mi" limits: cpu: "1000m" memory: "1Gi" securityContext: runAsUser: 1000 runAsGroup: 1000매니페스트를 적용하여 라우터를 클러스터에 배포합니다.
kubectl apply -f sandbox-router.yaml
Python 클라이언트 설치
이제 샌드박스 라우터와 같은 클러스터 내 구성요소가 배포되었으므로 마지막 준비 단계는 로컬 머신에 Agentic Sandbox Python 클라이언트를 설치하는 것입니다. 이 클라이언트는 프로그래매틱 방식으로 샌드박스를 만들고, 사용하고, 삭제할 수 있는 Python 라이브러리입니다. 다음 섹션에서 환경을 테스트하는 데 사용합니다.
Python 가상 환경을 만들고 활성화합니다.
python3 -m venv .venv source .venv/bin/activateagent-sandbox저장소에서 클라이언트 패키지를 설치합니다.pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"
샌드박스 테스트
모든 설정 구성요소가 준비되었으므로 이제 에이전트 샌드박스 Python 클라이언트를 사용하여 샌드박스를 만들고 상호작용할 수 있습니다.
agent-sandbox디렉터리에서 다음 콘텐츠가 포함된test_sandbox.py이라는 Python 스크립트를 만듭니다.from agentic_sandbox import SandboxClient # Automatically tunnels to svc/sandbox-router-svc with SandboxClient( template_name="python-runtime-template", namespace="default" ) as sandbox: print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout )가상 환경이 활성 상태인 터미널에서 테스트 스크립트를 실행합니다.
python3 test_sandbox.py
샌드박스에서 출력된 '샌드박스 환경에서 안녕하세요'라는 메시지가 표시됩니다.
축하합니다. 보안 샌드박스 내에서 셸 명령어를 실행했습니다.
sandbox.run()메서드를 사용하면 셸 명령어를 실행할 수 있으며, 에이전트 샌드박스는 클러스터의 노드와 기타 워크로드를 신뢰할 수 없는 코드로부터 보호하는 보안 장벽 내에서 명령어를 실행합니다. 이를 통해 AI 에이전트 또는 자동화된 워크플로가 작업을 실행하는 안전하고 신뢰할 수 있는 방법을 제공합니다.스크립트를 실행하면
SandboxClient가 모든 단계를 처리합니다. 샌드박스를 시작하기 위해SandboxClaim리소스를 만들고 샌드박스가 준비될 때까지 기다린 다음sandbox.run()메서드를 사용하여 보안 컨테이너 내에서 bash 셸 명령어를 실행합니다. 그런 다음 클라이언트는 해당 명령에서stdout를 캡처하여 출력합니다. 샌드박스는 프로그램이 실행된 후 자동으로 삭제됩니다.리소스 삭제
Google Cloud 계정에 요금이 청구되지 않도록 하려면 만든 GKE 클러스터를 삭제해야 합니다.
gcloud container clusters delete $CLUSTER_NAME --location=$GKE_LOCATION --quiet다음 단계
- GitHub에서 에이전트 샌드박스 오픈소스 프로젝트에 대해 자세히 알아보세요.
- 워크로드에 보안 격리를 제공하는 기본 기술을 알아보려면 GKE Sandbox를 참고하세요.
- 클러스터 및 워크로드의 보안 강화에 대한 자세한 내용은 GKE 보안 개요를 참고하세요.