GKE에서 에이전트 샌드박스 사용 설정

이 문서에서는 Google Kubernetes Engine (GKE) 클러스터에서 에이전트 샌드박스 기능을 사용 설정하는 방법을 설명합니다. 또한 신뢰할 수 없는 코드를 안전하게 실행하기 위해 클러스터에 샌드박스 환경을 만드는 방법을 설명합니다.

에이전트 샌드박스 기능이 신뢰할 수 없는 AI 생성 코드를 격리하는 방법에 대한 개요는 GKE 에이전트 샌드박스 정보를 참고하세요.

비용

에이전트 샌드박스는 GKE에서 추가 비용 없이 제공됩니다. 생성한 리소스에는 GKE 가격 책정이 적용됩니다.

불필요한 요금이 청구되지 않도록 이 문서를 완료한 후 GKE를 중지하거나 프로젝트를 삭제하세요.

시작하기 전에

1. Cloud de Confiance 콘솔의 프로젝트 선택기 페이지에서 Cloud de Confiance 프로젝트를 선택하거나 만듭니다.

   프로젝트를 선택하거나 만드는 데 필요한 역할

   • 프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
   • 프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

   프로젝트 선택기로 이동

2. Cloud de Confiance 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

3. Artifact Registry, Google Kubernetes Engine API가 아직 사용 설정되지 않은 경우 사용 설정합니다.

   API 사용 설정에 필요한 역할

   API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

   API 사용 설정

4. Cloud de Confiance 콘솔에서 Cloud Shell을 활성화합니다.

   Cloud Shell 활성화

5. 클러스터가 GKE 버전 1.36.3-gke.1767000 이상 (v1beta1 API 지원)을 실행하는지 확인합니다.

환경 변수 정의

이 문서에서 실행하는 명령어를 간소화하려면 Cloud Shell에서 환경 변수를 설정하면 됩니다. Cloud Shell에서 다음 명령어를 실행하여 유용한 환경 변수를 정의합니다.

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export CLUSTER_VERSION="1.36.3-gke.1767000"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"

다음은 이러한 환경 변수에 대한 설명입니다.

• PROJECT_ID: 현재 Cloud de Confiance by S3NS 프로젝트의 ID입니다. 이 변수를 정의하면 GKE 클러스터와 같은 모든 리소스가 올바른 프로젝트에 생성됩니다.
• CLUSTER_NAME: GKE 클러스터의 이름(예: agent-sandbox-cluster)
• LOCATION: GKE 클러스터가 생성된 Cloud de Confiance by S3NS 리전 또는 영역입니다. Autopilot 클러스터를 만드는 경우 리전 (예: us-central1)으로 설정하고 Standard 클러스터를 만드는 경우 영역 (예: us-central1-a)으로 설정합니다.
• CLUSTER_VERSION: 클러스터가 실행될 GKE 버전입니다 (1.36.3-gke.1767000 이상).
• NODE_POOL_NAME: 샌드박스 처리된 워크로드를 실행할 노드 풀의 이름입니다(예: agent-sandbox-pool). 이 변수는 GKE Standard 클러스터를 만드는 경우에만 필요합니다.
• MACHINE_TYPE: 노드 풀에 있는 노드의 머신 유형입니다(예: e2-standard-2). 다양한 머신 시리즈 및 옵션 선택에 대한 자세한 내용은 머신 계열 리소스 및 비교 가이드를 참고하세요. 이 변수는 GKE Standard 클러스터를 만드는 경우에만 필요합니다.

에이전트 샌드박스 사용 설정

새 클러스터를 만들거나 기존 클러스터를 업데이트할 때 에이전트 샌드박스 기능을 사용 설정할 수 있습니다.

새 GKE 클러스터를 만들 때 에이전트 샌드박스 사용 설정

완전 관리형 Kubernetes 환경을 위해서는 Autopilot 클러스터를 사용하는 것이 좋습니다. 워크로드에 가장 적합한 GKE 작업 모드를 선택하려면 GKE 작업 모드 선택을 참고하세요.

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --cluster-version=${CLUSTER_VERSION} \
    --enable-agent-sandbox

기존 GKE 클러스터를 업데이트할 때 에이전트 샌드박스 사용 설정

기존 클러스터에서 에이전트 샌드박스를 사용 설정하려면 클러스터가 v1beta1 API를 지원하는 버전 1.36.3-gke.1767000 이상을 실행해야 합니다.

LOCATION 환경 변수가 기존 클러스터가 있는 리전 또는 영역으로 설정되어 있는지 확인합니다.

1. GKE Standard 클러스터를 사용하는 경우 에이전트 샌드박스는 gVisor를 사용합니다. 표준 클러스터에 gVisor 지원 노드 풀이 없는 경우 먼저 하나를 만들어야 합니다.

   gcloud container node-pools create ${NODE_POOL_NAME} \
       --cluster=${CLUSTER_NAME} \
       --machine-type=${MACHINE_TYPE} \
       --location=${LOCATION} \
       --image-type=cos_containerd \
       --sandbox=type=gvisor
   

2. 에이전트 샌드박스 기능을 사용 설정하도록 클러스터를 업데이트합니다.

   gcloud beta container clusters update ${CLUSTER_NAME} \
       --location=${LOCATION} \
       --enable-agent-sandbox
   

구성 확인

클러스터 설명을 검사하여 에이전트 샌드박스 기능이 사용 설정되어 있는지 확인할 수 있습니다.

gcloud beta container clusters describe ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --format="value(addonsConfig.agentSandboxConfig.enabled)"

Autopilot 클러스터를 만든 경우 위치는 리전 (예: us-central1)입니다. Standard 클러스터를 만든 경우 위치는 영역 (예: us-central1-a)입니다.

기능이 사용 설정되면 명령어가 True를 반환합니다.

에이전트 샌드박스 배포 요구사항

Sandbox 또는 SandboxTemplate과 같은 워크로드를 성공적으로 배포하려면 YAML 매니페스트에 특정 보안 및 구성 설정이 포함되어야 합니다. GKE는 유효성 검사 승인 정책 (VAP)을 사용하여 이러한 요구사항을 적용합니다. 이러한 요구사항이 충족되지 않으면 승인 컨트롤러가 배포를 거부합니다.

필수 구성

배포 매니페스트에는 다음 설정이 포함되어야 합니다.

• runtimeClassName: gvisor: 포드가 gVisor 샌드박스에서 실행되도록 합니다.
• automountServiceAccountToken: false: 포드가 기본 서비스 계정 토큰을 자동으로 마운트하지 못하도록 합니다.
• securityContext.runAsNonRoot: true: 컨테이너가 루트 사용자로 실행되지 않도록 합니다.
• securityContext.capabilities.drop: ["ALL"]: 컨테이너에서 모든 Linux 기능을 삭제합니다.
• resources.limits: 서비스 거부 (DoS) 시나리오를 방지하기 위해 CPU 및 메모리 한도를 지정해야 합니다.
• nodeSelector: sandbox.gke.io/runtime: gvisor을 타겟팅해야 합니다.
• tolerations: sandbox.gke.io/runtime=gvisor:NoSchedule taint에 대한 톨러레이션을 포함해야 합니다.

금지된 구성

배포 매니페스트에 다음이 포함되어서는 안 됩니다.

• hostNetwork: true, hostPID: true 또는 hostIPC: true
• privileged: true 컨테이너 보안 컨텍스트에서
• HostPath 볼륨
• 기능이 추가되었습니다 (capabilities.add).
• hostPort 설정입니다.
• 맞춤 sysctl
• 서비스 계정 토큰 또는 인증서의 예상 볼륨입니다.

샌드박스 환경 배포

SandboxTemplate을 정의하고 SandboxWarmPool을 사용하여 사전 워밍된 인스턴스를 준비 상태로 유지하여 샌드박스 환경을 배포하는 것이 좋습니다. 그런 다음 SandboxClaim을 사용하여 이 준비된 노드 풀에서 인스턴스를 요청할 수 있습니다. 또는 샌드박스를 직접 만들 수도 있지만 이 방법은 웜 풀을 지원하지 않습니다.

SandboxTemplate, SandboxWarmPool, SandboxClaim, Sandbox는 Kubernetes 커스텀 리소스입니다.

권장사항: SandboxTemplate 및 SandboxWarmPool 만들기

SandboxTemplate은 재사용 가능한 청사진 역할을 합니다. SandboxWarmPool은 지정된 수의 사전 예열된 포드가 항상 실행되고 클레임할 준비가 되도록 지원합니다. 이 맞춤 리소스를 사용하면 시작 지연 시간이 최소화됩니다.

SandboxTemplate 및 SandboxWarmPool을 만들어 샌드박스 환경을 배포하려면 다음 단계를 완료하세요.

1. Cloud Shell에서 다음 콘텐츠가 포함된 sandbox-template.yaml 파일을 만듭니다.

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxTemplate
   metadata:
     name: python-runtime-template
     namespace: default
   spec:
     podTemplate:
       metadata:
         labels:
           sandbox-type: python-runtime
       spec:
         runtimeClassName: gvisor # Required
         automountServiceAccountToken: false # Required
         securityContext:
           runAsNonRoot: true # Required
         nodeSelector:
           sandbox.gke.io/runtime: gvisor # Required
         tolerations:
         - key: "sandbox.gke.io/runtime"
           value: "gvisor"
           effect: "NoSchedule" # Required
         containers:
         - name: runtime
           image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
           ports:
           - containerPort: 8888
           resources:
             requests:
               cpu: "250m"
               memory: "512Mi"
             limits:
               cpu: "500m"
               memory: "1Gi" # Required
           securityContext:
             capabilities:
               drop: ["ALL"] # Required
         restartPolicy: OnFailure
   

2. SandboxTemplate 매니페스트를 적용합니다.

   kubectl apply -f sandbox-template.yaml
   

3. 다음 콘텐츠로 sandbox-warmpool.yaml이라는 파일을 만듭니다.

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxWarmPool
   metadata:
     name: python-runtime-warmpool
     namespace: default
     labels:
       app: python-runtime-warmpool
   spec:
     replicas: 2
     sandboxTemplateRef:
       # This must match the name of the SandboxTemplate.
       name: python-runtime-template
   

4. SandboxWarmPool 매니페스트를 적용합니다.

   kubectl apply -f sandbox-warmpool.yaml
   

SandboxClaim 만들기

SandboxClaim은 웜 풀에서 샌드박스를 요청합니다. 웜 풀을 만들었으므로 생성된 샌드박스는 새 포드를 시작하는 대신 풀에서 실행 중인 포드를 채택합니다.

SandboxClaim를 만들어 워밍 풀에서 샌드박스를 요청하려면 다음 단계를 완료하세요.

1. 다음 콘텐츠로 sandbox-claim.yaml이라는 파일을 만듭니다.

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxClaim
   metadata:
     name: sandbox-claim
     namespace: default
   spec:
     warmPoolRef:
       # This must match the name of the SandboxWarmPool.
       name: python-runtime-warmpool
   

2. SandboxClaim 매니페스트를 적용합니다.

   kubectl apply -f sandbox-claim.yaml
   

3. 샌드박스, 클레임, 웜 풀이 준비되었는지 확인합니다.

   kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
   

대안: 샌드박스를 직접 만들기

웜 풀에서 제공하는 빠른 시작 시간이 필요하지 않은 경우 템플릿을 사용하지 않고 샌드박스를 직접 배포할 수 있습니다.

샌드박스를 직접 만들어 샌드박스 환경을 배포하려면 다음 단계를 완료하세요.

1. 다음 콘텐츠로 sandbox.yaml이라는 파일을 만듭니다.

   apiVersion: agents.x-k8s.io/v1beta1
   kind: Sandbox
   metadata:
     name: sandbox-example-2
   spec:
     replicas: 1
     podTemplate:
       metadata:
         labels:
           sandbox: sandbox-example
       spec:
         runtimeClassName: gvisor
         restartPolicy: OnFailure
         automountServiceAccountToken: false # Required
         securityContext:
           runAsNonRoot: true # Required
           runAsUser: 1000 # Required if image defaults to root (e.g. busybox)
         nodeSelector:
           sandbox.gke.io/runtime: gvisor
         tolerations:
         - key: "sandbox.gke.io/runtime"
           value: "gvisor"
           effect: "NoSchedule" # Required
         containers:
         - name: my-container
           image: busybox
           command: ["/bin/sh", "-c"]
           args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"]
           securityContext:
             capabilities:
               drop: ["ALL"] # Required
             allowPrivilegeEscalation: false
           resources:
             limits:
               cpu: "100m"
               memory: "128Mi" # Required
   

2. Sandbox 매니페스트를 적용합니다.

   kubectl apply -f sandbox.yaml
   

3. 샌드박스가 실행 중인지 확인합니다.

   kubectl get sandbox
   

v1alpha1에서 v1beta1로 에이전트 샌드박스 마이그레이션

v1alpha1 커스텀 리소스를 사용하여 이전 버전의 에이전트 샌드박스로 클러스터를 배포한 경우 워크로드 다운타임이 거의 없는 GKE 버전 1.36.3-gke.1767000 이상으로 업그레이드할 수 있습니다.

참고: 이 이전 절차는 관리형 GKE 에이전트 샌드박스 기능 (--enable-agent-sandbox)을 사용하는 클러스터에 적용됩니다. 오픈소스 매니페스트를 사용하여 에이전트 샌드박스를 배포한 경우 업스트림 이전 가이드를 참고하세요.

v1alpha1와 v1beta1 간의 주요 API 차이점

마이그레이션 도구를 사용하여 마이그레이션

섀도우 워밍 풀을 자동으로 만들고 스토리지를 다시 유지하려면 에이전트 샌드박스 저장소의 표준 마이그레이션 스크립트를 사용하세요.

스크립트를 다운로드하고 준비합니다.

curl -LO https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.6/helm/files/migrate.sh
chmod +x migrate.sh

단계별 이전 런북

워크로드 다운타임이 거의 없는 기존 클러스터를 마이그레이션하려면 다음 세 단계를 순서대로 완료하세요.

1단계: 업그레이드 전 부트스트랩 단계

1. 기존 리소스 백업: 선언적 에이전트 샌드박스 리소스 (sandboxtemplates, sandboxwarmpools, sandboxclaims)의 YAML 백업을 저장합니다.

   kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims \
       --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yaml
   

2. 템플릿 보안 규정 준수 확인: 기존 SandboxTemplate 리소스가 에이전트 샌드박스 배포 요구사항을 충족하는지 확인합니다. 3단계의 스토리지 마이그레이션 중에 허용 컨트롤러는 이러한 보안 정책을 준수하지 않는 템플릿의 업데이트를 거부합니다.

3. 생성될 섀도우 풀을 미리 봅니다.

   ./migrate.sh --phase=bootstrap --dry-run
   

4. 부트스트랩 단계를 실행합니다.

   ./migrate.sh --phase=bootstrap
   

5. 생성된 섀도우 풀을 확인합니다.

   kubectl get sandboxwarmpools --all-namespaces \
       -o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,REPLICAS:.spec.replicas,SHADOW:.metadata.annotations.agents\.x-k8s\.io/migration-shadow"
   

2단계: GKE 컨트롤 플레인 업그레이드

GKE 컨트롤 플레인을 버전 1.36.3-gke.1767000 이상으로 업그레이드합니다.

gcloud container clusters upgrade ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --master \
    --cluster-version=1.36.3-gke.1767000

컨트롤 플레인 출시 중에 다음 사항에 유의하세요.

• 포드에 다시 시작 또는 다운타임이 발생하지 않습니다.
• 새 컨트롤러와 /convert 웹훅 엔드포인트가 컨트롤 플레인에 배포됩니다.

3단계: 업그레이드 후 스토리지 마이그레이션

컨트롤 플레인 업그레이드가 완료되면 사용자 인증 정보를 새로고침하고 저장된 etcd 객체를 다시 작성하여 스토리지 마이그레이션 단계를 실행합니다.

./migrate.sh --phase=migrate

마이그레이션 후 확인 체크리스트

마이그레이션 단계가 완료된 후에도 CustomResourceDefinition에 .status.storedVersions의 ["v1alpha1", "v1beta1"]이 계속 나열되면 이는 예상되는 Kubernetes 동작입니다. 이전 스크립트는 etcd에서 모든 기존 레코드를 v1beta1로 다시 작성하지만 Kubernetes는 status.storedVersions 목록에서 지원 중단된 버전을 자동으로 삭제하지 않습니다.

모든 리소스가 이전되었는지 확인한 후 저장된 버전에서 v1alpha1를 선택적으로 삭제할 수 있습니다.

for crd in \
    sandboxes.agents.x-k8s.io \
    sandboxclaims.extensions.agents.x-k8s.io \
    sandboxtemplates.extensions.agents.x-k8s.io \
    sandboxwarmpools.extensions.agents.x-k8s.io; do
  kubectl patch crd "${crd}" --subresource=status --type=merge \
    -p '{"status":{"storedVersions":["v1beta1"]}}'
done

이전 문제 해결하기

컨트롤 플레인을 업그레이드하거나 스토리지 이전을 실행한 후 문제가 발생하면 컨트롤 플레인을 다운그레이드하려고 하지 말고 문제를 해결하세요.

• WarmPoolNotFound에서 신고가 멈춤:

  • ./migrate.sh --phase=bootstrap를 실행하지 않고 콜드 스타트 v1alpha1 클레임이 업그레이드된 경우 누락된 섀도우 웜 풀을 수동으로 만드세요.

    apiVersion: extensions.agents.x-k8s.io/v1beta1
    kind: SandboxWarmPool
    metadata:
      name: shadow-pool-TEMPLATE_NAME
      namespace: NAMESPACE
      annotations:
        agents.x-k8s.io/migration-shadow: "true"
    spec:
      replicas: 0
      sandboxTemplateRef:
        name: TEMPLATE_NAME
    

  • 더 이상 존재하지 않는 특정 웜 풀을 지정하는 클레임이 있는 경우 해당 이름으로 누락된 SandboxWarmPool 리소스를 만들거나 클레임의 spec.warmPoolRef.name을 업데이트하여 기존 웜 풀을 참조하세요.

• 클레임 조건 Ready=False: kubectl describe sandboxclaim을 실행하여 클레임의 이벤트를 검사합니다. 참조된 SandboxTemplate이 모든 에이전트 샌드박스 배포 요구사항을 충족하는지 확인하고 필요한 경우 템플릿을 다시 적용합니다.

• 변환 또는 컨트롤러 오류: kubectl get leases -n gke-managed-agentsandbox를 실행하여 컨트롤 플레인 리더 선출 리스가 활성 상태인지 확인합니다. 문제가 계속되면 Cloud Customer Care에 문의하세요.

에이전트 샌드박스 사용 중지

에이전트 샌드박스 기능을 사용 중지하려면 --no-enable-agent-sandbox 플래그와 함께 gcloud beta container clusters update 명령어를 사용합니다.

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --no-enable-agent-sandbox

Autopilot 클러스터를 만든 경우 위치는 리전 (예: us-central1)입니다. Standard 클러스터를 만든 경우 위치는 영역 (예: us-central1-a)입니다.

리소스 삭제

Cloud de Confiance by S3NS 계정에 요금이 청구되지 않도록 하려면 생성한 GKE 클러스터를 삭제합니다.

gcloud container clusters delete $CLUSTER_NAME \
    --location=${LOCATION} \
    --quiet

Autopilot 클러스터를 만든 경우 위치는 리전 (예: us-central1)입니다. Standard 클러스터를 만든 경우 위치는 영역 (예: us-central1-a)입니다.

다음 단계

• 포드 스냅샷으로 에이전트 샌드박스 환경을 저장하고 복원하는 방법을 알아봅니다.
• 에이전트 샌드박스에서 사용하는 기본 기술에 대해 알아봅니다.
• GKE 보안 자세히 알아보기
• GitHub에서 Agent Sandbox 오픈소스 프로젝트를 살펴봅니다.
• 오픈소스 Kata Containers와 Agent Sandbox를 사용하는 방법을 알아보세요. Kata Containers는 Cloud de Confiance 제품이 아닙니다. 이 소프트웨어를 설치하고 사용하는 경우 관리 및 문제 해결은 사용자의 책임입니다. Google의 지원 및 SLA는 Kata Containers에 적용되지 않습니다.