GKE에 에이전트 Substrate 설치

에이전트 서브스트레이트는 유휴 상태인 에이전트를 일시중지하고 다시 작동해야 할 때 해당 에이전트를 복원하여 GKE 클러스터에서 에이전트 워크로드를 효율적으로 실행합니다. 에이전트 기판은 GKE Standard 클러스터에 설치할 수 있는 오픈소스 소프트웨어입니다.

이 문서는 에이전트 기판을 위해 Google Cloud 프로젝트와 GKE 클러스터를 준비하고, 설치 프로그램을 실행하는 방법을 설명하며, 설치로 생성되는 리소스를 설명합니다.

가격 책정

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

제한사항

에이전트 Substrate에는 다음과 같은 설치 제한사항이 있습니다.

  • Cloud Shell: Cloud Shell은 영구 디스크 스토리지 5GB를 제공하므로 설치에 충분하지 않아 Cloud Shell에 에이전트 Substrate를 설치할 수 없습니다. 로컬 머신에서 설치 프로그램을 실행해야 합니다.
  • 클러스터 모드: GKE 표준 클러스터에만 에이전트 Substrate를 설치할 수 있습니다. Autopilot 클러스터는 지원되지 않습니다.
  • 기존 클러스터 및 베타 API: 기존 클러스터에서는 필수 베타 API(podcertificaterequests 및 clustertrustbundles)를 사용 설정할 수 없습니다. 버전 1.36을 실행하는 기존 클러스터에 설치하는 경우 클러스터를 만들 때 이러한 API가 사용 설정되어 있어야 합니다.
  • 머신 유형: 혼합 CPU 아키텍처에서 실행되는 머신 시리즈 (예: E2 머신 유형)는 사용할 수 없습니다.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

  • Google Kubernetes Engine API를 사용 설정합니다.
    • Google Kubernetes Engine API 사용 설정
  • 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치했으면 gcloud components update 명령어를 실행하여 최신 버전을 가져옵니다. 이전 gcloud CLI 버전에서는 이 문서의 명령어를 실행하지 못할 수 있습니다.
  • gcloud CLI에 다음 구성요소를 설치합니다.
    • kubectl
    • gke-gcloud-auth-plugin
  • 로컬 머신에 다음 도구가 설치되어 있는지 확인합니다.
    • Git을 사용하여 에이전트 기판 저장소를 클론합니다.
    • Go를 사용하여 소스 코드로 배포되는 설치 프로그램의 프로그램을 실행합니다.
    • make를 클릭하여 설치 프로그램을 시작합니다.

  • 설치 프로그램은 사용자를 대신하여 API를 사용 설정하고 리소스를 프로비저닝하므로 다음 명령어를 실행하여 애플리케이션 기본 사용자 인증 정보 (ADC)를 설정합니다.

    gcloud auth application-default login

    ADC를 사용한 인증에 대한 자세한 내용은 애플리케이션 기본 사용자 인증 정보 설정을 참고하세요.

필요한 역할

에이전트 Substrate를 설치하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

클러스터 요구사항

설치 프로그램에서 클러스터를 만들도록 하면 에이전트 기판의 모든 요구사항을 충족하는 클러스터가 자동으로 구성됩니다.

기존 클러스터에 에이전트 기판을 설치하는 경우 해당 클러스터는 다음 요구사항을 충족해야 합니다.

  • GKE Standard에서 실행됩니다 (에이전트 기판은 Standard 클러스터에서만 지원됨).
  • GKE 버전 1.36 (베타 플래그 사용 설정) 또는 버전 1.37 이상을 실행합니다.
  • 노드에 c3-standard-4 이상의 머신 유형을 사용합니다.
  • PodCertificateRequest 및 ClusterTrustBundle Kubernetes API가 사용 설정되어 있습니다 (certificates.k8s.io/v1beta1/podcertificaterequests 및 certificates.k8s.io/v1beta1/clustertrustbundles). 이러한 API는 Kubernetes 버전 1.37 이상에서 GA이므로 버전 1.37 이상을 실행하는 모든 클러스터에서 사용 설정됩니다. 버전 1.36 패치 버전을 실행하는 기존 클러스터에서만 수동으로 사용 설정하면 됩니다. 자세한 내용은 기존 클러스터에서 베타 API 사용 설정을 참고하세요.

에이전트 Substrate 설치

에이전트 Substrate를 설치하려면 로컬 터미널에서 다음 명령어를 실행합니다.

curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash

대화형 설치 프로그램에서 프로젝트, 클러스터, 스토리지 설정을 묻는 메시지가 표시됩니다. 가능한 경우 추천 기본값을 제안하며, 이를 수락하거나 맞춤설정할 수 있습니다.

  • 프로젝트 ID (필수): 리소스가 프로비저닝될 Google Cloud 프로젝트를 지정합니다. gcloud CLI의 기본 프로젝트를 구성한 경우 설치 프로그램에서 해당 프로젝트 ID를 사용합니다.
  • 클러스터 (필수): 설치 프로그램에서 권장 기본값을 사용하여 새 GKE 클러스터를 만들도록 할지 아니면 기존 클러스터에 에이전트 Substrate를 설치할지 선택합니다. 기존 클러스터에 설치하는 경우 클러스터 요구사항 섹션의 요구사항을 충족하는지 확인합니다.
  • 스냅샷 버킷 (선택사항): 맞춤 Cloud Storage 버킷 이름을 지정하거나 비워 두어 설치 프로그램이 ate-snapshots-<project>-<zone>이라는 기본 버킷을 만들도록 합니다.

컨테이너 이미지 소스를 선택하라는 메시지가 표시되면 다음 옵션 중에서 선택할 수 있습니다.

  • 사전 빌드된 이미지: 컨테이너 레지스트리에서 게시된 이미지를 가져옵니다. 빌드되거나 푸시되는 항목이 없으므로 Google Cloud 프로젝트에 자체 Container Registry가 필요하지 않습니다.
  • 소스에서 빌드: 업스트림 에이전트 기판 저장소(또는 맞춤 브랜치)에서 이미지를 빌드하고 프로젝트의 Artifact Registry 레지스트리에 푸시합니다.

설치 프로그램의 기능

설치 프로그램은 사용자를 대신하여 다음 프로그램을 실행합니다.

  • setup-gcp: 필요한 Google Cloud 리소스를 만들거나 확인하고, API를 사용 설정하고, 기존 클러스터를 사용하지 않기로 선택한 경우 GKE 클러스터와 Cloud Storage 버킷을 만들고, IAM 정책을 구성합니다.
  • ate-setup: 사전 빌드된 에이전트 기판 컨테이너 이미지와 컨트롤러를 GKE 클러스터에 배포합니다.

먼저 설치 프로그램은 Google Cloud 프로젝트를 다음과 같이 변경합니다.

  1. 에이전트 기판에 필요한 Google Cloud API를 사용 설정합니다.
  2. 다음 설정이 있는 GKE Standard 클러스터를 만듭니다 (기존 클러스터를 사용하지 않는 경우).
    • GKE용 워크로드 아이덴티티 제휴: 에이전트 Substrate가 노드에 키를 저장하지 않고 Cloud Storage에 액세스할 수 있습니다.
    • GKE Dataplane V2: 수신 요청을 에이전트로 라우팅하는 데 필요한 네트워킹을 처리합니다.
    • 인증서 API (PodCertificateRequest 및 ClusterTrustBundle): 이러한 Kubernetes 베타 API가 에이전트 기판 구성요소 간의 TLS 통신을 위한 인증서를 발급할 수 있도록 지원합니다.
    • 관리형 OpenTelemetry: 클러스터에서 측정항목과 trace를 수집합니다.
  3. 에이전트 기질이 스냅샷을 쓰는 Cloud Storage 버킷을 만듭니다.
  4. 스냅샷을 저장하기 위해 Cloud Storage에 에이전트 기판 액세스 권한을 부여합니다. 소스에서 빌드하도록 선택하면 컨테이너 이미지용 Artifact Registry에 대한 액세스 권한도 부여됩니다.
  5. 에이전트 서브스트레이트의 라우팅 지연 시간, 스냅샷 크기, gRPC 트래픽을 차트로 표시하는 Cloud Monitoring 대시보드를 만듭니다.

그런 다음 설치 프로그램은 클러스터를 다음과 같이 변경합니다.

  1. 클러스터에 에이전트 Substrate API 그룹과 리소스를 추가합니다. 이러한 리소스는 ActorTemplate (에이전트가 사용하는 컨테이너 이미지와 리소스를 정의함) 및 WorkerPool (유휴 상태의 샌드박스를 얼마나 준비된 상태로 유지할지 정의함)와 같은 Kubernetes 커스텀 리소스입니다.
  2. 에이전트 기판의 구성요소와 액터를 식별하는 인증서를 발급하는 인증 기관을 설정합니다. 구성요소는 mTLS를 사용하여 서로 인증하기 위해 이러한 인증서를 제공합니다.
  3. 액터와 워커의 상태를 추적하는 PostgreSQL 데이터베이스와 함께 에이전트 Substrate의 구성요소를 클러스터에 배포합니다. 설치 프로그램은 데이터베이스와 모든 컨트롤 플레인 포드가 준비될 때까지 기다립니다.

에이전트 기판은 ate-system 및 podcertificate-controller-system 네임스페이스 내에서 구성요소를 일반 워크로드로 배포합니다. 설치 시 GKE 컨트롤 플레인이 수정되지 않습니다.

배포되는 구성요소에는 에이전트 서브스트레이트가 기본적으로 사용하여 각 에이전트를 실행되는 노드에서 격리하는 gVisor 기반 런타임이 포함됩니다. 설치 프로그램은 microVM 런타임을 구성하지 않습니다. 마이크로 VM 런타임을 사용하려면 중첩된 가상화가 사용 설정된 노드 풀에 수동으로 배포해야 합니다. 자세한 내용은 업스트림 에이전트 서브스트레이트 저장소의 microVM 런타임 안내를 참고하세요.

설치가 언제든지 실패하면 (예: 일시적인 네트워크 오류 또는 토큰 만료로 인해) 명령어를 다시 실행합니다. 설치 프로그램은 기존 리소스를 보존하고 중단된 지점부터 다시 시작합니다.

기존 클러스터에서 에이전트 Substrate를 업그레이드하려면 설치 프로그램을 실행하고 설치된 클러스터 업그레이드를 선택합니다. 자세한 내용은 substrate-gke README의 설치된 클러스터 업그레이드를 참고하세요.

선택적 단계

핵심 구성요소를 배포한 후 설치 프로그램은 다음 선택 단계를 제공합니다.

  • Filestore CSI 드라이버: 에이전트 기판용으로 구성된 Filestore CSI 드라이버를 설치합니다. 에이전트가 공유 작업공간이나 저장소와 같이 포드 간에 공유 파일 스토리지가 필요한 경우 이 옵션을 선택하세요. 클러스터에 관리형 GKE Filestore 부가기능이 사용 설정되어 있으면 설치 프로그램에서 드라이버를 배포하기 전에 이를 사용 중지합니다.
  • 노드 풀 자동 확장: 노드 풀에서 GKE 클러스터 자동 확장을 사용 설정합니다. 풀의 최소 및 최대 노드 수를 지정합니다. 수요가 급증할 때 GKE가 자동으로 노드를 추가하고 에이전트가 일시 중지될 때 노드를 삭제하도록 하려면 이 옵션을 선택하세요. 예측 가능한 컴퓨팅 비용으로 고정된 노드 수를 선호하는 경우 이 옵션을 건너뛰세요.
  • 카운터 데모: 에이전트 일시중지 및 복원을 보여주는 예시 워크로드를 배포합니다. 설치 후 클러스터를 테스트하려면 이 옵션을 선택하세요. 자세한 내용은 카운터 데모 사용해 보기를 참고하세요.

설치 확인

설치가 성공했고 핵심 구성요소가 실행 중인지 확인하려면 다음 명령어를 실행하고 모든 포드의 상태가 Running인지 확인합니다.

kubectl get pods -n ate-system
kubectl get pods -n podcertificate-controller-system

노드 라벨 지정 및 버전

설치 프로그램은 클러스터의 모든 노드에 ate.dev/substrate-version 라벨을 적용합니다. 이 라벨은 클러스터에 설치된 에이전트 기판의 버전을 지정하며, 에이전트 기판은 이 버전 라벨이 있는 노드에서만 작업자를 실행합니다.

클러스터에 설치된 에이전트 기판 버전을 확인하려면 다음 명령어를 실행합니다.

kubectl get ds -n ate-system -l app=atelet -L ate.dev/substrate-version

다음 노드 라벨링 세부정보를 고려하세요.

  • 작업자 풀: WorkerPool를 만들 때 이 버전 태그를 타겟팅하도록 구성합니다. 예를 보려면 Substrate API 가이드의 설치된 기판 버전에 풀 고정을 참고하세요.
  • 새 노드: 설치 프로그램은 노드 풀이 아닌 개별 노드에 라벨을 지정합니다. 따라서 설치 후 추가된 새 노드는 설치 프로그램에서 생성한 노드 풀에 있더라도 버전 라벨 없이 시작됩니다. 새 노드가 자동으로 라벨을 수신하도록 GKE 노드 풀에 라벨을 지정해야 합니다.

카운터 데모 사용해 보기

설치 프로그램에서 메시지가 표시될 때 카운터 데모를 배포하도록 선택한 경우 에이전트 기판의 일시 중단 및 복원 기능을 확인할 수 있습니다. 데모는 메모리에 카운트를 유지하는 작은 웹 서버를 실행합니다.

데모의 WorkerPool 및 ActorTemplate를 배포하면 설치 프로그램에서 ActorTemplate에서 Actor를 만들고 해당 Actor에 요청을 전송하는 데 필요한 명령어를 출력합니다. 업스트림 에이전트 기판 저장소의 카운터 데모 README에 취해야 할 다음 단계가 설명되어 있습니다.

에이전트 Substrate 제거

설치가 완료되고 종료되면 설치 프로그램은 환경에 맞게 맞춤설정된 정리 명령어를 출력합니다.

설치 중에 생성된 리소스를 삭제하려면 다음 옵션 중 하나를 선택합니다.

  • 기존 클러스터에서 에이전트 기판 삭제: 기존 클러스터에 설치했고 클러스터와 다른 워크로드를 유지하려면 설치 프로그램에서 출력하는 ate-setup delete ate-system 명령어를 실행하여 에이전트 기판 구성요소만 삭제합니다. 설치 프로그램은 설치 중에 구성된 프로젝트, 클러스터, 위치 값으로 이 명령어를 미리 채웁니다.

  • 모든 리소스 (클러스터 포함) 삭제: GKE 클러스터, 스냅샷 버킷, IAM 바인딩, 대시보드를 삭제하려면 설치 프로그램에서 출력하는 cleanup-gcp 명령어를 실행합니다. 설치 프로그램은 설치 중에 구성된 프로젝트, 클러스터, 위치, 버킷 값으로 이 명령어를 미리 채웁니다. 자세한 내용은 substrate-gke README의 'Tearing down' 섹션을 참고하세요.

다음 단계