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

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

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

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

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

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

자세한 내용은 에이전트 Substrate 문서를 참고하세요.

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

에이전트 Substrate 설치

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

Filestore CSI 드라이버 설치 및 구성

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

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

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

에이전트 기판에서는 별도의 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 atespace와 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를 사용하여 에이전트 기판 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)으로 바꿉니다.

    액터를 만들면 에이전트 기판에서 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 볼륨이 다시 연결됩니다.

다음 단계