GKE 에이전트 서브스트레이트와 함께 Filestore 에이전트 볼륨 사용

Google Kubernetes Engine(GKE) Agent Substrate는 스테이트풀(Stateful) AI 에이전트 샌드박스의 수명 주기를 관리하는 인프라 플랫폼입니다. Agent Substrate를 사용하면 플랫폼에서 유휴 에이전트 워크로드를 정지하여 컴퓨팅 비용을 절감하고 새 프롬프트나 작업이 도착하면 1초 이내에 재개할 수 있습니다.

Filestore 에이전트 볼륨은 Agent Substrate에 영구 스토리지 레이어를 제공하여 샌드박스 정지 및 재개 주기 전반에서 작업공간 파일, 코드 저장소, 스크래치패드 아티팩트를 보존합니다.

Agent Substrate에서 에이전트 볼륨을 사용하는 방법

다음 단계에서는 Agent Substrate 및 Filestore 에이전트 볼륨이 개발자가 기능을 빌드하고, 테스트를 실행하고, 코드를 디버그하는 데 도움이 되는 대화형 코딩 에이전트를 지원하는 방법을 설명합니다.

  1. 세션 초기화: 개발자가 작업을 제출하면 Agent Substrate가 GKE에 샌드박스 환경을 만들고 전용 Filestore 볼륨을 마운트합니다. 에이전트는 프로젝트 저장소를 클론하고 종속 항목을 설치하며 작업공간을 준비합니다.
  2. 비용 효율적인 유휴 정지: 개발자가 코드 차이를 검토하거나 다음 프롬프트를 작성하는 동안 Agent Substrate는 볼륨을 마운트 해제하고 컴퓨팅 환경을 종료합니다. 컴퓨팅 리소스 사용률은 0으로 떨어지지만 모든 작업공간 파일, Git 기록, 빌드 캐시는 볼륨에 유지됩니다.
  3. 즉시 재개: 개발자가 새 프롬프트를 보내면 Agent Substrate가 사전 준비된 샌드박스를 요청하고 100ms 이내에 기존 볼륨을 다시 연결합니다. 에이전트는 전체 파일 시스템 컨텍스트를 그대로 유지한 채 즉시 워크로드를 재개하므로 시간이 많이 소요되는 저장소 재클론이나 종속 항목 재설치를 방지할 수 있습니다.

자세한 내용은 에이전트 기판 문서를 참조하세요.

Filestore 에이전트 볼륨을 사용하여 GKE Agent Substrate에서 스테이트풀(Stateful) 에이전트 워크로드를 실행하려면 Agent Substrate를 설치하고, Filestore CSI 드라이버 통합을 구성하고, 동적 CSI 볼륨을 사용하도록 에이전트 워크로드를 정의합니다.

Agent Substrate 설치

Google Cloud 프로젝트를 준비하고 GKE Standard 클러스터에 Agent Substrate를 설치하려면 GKE에 Agent Substrate 설치의 안내를 따르세요.

Filestore CSI 드라이버 설치 및 구성

Agent Substrate에서 Filestore 에이전트 볼륨을 사용하려면 대화형 Agent Substrate 설치 프로그램을 실행할 때 선택사항인 Filestore CSI 드라이버 단계를 선택해야 합니다.

Agent Substrate 컨트롤 플레인(ateapi)은 네트워크 gRPC를 통해 Filestore CSI 드라이버 컨트롤러와 직접 통신합니다. CSI 드라이버는 각 작업자의 수명 주기에 맞춰 Filestore 볼륨 풀에서 작업자별 볼륨을 동적으로 프로비저닝, 연결, 분리합니다.

Filestore 볼륨을 사용하는 워크로드 만들기

Agent Substrate에서는 별도의 Kubernetes PersistentVolumeClaim 객체를 만드는 대신 ActorTemplate 리소스에서 외부 Filestore 볼륨을 선언적으로 정의합니다. 다음 단계에서는 Filestore StorageClass 및 CSIDriverConfig를 구성하고, 외부 Filestore 볼륨을 마운트하는 WorkerPool 및 ActorTemplate를 배포하고, 액터 수명 주기를 관리하는 방법을 안내합니다.

StorageClass 만들기

Filestore 볼륨 풀에서 동적 볼륨을 프로비저닝하기 위해 storageclass.yaml라는 파일을 만듭니다.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: substrate-volumepool-sc
provisioner: filestore.csi.storage.gke.io
parameters:
  volume-pool: "projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_NAME"
allowVolumeExpansion: false
reclaimPolicy: Delete
volumeBindingMode: Immediate

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • LOCATION: 볼륨 풀이 있는 리전(예: us-central1)
  • VOLUME_POOL_NAME: Filestore 볼륨 풀의 이름입니다.

StorageClass를 적용합니다.

kubectl apply -f storageclass.yaml

CSIDriverConfig 등록

CSIDriverConfig 리소스는 Kubernetes StorageClass 프로비저닝 도구(filestore.csi.storage.gke.io)를 Filestore CSI 컨트롤러 서비스의 네트워크 gRPC 엔드포인트와 CSI 노드 플러그인의 로컬 Unix 도메인 소켓 경로에 연결합니다.

csi-driver-config.yaml이라는 파일을 만듭니다.

apiVersion: ate.dev/v1alpha1
kind: CSIDriverConfig
metadata:
  name: filestore.csi.storage.gke.io
spec:
  driverName: filestore.csi.storage.gke.io
  controllerEndpoint: tcp://csi-filestore-controller.gcp-filestore-csi-driver.svc:10000
  nodeSocketOverride: unix:///var/lib/kubelet/plugins/filestore.csi.storage.gke.io/csi.sock
  tls:
    enabled: true
    usePodIdentity: true
    serverName: csi-filestore-controller.gcp-filestore-csi-driver.svc

CSIDriverConfig를 적용합니다.

kubectl apply -f csi-driver-config.yaml

WorkerPool 및 ActorTemplate 정의

  1. 작업자 풀, 액터 템플릿, 액터의 격리 경계 역할을 할 ate-demo 네임스페이스와 Kubernetes 네임스페이스를 만듭니다.

    kubectl ate create atespace ate-demo
kubectl create namespace ate-demo

  2. 액터 샌드박스를 호스팅할 준비가 된 물리적 대기 워크로드를 유지하기 위해 WorkerPool 리소스를 만듭니다. 다음 매니페스트를 worker-pool.yaml로 저장합니다.

    apiVersion: ate.dev/v1alpha1
kind: WorkerPool
metadata:
  name: agent-pool
  namespace: ate-demo
  labels:
    workload: stateful-agent
spec:
  replicas: 5
  workerImage: ko://github.com/agent-substrate/substrate/cmd/ateom-gvisor

  3. WorkerPool 매니페스트를 적용합니다.

    kubectl apply -f worker-pool.yaml

  4. substrate-volumepool-sc에서 5GiB 볼륨을 마운트하는 ActorTemplate를 정의하는 actor-template.yaml이라는 파일을 만듭니다.

    metadata:
  atespace: ate-demo
  name: stateful-agent-template
workerSelector:
  matchLabels:
    workload: stateful-agent
containers:
- name: agent
  image: CONTAINER_IMAGE
  volumeMounts:
  - name: shared-storage
    mountPath: /mnt/shared
  readyz:
    httpGet:
      path: /readyz
      port: 8080
sandboxConfig:
  sandboxClass: SANDBOX_CLASS_GVISOR
  configName: gvisor-default
snapshotsConfig:
  storageLocation: gs://SNAPSHOT_BUCKET/stateful-agent
volumes:
- name: shared-storage
  externalVolumeTemplate:
    capacity: 5Gi
    storageClassName: substrate-volumepool-sc

    다음을 바꿉니다.

    • CONTAINER_IMAGE: 에이전트 워크로드의 컨테이너 이미지입니다(예: gcr.io/my-project/agent-app@sha256:7f28ab0...).
    • SNAPSHOT_BUCKET: Agent Substrate에서 액터 스냅샷을 저장하는 데 사용하는 Cloud Storage 버킷입니다.

    이 매니페스트에서 volumes[].externalVolumeTemplate는 요청된 볼륨 용량(5Gi)과 프로비저닝 도구가 CSIDriverConfig과 일치하는 StorageClass(substrate-volumepool-sc)를 지정하고, containers[].volumeMounts는 해당 볼륨을 /mnt/shared에 마운트합니다. volumes에 선언된 모든 볼륨은 하나 이상의 컨테이너에 의해 마운트되어야 합니다.

  5. kubectl ate CLI를 사용하여 Agent Substrate API를 통해 ActorTemplate를 만듭니다.

    kubectl ate create actor-template -f actor-template.yaml

액터 생성, 정지, 재개

ActorTemplate가 생성되고 골든 스냅샷이 준비되면 액터 인스턴스를 만들고 실행 상태를 관리할 수 있습니다.

  1. stateful-agent-template에서 새 액터를 만듭니다.

    kubectl ate create actor ACTOR_NAME \
    --template=stateful-agent-template \
    -a ate-demo

    ACTOR_NAME을 작업자의 DNS-1123 라벨 이름(예: my-agent-1)으로 바꿉니다.

    액터를 만들면 Agent Substrate가 substrate-volumepool-sc에서 전용 Filestore 볼륨을 동적으로 프로비저닝하고 /mnt/shared에 마운트합니다.

  2. 유휴 상태가 되면 액터를 정지합니다.

    kubectl ate suspend actor ACTOR_NAME \
    -a ate-demo

    액터를 정지하면 메모리 상태가 Cloud Storage에 체크포인트되고, 볼륨의 모든 작업공간 파일을 보존하면서 Filestore 볼륨을 마운트 해제하고 분리하며, 워크로드를 해제합니다.

  3. 새 요청 또는 태스크가 도착하면 액터를 재개합니다.

    kubectl ate resume actor ACTOR_NAME \
    -a ate-demo

    액터를 재개하면 사용 가능한 워크로드에 할당되고, 메모리 스냅샷이 복원되며, 모든 파일이 그대로 유지된 상태로 /mnt/shared에서 기존 Filestore 볼륨이 다시 연결됩니다.

다음 단계