GKE의 에이전트 샌드박스로 AI 코드 실행 격리

이 문서에서는 Google Kubernetes Engine (GKE) 클러스터의 격리된 샌드박스에서 AI 생성 코드를 실행하는 방법을 보여줍니다. 클러스터에 샌드박스 템플릿과 준비된 샌드박스 풀을 만듭니다. 그런 다음 풀에서 샌드박스를 요청하고 샌드박스에서 명령어를 실행하는 Python 스크립트를 실행합니다. 이 스크립트는 샌드박스를 만들고 관리하는 라이브러리인 Agent Sandbox Python 클라이언트를 사용합니다.

샌드박스에서 신뢰할 수 없는 코드를 실행하면 AI 생성 코드의 잠재적인 취약점으로부터 시스템을 보호하고 개발 속도를 높이며 배포 보안을 개선할 수 있습니다. GKE의 Agent Sandbox가 신뢰할 수 없는 AI 생성 코드를 격리하는 방법에 대한 개요는 GKE의 Agent Sandbox 정보를 참조하세요.

비용

GKE의 Agent Sandbox는 추가 비용 없이 사용할 수 있는 오픈소스 소프트웨어입니다. 에이전트 샌드박스 컨트롤러에서 사용하는 컴퓨팅 리소스를 포함하여 사용자가 만드는 리소스에는 GKE 가격 책정이 적용됩니다.

시작하기 전에

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

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

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

    프로젝트 선택기로 이동

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

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

    API 사용 설정에 필요한 역할

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

    API 사용 설정하기

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

    Cloud Shell 활성화

  5. 이 문서를 완료하는 데 필요한 권한이 있는지 확인합니다.
  6. Agent Sandbox 컨트롤러가 설치되고 Sandbox 라우터가 배포된 GKE 클러스터가 있는지 확인합니다. 그렇지 않은 경우 GKE에 Agent Sandbox 설치의 다음 섹션만 완료한 후 이 문서로 돌아갑니다.
    1. 환경 변수 정의
    2. GKE 클러스터 만들기
    3. Agent Sandbox 설치
    4. 샌드박스 라우터 배포
    샌드박스 환경 배포와 같은 해당 문서의 다른 섹션을 완료할 필요는 없습니다. 이 문서의 뒷부분에서 자체 SandboxTemplate 및 SandboxWarmPool 리소스를 만듭니다.

필요한 역할

샌드박스를 만들고 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Kubernetes Engine 관리자 (roles/container.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

환경 변수 정의

이 문서에서 실행하는 명령어를 간소화하기 위해 Cloud Shell에서 환경 변수를 설정할 수 있습니다. Cloud Shell에서 다음 명령어를 실행하여 다음과 같은 유용한 환경 변수를 정의합니다.

export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"

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

  • CLUSTER_NAME: GKE 클러스터의 이름입니다(예: agent-sandbox-cluster).
  • LOCATION: GKE 클러스터가 있는 Google Cloud 리전 또는 영역입니다. Autopilot 클러스터를 사용하는 경우 리전으로 설정합니다 (예: us-central1). Standard 클러스터를 사용하는 경우 영역으로 설정합니다 (예: us-central1-a).

샌드박스 환경 배포

이 섹션에서는 샌드박스 청사진(SandboxTemplate 리소스)을 만들고, 네트워킹 라우터를 확인하고, 샌드박스와 상호작용하는 데 사용할 Python 클라이언트를 설치하는 방법을 보여줍니다.

샌드박스를 만들고 상호작용하는 권장 방법은 Agentic Sandbox Python 클라이언트를 사용하는 것입니다. 이 클라이언트는 생성부터 정리까지 샌드박스의 전체 수명 주기를 간소화하는 인터페이스를 제공합니다. 샌드박스를 프로그래매틱 방식으로 만들고, 사용하고, 삭제하는 데 사용할 수 있는 Python 라이브러리입니다.

클라이언트는 샌드박스 라우터를 모든 트래픽의 중앙 진입점으로 사용합니다. 이 문서에 설명된 예시에서 클라이언트는 kubectl port-forward 명령어를 사용하여 이 라우터에 대한 터널을 만들므로 공개 IP 주소를 노출할 필요가 없습니다. kubectl port-forward를 사용하는 것은 안전한 솔루션이 아니며 개발 환경으로 사용을 제한해야 합니다.

SandboxTemplate 및 SandboxWarmPool 리소스 만들기

이제 SandboxTemplate 리소스와 SandboxWarmPool 리소스를 만들어 샌드박스의 구성을 정의합니다. SandboxTemplate 리소스는 Agent Sandbox 컨트롤러가 일관되고 사전 구성된 샌드박스 환경을 만드는 데 사용하는 재사용 가능한 청사진 역할을 합니다. SandboxWarmPool 리소스는 지정된 수의 사전 준비된 포드가 항상 실행되고 사용 가능한 상태로 유지되도록 합니다. 사전 준비된 샌드박스는 이미 초기화된 실행 중인 포드입니다. 이 사전 초기화를 통해 1초 이내에 새 샌드박스를 만들 수 있으며 일반 샌드박스를 실행할 때 발생하는 시작 지연 시간을 방지할 수 있습니다.

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

    apiVersion: extensions.agents.x-k8s.io/v1beta1
    kind: SandboxTemplate
    metadata:
      name: python-sandbox-template
      namespace: default
    spec:
      podTemplate:
        metadata:
          labels:
            sandbox: python-sandbox-example
        spec:
          runtimeClassName: gvisor
          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: 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"
              limits:
                cpu: "500m"
                memory: "1Gi" # Required
            securityContext:
              capabilities:
                drop: ["ALL"] # Required
          restartPolicy: "OnFailure"
    ---
    apiVersion: extensions.agents.x-k8s.io/v1beta1
    kind: SandboxWarmPool
    metadata:
      name: python-sandbox-warmpool
      namespace: default
    spec:
      replicas: 2
      sandboxTemplateRef:
        name: python-sandbox-template
    
  2. SandboxTemplate 및 SandboxWarmPool 매니페스트를 적용합니다.

    kubectl apply -f sandbox-template-and-pool.yaml
    
  3. 웜 풀의 샌드박스가 준비될 때까지 기다립니다.

    kubectl wait sandboxwarmpool python-sandbox-warmpool \
        --for=jsonpath='{.status.readyReplicas}'=2 \
        --timeout=600s
    

    이 문서의 뒷부분에서 Python 클라이언트는 SandboxClaim 리소스를 만듭니다. 풀의 샌드박스가 준비되기 전에 클라이언트가 클레임을 만들면 컨트롤러는 풀에서 샌드박스를 할당하는 대신 클레임에 대한 새 샌드박스를 만들 수 있습니다. Autopilot 클러스터에서는 GKE가 샌드박스용 노드를 만들어야 할 수 있으므로 샌드박스가 준비되는 데 몇 분 정도 걸릴 수 있습니다.

샌드박스 라우터 확인

샌드박스 환경을 만들고 상호작용하는 데 사용할 Python 클라이언트는 샌드박스 라우터라는 구성요소를 사용하여 샌드박스와 통신합니다.

이 예시에서는 테스트를 위해 클라이언트의 개발자 모드를 사용합니다. 이 모드는 로컬 개발용이며 kubectl port-forward 명령어를 사용하여 로컬 머신에서 클러스터에서 실행 중인 샌드박스 라우터 서비스로 직접 터널을 설정합니다. 이 터널링 접근 방식은 공개 IP 주소나 복잡한 인그레스 설정이 필요하지 않으며 로컬 환경에서 샌드박스와의 상호작용을 간소화합니다.

샌드박스 라우터가 agent-sandbox-system 네임스페이스에서 실행 중인지 확인합니다.

kubectl get deployment sandbox-router --namespace=agent-sandbox-system

라우터가 실행 중이면 READY 열에 모든 복제본이 준비되었다고 표시됩니다(예: 2/2). 명령어가 NotFound 오류를 반환하면 샌드박스 라우터 배포의 단계에 따라 라우터를 배포합니다.

Python 클라이언트 설치

샌드박스 라우터와 같은 클러스터 내 구성요소가 배포되었으므로 마지막 준비 단계는 로컬 머신에 에이전트형 샌드박스 Python 클라이언트를 설치하는 것입니다. 이 클라이언트는 프로그래매틱 방식으로 샌드박스를 만들고, 사용하고, 삭제할 수 있는 Python 라이브러리입니다. 다음 섹션에서 환경을 테스트하는 데 사용합니다.

  1. Python 가상 환경을 만들고 활성화합니다.

    python3 -m venv .venv
    source .venv/bin/activate
    
  2. 클라이언트 패키지를 설치합니다. 에이전트 샌드박스 컨트롤러와 동일한 버전을 사용합니다.

    pip install k8s-agent-sandbox==1.0.6
    

샌드박스 테스트

모든 설정 구성요소가 준비되었으므로 이제 Agentic Sandbox Python 클라이언트를 사용하여 샌드박스를 만들고 상호작용할 수 있습니다.

  1. 다음 콘텐츠로 test_sandbox.py라는 Python 스크립트를 만듭니다.

    from k8s_agent_sandbox import SandboxClient
    from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig
    
    # Tunnels to svc/sandbox-router-svc in the agent-sandbox-system namespace.
    # cleanup=True deletes the sandbox when the script exits.
    client = SandboxClient(
        connection_config=SandboxLocalTunnelConnectionConfig(),
        cleanup=True,
    )
    
    sandbox = client.create_sandbox(warmpool="python-sandbox-warmpool", namespace="default")
    try:
        print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
    except Exception as e:
        print(f"An error occurred: {e}")
    
  2. 터미널에서 (가상 환경이 아직 활성 상태인 경우) 테스트 스크립트를 실행합니다.

    python3 test_sandbox.py
    

샌드박스에서 출력되는 'Hello from the sandboxed environment!' 메시지가 표시됩니다.

수고하셨습니다 보안 샌드박스 내에서 셸 명령어를 성공적으로 실행했습니다. sandbox.commands.run() 메서드를 사용하면 모든 셸 명령어를 실행할 수 있으며, GKE의 Agent Sandbox는 신뢰할 수 없는 코드로부터 클러스터의 노드와 기타 워크로드를 보호하는 안전한 장벽 내에서 명령어를 실행합니다. 이를 통해 AI 에이전트 또는 자동화된 워크플로가 작업을 실행할 수 있는 안전하고 안정적인 방법을 제공합니다.

스크립트를 실행하면 SandboxClient가 모든 단계를 처리합니다. SandboxClaim 리소스를 만들어 샌드박스를 시작하고 샌드박스가 준비될 때까지 기다린 다음 sandbox.commands.run() 메서드를 사용하여 보안 컨테이너 내에서 bash 셸 명령어를 실행합니다. 그런 다음 클라이언트는 해당 명령어에서 stdout를 캡처하고 출력합니다. 스크립트가 cleanup 매개변수를 True로 설정하므로 프로그램이 종료되면 클라이언트가 샌드박스를 삭제합니다.

SandboxClaim 리소스가 생성되면 웜 풀에서 사용 가능한 샌드박스가 클레임에 할당되고 클레임이 준비됨으로 표시됩니다. 그러면 SandboxWarmPool 리소스가 자동으로 보충되어 구성된 복제본 수를 유지합니다.

특정 샌드박스가 사용 중인지 또는 사용 가능한지 확인하려면 Sandbox 리소스의 메타데이터에서 ownerReferences를 확인합니다. kind 필드의 값이 SandboxClaim이면 샌드박스가 사용 중입니다. kind 필드 값이 SandboxWarmPool이면 샌드박스가 유휴 상태이며 사용되기를 기다리는 중입니다.

프로덕션에서 샌드박스 실행

이 문서에서는 Cloud Shell을 사용하여 클러스터 외부에서 샌드박스와 상호작용합니다. Python 클라이언트는 사용자 인증 정보를 사용하여 클러스터에 인증하고 샌드박스 리소스를 관리하며 kubectl port-forward 명령어를 사용하여 샌드박스와의 연결을 설정합니다. 이러한 단계는 개발 시나리오에 적합합니다.

프로덕션 시나리오에서 컨트롤러 애플리케이션 (예: AI 조정자)은 샌드박스 리소스를 만들고 관리합니다. 프로덕션에서 GKE의 Agent Sandbox를 사용하려면 다음을 고려하세요.

  • 인증: 컨트롤러 애플리케이션은 샌드박스를 실행하기 위해 클러스터 API 서버에 인증해야 합니다. 인증 구성 방법은 다음과 같이 컨트롤러 애플리케이션이 실행되는 위치에 따라 달라집니다.

    • 컨트롤러 애플리케이션이 동일한 클러스터에서 포드로 실행되는 경우 Kubernetes RBAC 또는 GKE용 워크로드 아이덴티티 제휴를 IAM 정책과 함께 사용하여 포드의 Kubernetes ServiceAccount에 샌드박스를 감시하거나 네트워크 엔드포인트를 검색하는 데 필요한 권한을 부여합니다.
    • 컨트롤러 애플리케이션이 클러스터 외부에서 실행되는 경우 워크로드 아이덴티티 제휴 또는 IAM 서비스 계정을 사용하여 허용 정책에서 참조할 수 있는 ID를 애플리케이션에 부여합니다.
  • 라우팅: 컨트롤러 애플리케이션의 Python 클라이언트에서 전송된 요청이 클러스터의 샌드박스 라우터에 도달해야 합니다. 프로덕션에서는 다음 방법 중 하나를 사용하여 네트워크 연결을 설정합니다.

    • 컨트롤러 애플리케이션이 동일한 클러스터에서 실행되는 경우 SandboxDirectConnectionConfig 함수를 사용하여 샌드박스 라우터 서비스에서 사용하는 URL 및 포트를 타겟팅합니다.
    • 컨트롤러 애플리케이션이 클러스터 외부에서 실행되는 경우 GKE 게이트웨이 API를 사용하여 내부 또는 외부 부하 분산기를 만듭니다. 클라이언트 코드에서 SandboxGatewayConnectionConfig 함수를 사용하여 게이트웨이를 참조합니다.

    이러한 라우팅 방법에 대한 자세한 내용은 GitHub의 사용 예시 및 라우터의 게이트웨이 배포 단계를 참조하세요.

  • Google Cloud 리소스에 대한 샌드박스 액세스: 샌드박스 코드가 Cloud Storage와 같은 Google Cloud API에 요청을 전송해야 하는 경우 GKE용 워크로드 아이덴티티 제휴와 함께 IAM 정책을 사용하여 샌드박스 포드가 사용하는 Kubernetes ServiceAccount에 해당 액세스에 필요한 권한을 부여합니다. 기본 네트워크 정책은 Google Cloud 메타데이터 서버(169.254.169.254)에 대한 액세스를 차단하므로 이 트래픽을 허용하도록 네트워크 정책을 맞춤설정해야 합니다.

  • 네트워크 정책 제한사항: 기본적으로 GKE의 Agent Sandbox는 엄격한 보안 강화를 기본으로 설정한 네트워크 상태(networkPolicyManagement: Managed)를 적용합니다. 이 상태에서는 다음 제한사항이 적용됩니다.

    • 지정된 샌드박스 라우터(agent-sandbox-system 네임스페이스에 app: sandbox-router 라벨이 있는 포드)를 제외한 모든 소스에서 인그레스가 차단됩니다.
    • 이그레스는 공개 인터넷에 허용되지만 비공개 LAN 범위 (RFC 1918), 내부 클러스터 DNS (CoreDNS), 클라우드 제공업체 메타데이터 서버 (169.254.0.0/16)에 대한 이그레스는 명시적으로 차단됩니다.

    GKE용 워크로드 아이덴티티 제휴를 사용하거나 다른 비공개 리소스에 액세스하려면 SandboxTemplate 리소스에서 커스텀 네트워크 정책을 정의해야 합니다. 자세한 구성 세부정보와 맞춤설정 가능한 템플릿 (예: 에어 갭 샌드박스 또는 GKE용 워크로드 아이덴티티 제휴 통합)은 Agent Sandbox 네트워크 정책 관리를 참조하세요.

샌드박스 보안 정책

기본적으로 GKE의 Agent Sandbox는 샌드박스에 보안 정책을 적용하지 않습니다. 샌드박스의 격리 설정을 적용하려면 Agent Sandbox GitHub 저장소에서 권장되는 secure-sandbox-policy Kubernetes 검증 허용 정책 (VAP)을 적용하세요. 자세한 내용은 권장 보안 정책 적용을 참조하세요.

이 정책은 gVisor 요구, hostNetwork 사용 중지, hostPath 볼륨 차단과 같은 격리 요구사항을 적용합니다. 또한 이 정책은 모든 기능 삭제, 새 기능 추가 방지, 컨테이너가 루트가 아닌 사용자로 실행되고 리소스 한도를 설정하도록 요구하는 등의 강화 요구사항을 적용합니다. 전체 요구사항 목록은 GKE의 Agent Sandbox 배포 요구사항을 참조하세요.

정책 제약조건 수정 또는 삭제

정책을 직접 적용하므로 워크로드에 맞게 변경할 수 있습니다. 워크로드에 일부 규칙의 예외가 필요한 경우 정책을 수정하여 특정 제약조건을 삭제하거나 정책 바인딩을 완전히 삭제할 수 있습니다. 제약조건을 삭제하면 정책에서 제공하는 격리가 줄어들므로 워크로드에 필요한 제약조건만 삭제하세요.

정책을 수정하고 특정 제약조건을 삭제하려면 (예: 컨테이너가 루트로 실행되도록 허용하거나 리소스 한도를 생략) ValidatingAdmissionPolicy 리소스를 수정합니다.

kubectl edit validatingadmissionpolicy secure-sandbox-policy

열린 텍스트 편집기에서 validations 섹션을 찾아 워크로드를 차단하는 제약조건 표현식을 삭제하거나 수정합니다.

또는 클러스터에서 정책 적용을 중지하려면 정책 바인딩을 삭제합니다.

kubectl delete validatingadmissionpolicybinding secure-sandbox-binding

알려진 문제

이 섹션에서는 GKE에서 Agent Sandbox를 사용할 때 발생하는 알려진 문제와 이를 해결하거나 우회하는 방법을 설명합니다.

서비스 메시를 사용할 때 보안 정책이 기능을 차단함

권장 보안 정책을 적용하고 서비스 메시 사이드카(예: Envoy 또는 Istio)와 통합되는 샌드박스를 배포하려고 하면 다음과 같은 오류와 함께 정책에 의해 샌드박스 생성이 차단될 수 있습니다.

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'secure-sandbox-policy' with binding 'secure-sandbox-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.
  • 원인: 서비스 메시 사이드카는 istio-init 또는 proxy-init와 같은 초기화 컨테이너를 사용하는 경우가 많습니다. 이러한 init 컨테이너에는 투명한 이그레스 라우팅을 위해 iptables 규칙을 구성하는 NET_ADMIN 또는 NET_RAW와 같은 기능이 필요합니다. secure-sandbox-policy ValidatingAdmissionPolicy는 모든 컨테이너 유형에서 모든 기능 추가를 차단합니다.
  • 해결 방법: 클러스터에서 이 정책을 관리하므로 ValidatingAdmissionPolicy를 수정하여 특정 신뢰할 수 있는 초기화 컨테이너가 NET_ADMIN 및 NET_RAW 기능을 요청하도록 허용할 수 있습니다. 정책 제약조건을 수정하거나 삭제하는 방법에 대한 안내는 정책 제약조건 수정 또는 삭제를 참조하세요. 예를 들어 정책의 검증 표현식 또는 변수를 업데이트하여 신뢰할 수 있는 컨테이너 이름을 기능 규칙에서 제외할 수 있습니다.

IPv6를 통해 Google API에 연결할 때 이그레스 지연 시간 또는 제한 시간

샌드박스 내의 워크로드가 외부 리소스 또는 Google API (예: Vertex AI 또는 Cloud Storage)에 연결하려고 할 때 연결 시간 초과 또는 최대 2분의 높은 지연 시간이 발생할 수 있습니다.

  • 원인: GKE 클러스터에 이중 스택 IPv6가 사용 설정된 경우 Google API의 DNS 변환은 IPv4 (A) 및 IPv6 (AAAA) 주소를 모두 반환합니다. Node.js와 같은 런타임 엔진의 일부 알고리즘은 IPv6를 통해 먼저 연결을 시도합니다. GKE VPC에 IPv6용 Cloud NAT 또는 인터넷 게이트웨이와 같은 유효한 IPv6 이그레스 경로가 없으면 TCP SYN 제한 시간이 만료될 때까지 TCP 연결이 응답을 중지합니다. 그러면 TCP 연결이 IPv4로 대체됩니다.
  • 해결 방법: 이 문제를 해결하려면 다음 중 한 가지를 따르세요.

    • IPv6 이그레스 구성: 아웃바운드 IPv6 트래픽이 클러스터로 돌아갈 수 있도록 VPC 네트워크에서 유효한 IPv6 Cloud NAT 또는 인터넷 게이트웨이를 구성합니다.
    • 워크로드에서 IPv4 선호: IPv4 DNS 변환을 선호하려면 워크로드의 런타임을 구성합니다. 예를 들어 Node.js 애플리케이션에서 SandboxTemplate 정의에 다음 환경 변수를 설정할 수 있습니다.

      env:
      - name: NODE_OPTIONS
        value: "--dns-result-order=ipv4first --no-network-family-autoselection"
      

리소스 삭제

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

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

다음 단계