이 문서는 Standard 클러스터에만 적용됩니다.
이 문서에서는 GKE Pod 스냅샷을 사용하여 실행 중인 에이전트 샌드박스 환경의 상태를 저장하는 방법을 보여줍니다.
에이전트 샌드박스는 대규모 언어 모델 (LLM)이 생성한 코드와 같은 신뢰할 수 없는 코드를 실행할 수 있는 안전하고 격리된 환경을 제공합니다. 이러한 유형의 코드를 클러스터에서 직접 실행하면 신뢰할 수 없는 코드가 다른 앱이나 기본 클러스터 노드 자체에 액세스하거나 이를 방해할 수 있으므로 보안 위험이 발생합니다.
GKE Pod 스냅샷을 사용하면 샌드박스 환경의 상태를 저장하고 복원할 수 있습니다. 이 기능은 다음과 같은 이유로 유용합니다.
- 빠른 시작: 미리 워밍된 스냅샷에서 복원하여 샌드박스 시작 시간을 줄입니다.
- 장기 실행 에이전트: 실행하는 데 시간이 오래 걸리는 샌드박스를 일시중지하고 나중에 진행 상황을 잃지 않고 다시 시작하거나 다른 노드로 이동합니다.
- 스테이트풀 워크로드: 샌드박스 환경의 상태를 저장하고 복원하여 대화 기록이나 중간 계산과 같은 에이전트의 컨텍스트를 유지합니다.
- 재현성: 특정 상태를 캡처하고 이를 기반으로 동일한 초기화 상태로 여러 개의 새 샌드박스를 시작합니다.
스냅샷은 다음 두 가지 방법으로 트리거할 수 있습니다.
- 수동 트리거: 스냅샷을 트리거하기 위해
PodSnapshotManualTrigger리소스를 만듭니다. - 워크로드 트리거: 샌드박스 처리된 애플리케이션 자체가 저장될 준비가 되면 신호를 보냅니다.
이 문서에서는 스냅샷을 수동으로 트리거하는 방법을 보여줍니다.
참고: 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 Google Kubernetes Engine, Cloud Storage, Identity and Access Management (IAM) 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.
요구사항
GKE 포드 스냅샷을 사용하려면 GKE 버전 1.34.1-gke.3084001 이상을 실행하는 Standard 모드 클러스터가 필요합니다. GKE 버전 1.35 이상을 사용하는 것이 좋습니다. GKE 버전 1.34에는 Cloud Storage 권한 버그와 관련된 입력/출력 오류로 인해 체크포인트가 실패할 수 있는 알려진 문제가 있습니다.
포드 스냅샷은 E2 머신 유형을 지원하지 않습니다. 따라서 이 튜토리얼에서는 N2 머신으로 구성된 노드 풀을 만듭니다.
노드 풀의 노드에 GPU 기반 머신 유형을 사용하려면 제한사항 및 요구사항을 참고하세요.
환경 변수 정의
이 문서에서 실행하는 명령어를 간소화하려면 Cloud Shell에서 환경 변수를 설정하면 됩니다. 이러한 변수는 Google Cloud 프로젝트의 ID, 스냅샷을 저장할 Cloud Storage 버킷의 이름, GKE 클러스터의 위치와 같은 값을 저장합니다.
이러한 변수를 정의한 후에는 매번 값을 다시 입력하거나 바꾸는 대신 변수 이름 (예:
$CLUSTER_NAME)을 참조하여 여러 명령어에서 재사용할 수 있습니다. 이 접근 방식을 사용하면 프로세스를 더 쉽게 따라갈 수 있으므로 오류 위험이 줄어듭니다.Cloud Shell에서 유용한 다음 환경 변수를 정의하려면 다음 명령어를 실행하세요.
export PROJECT_ID=$(gcloud config get project) export CLUSTER_NAME="agent-sandbox-cluster" export GKE_LOCATION="us-central1" export GKE_VERSION="1.35.0-gke.1795000" export AGENT_SANDBOX_VERSION="v0.1.0" export NODE_POOL_NAME="agent-sandbox-node-pool" export MACHINE_TYPE="n2-standard-2" export SNAPSHOTS_BUCKET_NAME="agent-sandbox-snapshots-${PROJECT_ID}" export SNAPSHOT_NAMESPACE="pod-snapshots-ns" export SNAPSHOT_KSA_NAME="pod-snapshot-sa" export SNAPSHOT_FOLDER="my-snapshots" export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")다음은 이러한 환경 변수에 대한 설명입니다.
PROJECT_ID: 현재 Google Cloud 프로젝트의 ID입니다. 이 변수를 정의하면 GKE 클러스터와 같은 모든 리소스가 올바른 프로젝트에 생성됩니다.CLUSTER_NAME: GKE 클러스터의 이름입니다 (예:agent-sandbox-cluster).GKE_LOCATION: GKE 클러스터가 생성될 Google Cloud 리전입니다 (예:us-central1).GKE_VERSION: 포드 스냅샷과의 호환성에 필요한 GKE 클러스터 및 노드 버전입니다. GKE 포드 스냅샷에는 GKE 버전 1.34.1-gke.3084001 이상이 필요합니다.AGENT_SANDBOX_VERSION: 클러스터에 배포할 에이전트 샌드박스 컨트롤러의 버전입니다.NODE_POOL_NAME: 샌드박스 처리된 워크로드를 실행할 노드 풀의 이름입니다 (예:agent-sandbox-node-pool).MACHINE_TYPE: 노드 풀에 있는 노드의 머신 유형입니다 (예:n2-standard-2). 포드 스냅샷은 E2 머신 유형을 지원하지 않습니다. 노드 풀의 노드에 GPU 기반 머신 유형을 사용하려면 제한사항 및 요구사항을 참고하세요. 다양한 머신 시리즈와 옵션 선택에 관한 자세한 내용은 머신 계열 리소스 및 비교 가이드를 참고하세요.SNAPSHOTS_BUCKET_NAME: 스냅샷을 저장하기 위해 만들 Cloud Storage 버킷의 이름입니다.SNAPSHOT_NAMESPACE: 스냅샷 워크로드 및 서비스 계정이 있는 Kubernetes 네임스페이스입니다.SNAPSHOT_KSA_NAME: 워크로드가 인증하는 데 사용할 Kubernetes 서비스 계정의 이름입니다.SNAPSHOT_FOLDER: 스냅샷이 정리될 Cloud Storage 버킷 내부의 디렉터리입니다.PROJECT_NUMBER: IAM 권한 바인딩에 사용되는 프로젝트의 고유 숫자 식별자입니다.
구성 단계 개요
에이전트 샌드박스 환경의 포드 스냅샷을 사용 설정하려면 몇 가지 구성 단계를 실행해야 합니다. 이 단계를 이해하려면 먼저 몇 가지 주요 개념과 스냅샷 프로세스를 이해하는 것이 좋습니다.
주요 개념
- 환경: 샌드박스 애플리케이션이 GKE 클러스터 노드의 Kubernetes 포드 내에서 실행됩니다.
- ID: 포드가 Kubernetes 서비스 계정과 연결되고 사용자가 만든 특수 네임스페이스에서 실행됩니다. Kubernetes 서비스 계정과 네임스페이스는 함께 포드에 Google Cloud 리소스에 대한 보안 액세스 권한을 부여하는 데 사용되는 고유한 ID를 형성합니다.
- 권한: 스냅샷을 Cloud Storage에 저장할 수 있도록 포드의 ID에 Cloud Storage 버킷에 쓸 수 있는 특정 IAM 권한이 부여되어야 합니다.
스냅샷 프로세스
- 트리거: 스냅샷이 수동 (외부)으로 또는 샌드박스 처리된 워크로드 자체에 의해 시작됩니다. 이 문서에서는
PodSnapshotManualTrigger리소스를 만들어 시작하는 수동 트리거를 보여줍니다. - 캡처: GKE는 포드의 메모리 및 파일 시스템 상태와 같은 포드의 실행 상태를 캡처합니다.
- 업로드: 포드의 Kubernetes 서비스 계정에 부여된 권한을 사용하여 GKE는 캡처된 상태를 스냅샷 파일로 지정된 Cloud Storage 버킷에 업로드합니다.
GKE가 Kubernetes 서비스 계정 및 IAM 역할을 사용하여 Google Cloud 리소스에 액세스하는 방법을 자세히 알아보려면 GKE 워크로드에서 Google Cloud API 인증을 참고하세요.
에이전트 샌드박스 환경의 Pod 스냅샷을 사용 설정하려면 다음 구성을 실행하세요. 먼저 GKE용 워크로드 아이덴티티 제휴 및 포드 스냅샷 기능이 사용 설정된 GKE 클러스터를 만들어 클러스터 환경을 준비합니다. 그런 다음 스냅샷이 안전하게 저장되고 샌드박스에 필요한 권한이 있는지 확인하기 위해 Cloud Storage 및 IAM 정책을 구성합니다. 마지막으로 샌드박스의 스토리지 위치와 정책을 지정하는 스냅샷 리소스를 만듭니다.
다음 표에는 실행해야 하는 구성 단계가 요약되어 있으며 각 단계는 다음 섹션에 설명되어 있습니다.
클러스터 설정
샌드박스 앱은 GKE 클러스터 노드의 포드 내에서 실행되므로 클러스터 환경을 설정해야 합니다. 이 섹션에서는 GKE 클러스터를 만들고 에이전트 샌드박스 컨트롤러를 배포하는 방법을 보여줍니다.
GKE 클러스터 만들기
GKE Standard 클러스터를 만듭니다. 이 클러스터는 에이전트 샌드박스 환경의 스냅샷을 생성할 Kubernetes 환경을 제공합니다. 다음 명령어는 클러스터를 만들고 GKE용 워크로드 아이덴티티 제휴 및 포드 스냅샷 기능을 사용 설정합니다.
Google Cloud CLI를 사용하여 표준 클러스터를 만들려면 다음 명령어를 실행합니다.
gcloud beta container clusters create ${CLUSTER_NAME} \ --location=${GKE_LOCATION} \ --cluster-version=${GKE_VERSION} \ --workload-pool=${PROJECT_ID}.svc.id.goog \ --workload-metadata=GKE_METADATA \ --num-nodes=1 \ --enable-pod-snapshots이 명령어는 클러스터를 만드는 것 외에도 클러스터에서 GKE용 워크로드 아이덴티티 제휴와 포드 스냅샷 기능을 사용 설정합니다.
kubectlCLI가 클러스터에 연결할 수 있도록 클러스터의 사용자 인증 정보를 검색합니다. 이 명령어는 기본적으로~/.kube/config디렉터리에 저장된 Kubernetes 구성 파일을 업데이트합니다. 이 구성 파일에는kubectl이 GKE 클러스터와 상호작용하는 데 필요한 사용자 인증 정보가 포함되어 있습니다.gcloud container clusters get-credentials ${CLUSTER_NAME} \ --location=${GKE_LOCATION}gVisor가 사용 설정된 노드 풀을 만듭니다.
gcloud container node-pools create ${NODE_POOL_NAME} \ --cluster=${CLUSTER_NAME} \ --location=${GKE_LOCATION} \ --machine-type=${MACHINE_TYPE} \ --node-version=${GKE_VERSION} \ --image-type=cos_containerd \ --num-nodes=1 \ --sandbox type=gvisor이 명령어는 다음 주요 플래그를 사용합니다.
--image-type=cos_containerd: 노드가 containerd를 포함한 Container-Optimized OS를 사용하도록 지정합니다.--sandbox type=gvisor: 노드에서 gVisor 샌드박스 기술을 사용 설정합니다. 이는 에이전트 샌드박스에 필요합니다.
클러스터에 에이전트 샌드박스 컨트롤러 배포
공식 출시 매니페스트를 클러스터에 적용하여 에이전트 샌드박스 컨트롤러와 필수 구성요소를 배포할 수 있습니다. 이러한 매니페스트는 클러스터에 에이전트 샌드박스 컨트롤러를 배포하고 실행하는 데 필요한 모든 구성요소를 다운로드하도록 Kubernetes에 지시하는 구성 파일입니다.
GKE 클러스터에 에이전트 샌드박스를 배포하려면 다음 명령어를 실행합니다.
# Apply the main manifest for the controller and its Custom Resource Definitions (CRDs) 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네임스페이스에서 올바르게 실행되고 있는지 확인합니다. 매니페스트는 이전 단계에서 적용할 때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리소스의 샌드박스 환경을 자동으로 만들고 관리할 수 있습니다.스토리지 및 권한 구성
이 섹션에서는 Pod 스냅샷에 필요한 스토리지와 권한을 구성하는 방법을 보여줍니다. 스냅샷 데이터를 저장할 Cloud Storage 버킷과 관리형 폴더를 만듭니다. 그런 다음 샌드박스와 스냅샷 컨트롤러에 해당 저장소에 액세스하는 데 필요한 권한을 부여합니다.
Cloud Storage 버킷 만들기
스냅샷을 저장할 버킷을 만듭니다. 스냅샷 프로세스가 빠르고 비용 효율적인지 확인하려면 다음 설정으로 버킷을 만드는 것이 좋습니다.
- 계층적 네임스페이스 사용 설정: 계층적 네임스페이스 기능은 버킷을 플랫 네임스페이스가 아닌 파일 시스템 계층 구조로 구성합니다. 이 구성을 사용하면 읽기 및 쓰기 처리량이 높아지므로 스냅샷 저장 및 복원 속도가 빨라집니다.
- 소프트 삭제 사용 중지: 소프트 삭제 기능은 삭제된 파일을 일정 기간 동안 보관하여 데이터를 보호합니다. 하지만 스냅샷 프로세스는 업로드 중에 많은 임시 파일을 생성하고 삭제합니다. 이러한 임시 파일을 저장하는 데 불필요한 요금이 청구되지 않도록 소프트 삭제를 사용 중지하는 것이 좋습니다.
이러한 설정으로 버킷을 만들려면 다음 명령어를 실행합니다.
gcloud storage buckets create "gs://${SNAPSHOTS_BUCKET_NAME}" \ --uniform-bucket-level-access \ --enable-hierarchical-namespace \ --soft-delete-duration=0d \ --location="${GKE_LOCATION}"관리형 폴더 만들기
버킷 내에서 스냅샷을 정리하기 위해 관리 폴더를 만듭니다. 관리 폴더를 사용하면 전체 버킷이 아닌 특정 폴더에 IAM 권한을 적용할 수 있습니다. 이 폴더 수준 액세스는 샌드박스의 액세스를 자체 스냅샷으로만 제한하고 이러한 스냅샷을 버킷의 다른 데이터와 격리합니다.
관리형 폴더를 만들려면 다음 명령어를 실행합니다.
gcloud storage managed-folders create "gs://${SNAPSHOTS_BUCKET_NAME}/${SNAPSHOT_FOLDER}/"서비스 계정 및 IAM 역할 구성
GKE가 스냅샷을 안전하게 저장하도록 하려면 샌드박스 처리된 워크로드를 실행하는 포드에서 사용하는 Kubernetes 서비스 계정에 버킷에 쓸 수 있는 권한이 있어야 합니다. 이 권한은 Pod에서 사용하는 Kubernetes 서비스 계정에 Google CloudIAM 역할을 바인딩하여 부여합니다. 이 섹션에서는 커스텀 IAM 역할을 만들고, Kubernetes 서비스 계정을 만들고, 필요한 권한을 구성하는 방법을 보여줍니다.
스냅샷 데이터를 쓰는 데 필요한 권한이 포함된
podSnapshotGcsReadWriter라는 커스텀 IAM 역할을 만듭니다.gcloud iam roles create podSnapshotGcsReadWriter \ --project="${PROJECT_ID}" \ --permissions="storage.objects.get,storage.objects.create,storage.objects.delete,storage.folders.create"역할이 성공적으로 생성되면 출력은 다음과 같이 표시됩니다.
Created role [podSnapshotGcsReadWriter]. etag: BwZJUfjNbew= includedPermissions: - storage.folders.create - storage.objects.create - storage.objects.delete - storage.objects.get name: projects/${PROJECT_ID}/roles/podSnapshotGcsReadWriter stage: ALPHA title: podSnapshotGcsReadWriter샌드박스와 서비스 계정이 상주할 네임스페이스를 만듭니다.
kubectl create namespace "${SNAPSHOT_NAMESPACE}"방금 만든 네임스페이스에 Kubernetes 서비스 계정을 만듭니다. Kubernetes 서비스 계정과 네임스페이스는 함께 샌드박스에 Google Cloud 리소스에 대한 보안 액세스 권한을 부여하는 데 사용되는 고유 ID를 형성합니다.
kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \ --namespace "${SNAPSHOT_NAMESPACE}"네임스페이스의 모든 서비스 계정에
roles/storage.bucketViewer역할을 부여합니다. 이 역할을 사용하면 계정에서 버킷의 메타데이터를 볼 수 있지만 데이터 자체를 읽거나 쓸 수는 없습니다.gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \ --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/namespace/${SNAPSHOT_NAMESPACE}" \ --role="roles/storage.bucketViewer"샌드박스의 Kubernetes 서비스 계정에 맞춤
podSnapshotGcsReadWriter역할을 부여합니다. 이 바인딩을 사용하면 이 특정 계정만 관리 폴더에 데이터를 쓸 수 있습니다.gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \ --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${SNAPSHOT_NAMESPACE}/sa/${SNAPSHOT_KSA_NAME}" \ --role="projects/${PROJECT_ID}/roles/podSnapshotGcsReadWriter"Kubernetes 서비스 계정에
roles/storage.objectUser역할을 부여합니다. 이 역할은 Pod 스냅샷 에이전트가 관리 폴더에서 작업을 실행하는 데 필요합니다.gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \ --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${SNAPSHOT_NAMESPACE}/sa/${SNAPSHOT_KSA_NAME}" \ --role="roles/storage.objectUser"
스냅샷 컨트롤러에 권한 부여
GKE 시스템의 스냅샷 컨트롤러에
objectUser역할을 부여합니다. 이 권한을 사용하면PodSnapshot리소스를 삭제할 때 스냅샷 객체를 삭제하는 등 컨트롤러가 스냅샷 수명 주기를 관리할 수 있습니다.gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@container-engine-robot.iam.gserviceaccount.com" \ --role="roles/storage.objectUser"스냅샷 리소스 구성
이 섹션에서는 에이전트 샌드박스 워크로드의 스냅샷 리소스를 구성하는 방법을 보여줍니다.
스냅샷 스토리지 및 규칙 정의
GKE가 스냅샷을 저장하는 위치와 스냅샷 프로세스를 관리하는 규칙을 지정하려면 다음 두 가지 커스텀 리소스를 만듭니다.
PodSnapshotStorageConfig: 이 리소스는 GKE가 스냅샷 파일을 저장하는 Cloud Storage 버킷 및 폴더 위치를 지정합니다.PodSnapshotPolicy: 이 리소스는 Kubernetes 라벨을 기반으로 스냅샷을 사용할 수 있는 포드를 정의합니다. 또한 스냅샷이 수동인지 샌드박스 워크로드에 의해 시작되는지 등 트리거 규칙도 지정합니다.
한 단계로 두 리소스를 모두 적용하려면 Cloud Shell에서 다음 명령어를 실행하세요. 이 방법을 사용하면 환경 변수가 올바르게 삽입됩니다.
kubectl apply -f - <<EOF apiVersion: podsnapshot.gke.io/v1alpha1 kind: PodSnapshotStorageConfig metadata: name: cpu-pssc-gcs spec: snapshotStorageConfig: gcs: bucket: "${SNAPSHOTS_BUCKET_NAME}" path: "${SNAPSHOT_FOLDER}" EOF sleep 5 kubectl apply -f - <<EOF apiVersion: podsnapshot.gke.io/v1alpha1 kind: PodSnapshotPolicy metadata: name: cpu-psp namespace: ${SNAPSHOT_NAMESPACE} spec: storageConfigName: cpu-pssc-gcs selector: matchLabels: app: agent-sandbox-workload triggerConfig: type: manual postCheckpoint: resume EOF구성 확인
스냅샷 스토리지 구성 및 정책을 적용한 후 리소스를 사용할 준비가 되었는지 확인합니다. 이 섹션에서는 이러한 맞춤 리소스의 상태를 확인하는 방법을 보여줍니다.
PodSnapshotStorageConfig리소스의 상태를 확인합니다.kubectl get podsnapshotstorageconfigs.podsnapshot.gke.io cpu-pssc-gcs \ --namespace "${SNAPSHOT_NAMESPACE}" -o yaml출력에는
type: Ready및status: "True"이 포함된 조건이 포함되어야 합니다.status: conditions: - lastTransitionTime: "2025-10-31T18:18:02Z" message: Valid PodSnapshotStorageConfig reason: StorageConfigValid status: "True" type: ReadyPodSnapshotPolicy리소스의 상태를 확인합니다.kubectl get podsnapshotpolicies.podsnapshot.gke.io cpu-psp \ --namespace "${SNAPSHOT_NAMESPACE}" -o yaml출력에는
type: Ready및status: "True"이 포함된 조건이 포함되어야 합니다. 또한 참조된PodSnapshotStorageConfig을 찾았음을 나타내야 합니다.status: conditions: - lastTransitionTime: "2025-10-31T18:19:47Z" message: The referenced PodSnapshotStorageConfig "cpu-pssc-gcs" was found reason: StorageConfigValid status: "True" type: Ready
샌드박스 템플릿 만들기
이제 스토리지 정책과 권한이 설정되었으므로
SandboxTemplate및SandboxClaim리소스를 만듭니다. 스냅샷 프로세스가 작동하려면 샌드박스가 이 문서의 앞부분에서 만든 Kubernetes 서비스 계정으로 실행되어야 합니다. 샌드박스에는 이전에PodSnapshotPolicy에서 지정한 라벨도 있어야 합니다.이 예시에서는 증가하는 카운터를 로그에 출력하는 Python 앱을 사용합니다. 이 카운터를 사용하면 상태가 저장되고 나중에 복원되었는지 확인할 수 있습니다.
SandboxTemplate및SandboxClaim리소스를 만들려면 다음 매니페스트를 적용합니다.kubectl apply -f - <<EOF --- apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxTemplate metadata: name: python-runtime-template namespace: ${SNAPSHOT_NAMESPACE} spec: podTemplate: metadata: labels: app: agent-sandbox-workload spec: serviceAccountName: ${SNAPSHOT_KSA_NAME} runtimeClassName: gvisor containers: - name: my-container image: python:3.10-slim command: ["python3", "-c"] args: - | import time i = 0 while True: print(f"Count: {i}", flush=True) i += 1 time.sleep(1) --- apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxClaim metadata: name: python-sandbox-example namespace: ${SNAPSHOT_NAMESPACE} labels: app: agent-sandbox-workload spec: sandboxTemplateRef: name: python-runtime-template EOF이제 샌드박스가 올바른 ID로 실행되고 스냅샷을 찍을 준비가 되었습니다.
스냅샷 만들기
이 섹션에서는 실행 중인 샌드박스의 스냅샷을 수동으로 트리거하는 방법을 보여줍니다. 샌드박스 포드를 타겟팅하는 트리거 리소스를 만든 다음 스냅샷 프로세스가 성공적으로 완료되었는지 확인합니다.
초기 카운터 로그 확인: 스냅샷을 트리거하기 전에 실행 중인 샌드박스의 로그를 확인하여 현재 카운터 값을 확인합니다. 로그를 보면 복원 후 비교할 기준이 설정됩니다.
kubectl logs python-sandbox-example --namespace "${SNAPSHOT_NAMESPACE}" --tail=5출력에는 카운터의 마지막 몇 줄이 표시됩니다. 예를 들면 다음과 같습니다.
Count: 15 Count: 16 Count: 17출력된 마지막 몇 개의 'Count' 값을 확인합니다.
PodSnapshotManualTrigger 리소스 만들기: 스냅샷을 시작합니다.
kubectl apply -f - <<EOF apiVersion: podsnapshot.gke.io/v1alpha1 kind: PodSnapshotManualTrigger metadata: name: cpu-snapshot-trigger namespace: ${SNAPSHOT_NAMESPACE} spec: targetPod: python-sandbox-example EOF수동 트리거가 성공했는지 확인합니다.
kubectl get podsnapshotmanualtriggers.podsnapshot.gke.io \ --namespace "${SNAPSHOT_NAMESPACE}"출력에
Complete상태가 표시되어야 합니다. 이는 GKE가 타겟 Pod의 스냅샷을 성공적으로 트리거했음을 나타냅니다.NAME TARGET POD STATUS AGE cpu-snapshot-trigger python-sandbox-example Complete XXs트리거를 설명하여 캡처된 상태에 관한 세부정보를 자세히 확인합니다.
kubectl describe podsnapshotmanualtriggers.podsnapshot.gke.io cpu-snapshot-trigger \ --namespace "${SNAPSHOT_NAMESPACE}"출력에는 버킷에 저장된 스냅샷 파일의 고유한 이름이 포함된
Snapshot Created섹션이 포함됩니다.Status: Conditions: Last Transition Time: 2026-01-30T19:11:04Z Message: checkpoint completed successfully Reason: Complete Status: True Type: Triggered Observed Generation: 1 Snapshot Created: Name: <UNIQUE_SNAPSHOT_NAME>
스냅샷을 사용하여 복원
스냅샷을 캡처한 후 샌드박스 환경을 복원하여 저장된 상태에서 실행을 재개할 수 있습니다. 샌드박스를 복원하려면 원래
SandboxTemplate을 참조하는 새SandboxClaim을 만듭니다. 포드 스냅샷 컨트롤러는 가장 최근에 일치하는 스냅샷을 자동으로 식별하고 복원합니다.샌드박스를 복원할 새
SandboxClaim를 만듭니다.kubectl apply -f - <<EOF apiVersion: extensions.agents.x-k8s.io/v1alpha1 kind: SandboxClaim metadata: name: python-sandbox-from-snapshot namespace: ${SNAPSHOT_NAMESPACE} labels: app: agent-sandbox-workload spec: sandboxTemplateRef: name: python-runtime-template EOF로그를 확인하여 복원이 이루어졌는지 확인합니다. 카운터는 스냅샷이 촬영된 지점부터 계속됩니다.
kubectl logs python-sandbox-from-snapshot --namespace "${SNAPSHOT_NAMESPACE}"출력에는 카운터가 재개되는 것으로 표시됩니다. 예를 들면 다음과 같습니다.
Count: 18 Count: 19 Count: 20 Count: 21
삭제
이 문서에서 사용한 리소스의 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 단계에 따라 만든 리소스를 삭제하세요.
실행 중인 포드를 중지하고 에이전트 샌드박스 컨트롤러가 컨테이너를 단계적으로 종료할 수 있도록 샌드박스 클레임을 삭제합니다.
kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"샌드박스를 만들고 스냅샷을 시작하는 데 사용된 샌드박스 템플릿과 수동 트리거를 삭제합니다.
# Delete the blueprints kubectl delete sandboxtemplates --all --namespace "${SNAPSHOT_NAMESPACE}" # Delete the snapshot initiation objects kubectl delete podsnapshotmanualtriggers --all --namespace "${SNAPSHOT_NAMESPACE}"네임스페이스 내에서 스냅샷을 사용할 수 있는 포드를 정의하는 스냅샷 정책을 삭제합니다.
kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"스냅샷 스토리지 백엔드의 전역 정의인 스냅샷 스토리지 구성을 삭제합니다. 이 리소스는 클러스터 범위이므로 네임스페이스 플래그를 사용하지 마세요.
kubectl delete podsnapshotstorageconfig cpu-pssc-gcsKubernetes 네임스페이스를 삭제하여 Kubernetes 서비스 계정과 남아 있는 네임스페이스 메타데이터를 자동으로 삭제합니다.
kubectl delete namespace "${SNAPSHOT_NAMESPACE}"GKE 클러스터를 삭제하여 기본 인프라와 튜토리얼과 연결된 모든 노드를 삭제합니다.
gcloud container clusters delete "${CLUSTER_NAME}" --location="${GKE_LOCATION}" --quiet저장소를 완전히 재설정하려면 재귀 삭제 명령어를 사용하여 Cloud Storage 버킷을 삭제합니다 (선택사항). 올바르게 구성된 버킷을 향후 테스트에 재사용하려는 경우 이 단계를 건너뛸 수 있습니다.
gcloud storage rm --recursive "gs://${SNAPSHOTS_BUCKET_NAME:?Error: SNAPSHOTS_BUCKET_NAME is not set. Please re-define the environment variables you defined earlier.}"프로젝트를 완전히 정리된 상태로 되돌리려면 맞춤 IAM 역할을 삭제합니다 (선택사항). 클러스터가 삭제된 후에도 IAM 역할은 유지되므로 별도로 삭제해야 합니다.
gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"
다음 단계
- GKE 포드 스냅샷에 대해 자세히 알아보세요.
- GitHub에서 에이전트 샌드박스 오픈소스 프로젝트에 대해 자세히 알아보세요.
- 에이전트 샌드박스로 AI 코드 실행을 격리하는 방법을 알아보세요.