의도에서 인프라로: 에이전트 기반 GKE 마이그레이션

1. 소개

이 Codelab에서는 AI 에이전트를 사용하여 복잡한 인프라 이전을 자동으로 실행하는 방법을 알아봅니다. Kubernetes 매니페스트를 직접 작성하거나 자동화 스크립트를 실행하는 대신 자연어로 의도를 표현하면 에이전트가 모델 컨텍스트 프로토콜 (MCP) 및 Gemini Cloud Assist 서버를 사용하여 구성을 생성하고 적용합니다.

중요: 이 Codelab에서는 현재 비공개 프리뷰 상태인 Gemini Cloud Assist (GCA) MCP 서버를 중점적으로 다룹니다. 전체 기능 세트에 액세스할 수 없더라도 Codelab을 진행할 수 있습니다. 하지만 변형 기능 (특히 invoke_operation 도구)에 대한 액세스 권한이 부여되지 않은 경우 상담사가 변경사항을 자동으로 적용할 수 없습니다. 이 경우 생성된 Kubernetes 매니페스트를 수동으로 적용해야 합니다. 자세한 내용은 계정팀에 문의하세요.

GCA MCP 서버 기능

GCA MCP 서버는 에이전트에게 다음과 같은 여러 전문 도구를 제공합니다.

• ask_cloud_assist: Google Cloud Platform 지원 및 Gemini Cloud Assist 에이전트의 기본 인터페이스입니다. Gemini Cloud Assist의 모든 기능은 이 도구를 통해 액세스할 수 있으며 다른 MCP 도구의 기능을 포함합니다.
• design_infra: Google Cloud Platform에서 인프라를 설계하고 아키텍처를 만드는 워크플로를 지원합니다.
• investigate_issue: Google Cloud에서 문제 해결을 위한 워크플로를 지원합니다. 조사 리소스를 통해 빠른 문제 해결 또는 심층적인 문제 해결을 할 수 있습니다.
• invoke_operation: Google Cloud에서 리소스를 만들고, 업데이트하고, 삭제하는 워크플로를 지원합니다. 이 도구는 상담사 작업이 사용 설정된 경우에만 작동합니다. Gemini Cloud Assist의 쓰기 작업은 이 도구를 호출해야만 실행할 수 있습니다.
• optimize_costs: Google Cloud 비용을 분석, 추적, 최적화하는 워크플로를 지원합니다. 지출을 상세하게 분석하고 유휴 또는 사용률이 낮은 리소스를 찾아 비용 효율성을 높일 수 있는 기회를 파악합니다.

GKE 클러스터와 다운로드된 모델이 있는 사전 준비된 환경으로 시작합니다. 그런 다음 gemini-cli를 사용하여 에이전트가 Cloud Run에서 GKE로 워크로드를 이전하고 스토리지 버킷의 스테이징된 모델을 사용하여 vLLM으로 Gemma 추론 인스턴스를 시작하도록 프롬프트합니다.

실습할 내용

• Terraform을 사용하여 GKE 클러스터를 스테이징하고 Gemma 모델을 다운로드합니다.
• 에이전트 규칙 및 MCP 서버를 사용하여 gemini-cli를 구성합니다.
• 특정 자연어 프롬프트를 사용하여 에이전트가 전체 이전 및 배포를 실행하도록 지시합니다.
• 에이전트가 실행한 배포를 확인합니다.

필요한 항목

• 웹브라우저(예: Chrome)
• 결제가 사용 설정된 Google Cloud 프로젝트.
• Hugging Face 토큰 (스테이징 단계에서 Gemma 모델을 다운로드하는 데 필요)

이 Codelab은 초보자를 포함한 모든 수준의 개발자를 대상으로 합니다.

예상 소요 시간: 45~60분

2. 시작하기 전에

Google Cloud 프로젝트 만들기 또는 선택

1. Google Cloud 콘솔에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
2. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Cloud Shell 시작

1. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
2. 인증을 확인합니다.

gcloud auth list

3. 프로젝트를 확인합니다.

gcloud config get project

4. 필요한 경우 설정합니다.

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

API 사용 설정

다음 명령어를 실행하여 필요한 모든 API를 사용 설정합니다.

gcloud services enable \
  run.googleapis.com \
  container.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com

또한 Gemini Cloud Assist MCP 서비스를 사용 설정합니다.

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. 환경 스테이징

이 단계에서는 맞춤 챗봇 이미지를 빌드하고, GKE 클러스터를 만들고, Gemma 모델을 Cloud Storage 버킷에 다운로드하여 환경을 준비합니다.

조직에서는 Gemini API로 시작하지만 나중에 더 나은 제어, 맞춤설정 또는 비즈니스에 특화된 미세 조정된 버전을 사용하기 위해 자체 호스팅 모델로 이전하기로 결정하는 경우가 많습니다. 이 Codelab에서는 GKE에서 직접 호스팅할 수 있는 강력한 개방형 모델의 예로 Gemma를 사용합니다. Cloud Storage 버킷에 스테이징하면 클러스터에서 사용할 수 있습니다.

데모 애셋 다운로드

GitHub 저장소에서 특정 폴더를 클론합니다.

git clone --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
cd next-26-keynotes
git sparse-checkout set devkey/intent-to-infrastructure
cd devkey/intent-to-infrastructure

챗봇 이미지 빌드

인프라를 프로비저닝하기 전에 맞춤 챗봇 이미지를 빌드하고 Artifact Registry에 푸시해야 합니다. 이 이미지는 다음 단계에서 Cloud Run에 의해 사용됩니다.

1. asia-southeast1에서 chatbot-repo라는 Artifact Registry 저장소를 만듭니다.

   gcloud artifacts repositories create chatbot-repo \
       --repository-format=docker \
       --location=asia-southeast1 \
       --description="Chatbot Docker repository"
   

2. src 디렉터리로 이동합니다.

   cd src
   

3. Cloud Build를 사용하여 이미지를 빌드하고 푸시합니다.

   gcloud builds submit --config cloudbuild.yaml \
       --substitutions=_LOCATION="asia-southeast1",_REPOSITORY_ID="chatbot-repo",_IMAGE_NAME="chatbot",_IMAGE_TAG="latest"
   

4. 프로젝트 루트로 다시 이동합니다.

   cd ..
   

기본 인프라 프로비저닝

terraform 디렉터리로 이동하고 1단계를 실행하여 GKE 클러스터를 만듭니다.

cd terraform
./deploy.sh demo step1 apply

참고: deploy.sh를 실행할 때 '권한 거부됨' 오류가 표시되면 chmod +x deploy.sh를 실행하여 실행 가능하도록 설정해야 할 수 있습니다.

이 스크립트는 Terraform을 사용하여 기본 인프라를 프로비저닝합니다. VPC, GKE 클러스터, 서비스 계정을 만들고 방금 빌드한 챗봇 이미지를 사용하여 초기 Cloud Run 서비스를 배포합니다.

이 과정에서 Terraform은 계획을 표시하고 확인을 요청합니다. 승인하고 계속하려면 yes를 입력해야 합니다.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

전체 프로세스를 완료하는 데 15~20분이 걸릴 수 있습니다.

배포가 완료되면 터미널에 출력된 Terraform 출력에서 cloud_run_url를 찾습니다. URL을 클릭하여 브라우저에서 챗봇을 엽니다. 이제 Gemini 2.5 Flash를 기반으로 실행되는 챗봇과 상호작용할 수 있습니다.

모델 다운로드

이 단계에서는 Cloud Storage 버킷에 Gemma 모델을 스테이징합니다. 관리형 Gemini API로 시작하지만, 맞춤 미세 조정 모델이나 다른 맞춤 오픈 모델을 실행할 수도 있습니다. 또는 보안 또는 규정 준수상의 이유로 자체 클러스터 내에서 모델 실행을 관리하고 싶을 수도 있습니다. 여기에서 모델을 스테이징하면 관리형 Gemini API에서 GKE의 자체 호스팅 모델로 마이그레이션할 수 있습니다.

2단계를 실행하여 Gemma 모델을 GCS 버킷에 다운로드합니다. Hugging Face 토큰이 필요합니다. 이 프로세스는 GKE 클러스터에서 실행되며, Hugging Face에서 모델을 다운로드하고 나중에 사용할 수 있도록 버킷에 업로드하는 데 약 15분 (트래픽에 따라 더 오래 걸릴 수 있음)이 걸립니다.

./deploy.sh demo step2 apply -var="hf_token=<YOUR_HF_TOKEN>"

이 Terraform 명령어는 다운로드를 처리하기 위해 GKE 클러스터에 Kubernetes 작업을 만듭니다. 작업이 실행되는 동안 Terraform 스크립트는 활성 상태로 유지됩니다.

다른 셸 세션에서 진행 상황을 모니터링하거나 실행 후 완료되었는지 확인하려면 다음을 실행하면 됩니다.

kubectl get jobs

4. 에이전트 및 MCP 설정

이제 마이그레이션을 실행할 에이전트를 구성합니다. gemini-cli를 사용하여 환경과 상호작용하는 규칙을 갖춥니다.

Gemini Cloud Assist (GCA) MCP 서버는 이 흐름의 중요한 구성요소입니다. 클라이언트 측 에이전트와 Google Cloud 간의 브리지 역할을 하여 조사를 실행하고, 계획 (예: gcloud 및 kubectl 명령어)을 생성하고, 클라우드 프로젝트의 리소스에 직접 변경사항을 적용할 수 있습니다.

roles/geminicloudassist.user와 같은 MCP 도구를 호출할 수 있는 역할이 부여되었는지 확인합니다. 나중에 권한 문제가 발생하면 Cloud Assist의 IAM 역할 구성에 관한 문서를 참고하세요.

Gemini Cloud Assist를 서드 파티 도구와 통합하는 방법에 관한 자세한 내용은 MCP를 사용하여 Gemini Cloud Assist를 서드 파티 도구와 통합 문서를 참고하세요.

Gemini Cloud Assist 확장 프로그램 설치

1. 다음 명령어를 실행하여 애플리케이션 기본 사용자 인증 정보 (ADC)를 통해 인증합니다.

gcloud auth application-default login

2. MCP 서버를 Gemini CLI 확장 프로그램으로 설치합니다.

gemini extensions install https://github.com/GoogleCloudPlatform/gemini-cloud-assist-mcp

참고: 이 명령어는 MCP 서버와 전문 기술을 모두 설치합니다. 이 스킬은 Gemini CLI가 Cloud Assist 도구를 사용해야 하는 적절한 컨텍스트를 이해하는 데 도움이 됩니다.

3. 스킬이 성공적으로 설치되었는지 확인합니다. gemini를 시작하고 다음 명령어를 실행하여 활성 스킬을 나열합니다.

/skills list

목록에 Gemini Cloud Assist와 관련된 스킬이 표시되는지 확인합니다. exit를 입력하여 Cloud Shell 프롬프트로 돌아갑니다.

Gemini Cloud Assist에서 변형 사용 설정

에이전트가 인프라에 변경사항을 적용하도록 허용하려면 Gemini Cloud Assist UI에서 변이 기능을 사용 설정해야 합니다.

1. Google Cloud 콘솔 창의 오른쪽 상단에 있는 Gemini 로고를 클릭하여 Gemini 어시스턴트 사이드바를 엽니다.
   
   
2. 사이드바에 나열된 필요한 API를 사용 설정합니다.
   
   
3. 사이드바에서 설정으로 이동하여 'Cloud Assist를 사용 설정하여 작업을 실행'을 선택합니다.
   
   
   

에이전트 규칙 구성

프로젝트 디렉터리에는 폴더의 루트 (intent-to-infrastructure)에 맞춤 gemini.md 파일이 포함되어 있습니다. 이 파일에는 에이전트가 올바른 도구를 사용하도록 안내하는 규칙이 포함되어 있습니다.

이 파일이 디렉터리에 있는지 확인합니다. Terraform 파일, 애플리케이션 코드, gemini.md 규칙 파일에 액세스할 수 있도록 이 디렉터리에서 gemini를 실행해야 합니다.

5. 1단계: 챗봇을 GKE로 마이그레이션

이제 에이전트를 사용하여 마이그레이션의 첫 번째 부분인 챗봇 애플리케이션을 Cloud Run에서 GKE로 이동하는 작업을 수행합니다.

1. intent-to-infrastructure 디렉터리의 루트에서 gemini를 시작합니다 (gemini.md에 액세스할 수 있는지 확인).
2. 먼저 에이전트에게 프로젝트를 탐색하여 애플리케이션과 인프라를 이해하도록 요청합니다. 다음 프롬프트를 입력합니다.

Tell me about the app and infrastructure in this project

에이전트가 디렉터리의 파일을 읽고 챗봇 애플리케이션과 Terraform 구성에 대한 개요를 제공해야 합니다.

3. 이제 다음 프롬프트를 사용하여 에이전트가 마이그레이션을 실행하도록 지시합니다.

Convert my Cloud Run service to the equivalent on GKE.

4. 상담사는 다음을 수행해야 합니다.
   • ask_cloud_assist 도구를 사용하여 컨텍스트를 파악합니다.
   • design_infra 도구를 사용하여 챗봇 애플리케이션의 Kubernetes YAML을 생성합니다.
   • '이 구성을 적용하시겠어요?'라고 묻습니다.

참고: gemini가 도구를 처음 사용하려고 하면 MCP 서버에서 제공하는 도구에 액세스할 수 있는 권한을 요청합니다. 에이전트가 계속 진행되도록 하려면 허용을 선택해야 합니다.

5. yes로 응답하여 변경사항을 적용합니다. 에이전트는 invoke_operation를 사용하여 리소스를 GKE 클러스터에 배포합니다.

1단계 확인

1. 서비스 목록을 가져옵니다.

kubectl get services

챗봇 애플리케이션 서비스가 실행 중인 것을 확인할 수 있습니다.

2. 챗봇에 액세스하도록 서비스를 포트 전달합니다.

kubectl port-forward svc/chatbot-service 8080:80

(부가 정보:

chatbot-service

(다른 경우 에이전트에서 생성된 실제 서비스 이름 사용)

챗봇을 테스트합니다. Cloud Run에서 구성된 대로 Gemini API를 사용하여 계속 응답해야 합니다.

6. 2단계: vLLM을 통해 Gemma 배포 및 다시 연결

이 단계에서는 에이전트를 사용하여 자체 호스팅 Gemma 모델을 GKE에 배포하고 애플리케이션을 다시 연결합니다.

1. 동일한 gemini 세션에서 다음 프롬프트를 입력합니다.

Now that the chatbot is on GKE, add a vLLM service running the Gemma model from my storage bucket in the same cluster. Make sure to give the vLLM service at least 10 minutes to start up to account for loading the large model. Then, update the chatbot service to reference this vLLM service instead of the Gemini API.

2. 상담사는 다음을 수행해야 합니다.
   • design_infra을 사용하여 vLLM 배포 및 서비스의 YAML을 생성합니다.
   • 챗봇 배포 YAML을 업데이트하여 환경 변수 (또는 구성)가 Gemini API 대신 새 vLLM 서비스를 가리키도록 변경합니다.
   • 변경사항을 적용할지 확인합니다.
3. yes로 응답하여 변경사항을 적용합니다.

2단계 인증

1. 포드 목록을 다시 가져옵니다.

kubectl get pods

이제 챗봇과 vLLM 모두의 포드가 표시됩니다.

참고: vLLM 포드가 Running 상태가 된 후에도 모델 크기가 크기 때문에 서버가 스토리지 버킷에서 모델 가중치를 완전히 로드하고 서빙을 시작하는 데 최대 10분이 걸릴 수 있습니다. 로그를 확인하여 로드 진행 상황을 모니터링할 수 있습니다.

kubectl logs -f deployment/gemma-vllm -c vllm-server

2. vLLM이 준비되면 필요한 경우 챗봇 서비스를 다시 포트 포워딩하고 테스트합니다. 이제 자체 호스팅 Gemma 모델로 구동됩니다.

7. 삭제

Google Cloud 계정에 지속적으로 비용이 청구되지 않도록 하려면 이 Codelab에서 만든 리소스를 삭제하세요.

기본 인프라에 대해 destroy 명령어를 실행합니다.

cd terraform
./deploy.sh demo step1 destroy

또한 로컬 환경을 정리하려면 Gemini Cloud Assist 확장 프로그램을 제거하거나 사용 중지하면 됩니다. gemini extensions uninstall 또는 gemini extensions disable을 사용한 후 확장 프로그램 이름을 사용합니다.

8. 다음 단계

Gemini Cloud Assist 및 고급 기능에 대해 자세히 알아보려면 다음 리소스를 확인하세요.

• Cloud Assist 조사로 문제 해결
• 능동 모드 설정하기

9. 축하합니다

수고하셨습니다 자연어와 MCP를 사용하여 에이전트 기반 워크로드 마이그레이션을 GKE로 성공적으로 수행했습니다.