Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Autopilot Standard

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

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

비용

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

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

시작하기 전에

Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
프로젝트를 선택하거나 만드는 데 필요한 역할
- 프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
- 프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기
참고: 이 절차에서 생성한 리소스를 유지하지 않으려면 기존 프로젝트를 선택하지 말고 프로젝트를 새로 만드세요. 작업이 끝나면 프로젝트를 삭제하여 프로젝트와 관련된 모든 리소스를 삭제할 수 있습니다.

프로젝트 선택기로 이동
Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.
Artifact Registry, Google Kubernetes Engine API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기
API 사용 설정

Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

Cloud Shell 활성화
클러스터가 GKE 버전 1.35.2-gke.1269000 이상을 실행하는지 확인합니다.

환경 변수 정의

이 문서에서 실행하는 명령어를 간소화하려면 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.35.2-gke.1269000"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"

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

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

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

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

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

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

Autopilot

에이전트 샌드박스가 사용 설정된 새 GKE Autopilot 클러스터를 만들려면 --enable-agent-sandbox 플래그를 포함하세요.

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

Autopilot 클러스터의 경우 LOCATION 환경 변수가 리전 (예: us-central1)으로 설정되어 있는지 확인합니다.

표준

에이전트 샌드박스가 사용 설정된 새 GKE Standard 클러스터를 만들려면 클러스터를 만들고, gVisor가 사용 설정된 노드 풀을 추가한 후 에이전트 샌드박스 기능을 사용 설정해야 합니다. 비용을 절약하려면 풀당 노드가 하나인 영역 클러스터를 만드는 것이 좋습니다.

클러스터를 만듭니다.

gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --cluster-version=${CLUSTER_VERSION}

이 표준 클러스터의 경우 LOCATION 환경 변수가 영역 (예: us-central1-a)으로 설정되어 있는지 확인합니다.

gVisor가 사용 설정된 별도의 노드 풀을 만듭니다.

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

LOCATION는 클러스터를 만들 때 사용한 영역과 동일해야 합니다.

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

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

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

기존 클러스터에서 에이전트 Sandbox를 사용 설정하려면 클러스터가 버전 1.35.2-gke.1269000 이상을 실행해야 합니다.

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

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

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

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을 만들어 샌드박스 환경을 배포하려면 다음 단계를 완료하세요.

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

apiVersion: extensions.agents.x-k8s.io/v1alpha1
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

SandboxTemplate 매니페스트를 적용합니다.
```
kubectl apply -f sandbox-template.yaml
```

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

apiVersion: extensions.agents.x-k8s.io/v1alpha1
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

SandboxWarmPool 매니페스트를 적용합니다.
```
kubectl apply -f sandbox-warmpool.yaml
```

SandboxClaim 만들기

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

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

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

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

SandboxClaim 매니페스트를 적용합니다.
```
kubectl apply -f sandbox-claim.yaml
```
샌드박스, 클레임, 웜 풀이 준비되었는지 확인합니다.
```
kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
```

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

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

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

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

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: Always
      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

Sandbox 매니페스트를 적용합니다.
```
kubectl apply -f sandbox.yaml
```
샌드박스가 실행 중인지 확인합니다.
```
kubectl get sandbox
```

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

에이전트 샌드박스 기능을 사용 중지하려면 --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)입니다.

리소스 삭제

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

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

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

다음 단계

포드 스냅샷으로 에이전트 샌드박스 환경을 저장하고 복원하는 방법을 알아봅니다.
에이전트 샌드박스에서 사용하는 기본 기술에 대해 알아봅니다.
GKE 보안 자세히 알아보기
GitHub에서 Agent Sandbox 오픈소스 프로젝트를 살펴봅니다.

GKE에서 에이전트 샌드박스 사용 설정 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

비용

시작하기 전에

환경 변수 정의

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

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

Autopilot

표준

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

구성 확인

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

필수 구성

금지된 구성

샌드박스 환경 배포

권장사항: SandboxTemplate 및 SandboxWarmPool 만들기

SandboxClaim 만들기

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

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

리소스 삭제

다음 단계

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