클라우드 엔지니어링의 AI 툴킷: Gemini를 사용하여 GKE에서 플랫폼 엔지니어링

1. 소개

손상된 Kubernetes 배포 문제를 해결하는 것은 플랫폼 엔지니어의 일상에서 흔히 발생하며 종종 답답한 부분입니다. 일반적으로 로그를 살펴보고 kubectl describe 명령어를 실행하고 YAML 파일을 상호 참조하여 불일치 또는 잘못된 구성을 찾는 등 많은 수동 조사가 필요합니다.

범용 AI 챗봇은 개념을 설명하거나 기본 코드를 작성하는 데 도움이 될 수 있지만, 정보가 없는 상태에서 작동합니다. 특정 코드베이스나 클러스터의 라이브 상태에 대해 알지 못하므로 수동으로 복사하여 붙여넣고 컨텍스트를 전환하는 작업이 많이 필요합니다.

이 실습에서는 컨텍스트 수준이 높아지는 AI 도구를 사용하여 이 격차를 해소하는 방법을 알아봅니다. Gemini CLI와 모델 컨텍스트 프로토콜 (MCP)을 사용하여 GKE에서 작동하지 않는 애플리케이션의 문제를 해결합니다. 이 실습을 마치면 파일과 인프라를 인식하는 AI를 사용하여 복잡한 문제를 더 빠르게 해결하는 방법과 이러한 워크플로를 팀에서 재사용할 수 있는'기술'로 코딩하는 방법을 이해하게 됩니다.

핵심 개념

• 플랫폼 엔지니어링: 플랫폼 엔지니어링은 소프트웨어 개발자가 모든 기본 클라우드 서비스의 전문가가 될 필요 없이 자체 인프라를 관리할 수 있도록 내부 도구와 워크플로를 빌드하고 유지보수하는 관행입니다. 목표는 일관성과 보안을 유지하면서 기술적 마찰을 줄이는 것입니다. 표준화된 골든 경로를 만들어 플랫폼팀은 애플리케이션 개발자가 안전하고 빠르게 배포할 수 있도록 지원하고 플랫폼팀은 거버넌스와 비용을 관리할 수 있습니다.
• Gemini CLI: Gemini CLI는 터미널에서 직접 Gemini 모델과 상호작용할 수 있는 명령줄 인터페이스입니다. 표준 웹 기반 챗봇과 달리 CLI는 개발 환경 내에 존재하도록 설계되어 기존 셸 기반 워크플로에 AI를 더 쉽게 통합할 수 있습니다. CLI를 사용하면 다른 명령어의 출력을 모델에 직접 파이프하고 터미널을 종료하지 않고도 명령어를 실행할 수 있습니다.
• 모델 컨텍스트 프로토콜 (MCP): MCP는 AI 모델이 특정 도구 또는 데이터 소스에 연결할 수 있도록 지원하는 개방형 표준입니다. MCP가 없으면 AI 모델은 학습된 내용만 알고 사용자의 특정 리소스를 볼 수 없습니다. GKE MCP 서버를 사용하면 Gemini CLI가 Google Cloud 프로젝트의 API를 적극적으로 쿼리하고, 클러스터의 상태를 검사하고, 사용자를 대신하여 명령어를 실행할 수 있습니다. 모델의 추론 엔진과 실제 GKE API 사이의 브리지 역할을 합니다.
• 에이전트 스킬: 스킬은 전문 작업을 위해 AI 에이전트의 기능을 확장하는 명령어, 스크립트, 리소스 패키지입니다. 스킬을 사용하면 조직 표준을 코드화하고 복잡한 워크플로를 자동화할 수 있습니다.

실습 목표

이 실습에서 학습할 내용은 다음과 같습니다.

1. 컨텍스트 진행 경험: 컨텍스트를 늘리면 AI 문제 해결이 어떻게 개선되는지 확인하세요.
2. 수동 문제 해결과 AI 문제 해결 비교: 수동 디버깅의 어려움과 AI 지원 워크플로를 비교합니다.
3. 전체 컨텍스트 디버깅: GKE MCP 서버와 함께 Gemini CLI를 사용하여 전체 인프라 인식으로 애플리케이션을 디버그합니다.
4. 기능 확장: 맞춤 스킬을 작성하여 워크플로를 자동화하는 방법을 알아봅니다.

LLM 출력 참고사항

이 실습의 특성과 LLM의 작동 방식으로 인해 표시되는 출력은 예시 출력과 다를 수 있습니다. 이는 생성형 AI의 예상되는 동작입니다. 예시의 정확한 텍스트나 서식을 복제하려고 하기보다는 모델이 제공하는 단계와 추론을 이해하는 데 집중하세요.

2. 프로젝트 설정

실습을 시작하기 전에 환경을 준비합니다. Cloud Shell을 열고 프로젝트를 선택한 후 설정 스크립트를 실행합니다. 지금 시작해 보세요.

Cloud Shell 열기

이 실습에서는 Google Cloud에서 제공하는 브라우저 기반 터미널 환경인 Cloud Shell을 사용합니다. Google Cloud CLI (gcloud), kubectl, Gemini CLI를 비롯해 필요한 모든 도구가 사전 구성되어 있으므로 로컬 머신에 이러한 도구를 설치하는 시간을 절약할 수 있습니다.

1. Google Cloud Console로 이동합니다.
2. 콘솔의 오른쪽 상단 헤더를 확인하고 Cloud Shell 활성화 버튼 (터미널 프롬프트 >_와 유사함)을 클릭합니다.
3. 터미널 세션이 브라우저 창 하단에 열립니다. 메시지가 표시되면 계속을 클릭합니다.

프로젝트 선택

Cloud Shell 터미널에서 올바른 프로젝트 내에서 작업하고 있는지 확인합니다.

1. 콘솔에서 기존 프로젝트를 선택하거나 이 실습을 위한 새 프로젝트를 만듭니다.
2. 프로젝트 ID를 적어 둡니다. gcloud config set project [YOUR_PROJECT_ID]를 실행하여 현재 셸에서 프로젝트를 설정합니다.

실습 설정

이제 설정 스크립트를 실행하여 환경을 준비하고 실습의 버그를 도입합니다.

1. 저장소 클론:
   👉💻 다음 명령어를 실행하여 실습 디렉터리만 클론합니다.

   git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos ~/devrel-demos
   cd ~/devrel-demos
   git sparse-checkout set codelabs/ai-toolkit-lab-1
   

2. 실습 디렉터리로 이동합니다.
   👉💻 다음을 실행합니다.

   cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/
   

3. 환경 변수 설정:
   👉💻 다음 명령어를 실행하여 프로젝트와 리전을 설정합니다.

   export PROJECT_ID=$(gcloud config get-value project)
   export REGION=us-central1
   

4. 설정 스크립트 실행:
   이 스크립트는 아래에 나열된 API를 사용 설정하고, GKE Autopilot 클러스터를 만들고, 필요한 도구가 설치되어 있는지 확인합니다.
   👉💻 루트 디렉터리에서 스크립트를 실행합니다.

   ./setup.sh
   

   참고: 클러스터를 만드는 데 5~10분 정도 걸릴 수 있습니다.
5. 손상된 상태 초기화:
   동료가 손상된 환경을 남겨둔 시나리오를 시뮬레이션하려면 break.sh 스크립트를 실행하세요. 손상된 매니페스트를 활성 코드베이스 디렉터리에 복사합니다.
   👉💻 스크립트를 실행합니다.

   ./break.sh
   

6. 실습 준비:
   AI가 부정행위 (솔루션 확인)를 하지 않도록 실습의 나머지 부분에서는 cymbal-bank 디렉터리로 변경합니다.
   👉💻 다음을 실행합니다.

   cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/cymbal-bank
   

사용 설정된 API

설정 스크립트는 여러 Google Cloud API를 사용 설정합니다. 이러한 도구는 다음과 같은 작업을 실행합니다.

• container.googleapis.com: Google Kubernetes Engine API입니다. 모든 클러스터 수준 작업에 필요합니다.
• generativelanguage.googleapis.com: Gemini CLI가 Gemini 모델과 통신할 수 있도록 지원하는 API입니다.
• cloudresourcemanager.googleapis.com: 프로젝트 수준 메타데이터를 검사하고 권한을 관리하는 데 필요합니다.
• logging.googleapis.com: 컨테이너에서 로그를 가져오고 분석할 수 있으므로 문제 해결에 필수적입니다.

3. 0단계: 수동 문제 해결 (AI 없음)

이제 cymbal-bank 디렉터리에 있으므로 오류를 수동으로 찾아보겠습니다. '어려운 방법'입니다. AI에 힘든 일을 맡기기 전에 기준을 경험해 보세요. 수동 문제 해결은 kubectl와 같은 표준 도구를 사용하여 클러스터 상태를 검사하고, 로그를 가져오고, YAML 파일을 읽어 불일치를 발견하는 것을 의미합니다. 이 작업은 종종 느리고 지루하며, 연관성을 파악하려면 전문 지식이 필요합니다. 이는 나중에 사용할 AI 도구에 완벽한 참조점이 됩니다.

1. 배포 시도: Kubernetes에서 이러한 매니페스트를 어떻게 생각하는지 확인해 보겠습니다.
   👉💻 다음 명령어를 실행하여 매니페스트를 적용합니다.

   kubectl apply -f kubernetes-manifests/
   

   포드가 가동되는 데 몇 초 정도 걸릴 수 있습니다. 'watch kubectl get pods'를 사용하여 포드가 실행되는지 확인할 수 있습니다. 준비가 완료되면 ctrl+c를 사용하여 감시를 종료합니다. 목록에 실패한 포드가 두 개 표시됩니다.
   • 프런트엔드 포드에 'CreateContainerConfigError'가 표시됩니다. 이 유형의 오류는 일반적으로 컨테이너가 필요한 구성을 로드하는 데 문제가 있음을 나타냅니다. 컨테이너를 시작하는 데 필요한 외부 리소스가 무엇인지 생각해 보세요. 잘못 구성되었거나 누락된 환경 변수, 보안 비밀 또는 ConfigMap이 있나요? pod의 구성을 조사하여 구체적인 원인을 찾아야 합니다.
   • userservice 포드가 'ImagePullBackOff' 상태입니다. 이 오류가 표시되면 클러스터가 사용하도록 지정된 컨테이너 이미지를 가져올 수 없음을 의미합니다. 이미지 요청의 세부정보를 고려합니다. 이미지 이름과 태그가 정확한가요? 레지스트리에 권한 문제가 있을 수 있나요? 이미지가 가져오는 위치를 확인하여 요청이 실패하는 이유를 파악할 수 있습니다.
2. 손상 검사: 표준 Kubernetes 명령어를 사용하여 실패한 항목을 확인합니다.
   • 👉💻 포드 상태와 이름을 확인합니다.

     kubectl get pods
     

     • 관찰: ImagePullBackOff, CrashLoopBackOff, Pending 또는 CreateContainerConfigError에 포드가 표시됩니다.
     • 참고: Running 상태의 포드가 반드시 올바르게 작동한다는 의미는 아닙니다. 예를 들어 충분한 상태 프로브 (활성/준비)가 누락되어 애플리케이션 내부가 실패하더라도 실행 중으로 표시될 수 있습니다. 로그에는 포드가 실행 중인 것처럼 보여도 오류가 표시될 수 있습니다. 총 11개의 오류를 수정해야 합니다.
   • 👉💻 실패한 포드를 설명하여 이벤트를 확인합니다 ([POD_NAME]를 실제 포드 이름으로 바꿈).

     kubectl describe pod [POD_NAME]
     

   • 👉💻 실패한 포드의 로그를 확인하여 애플리케이션 오류를 확인합니다.

     kubectl logs [POD_NAME]
     

3. 탐정 작업: Cloud Shell 편집기에서 kubernetes-manifests/의 매니페스트를 열거나 터미널에서 cat을 엽니다. 로그와 이벤트에 표시되는 오류를 YAML 파일의 구성과 연관시켜 보세요.챌린지: 오류 하나만 수동으로 수정해 보세요. 실패 체인의 나머지 부분을 파악하기 위해 파일 간에 이동해야 하는 것을 확인할 수 있습니다.

4. 1단계: 웹에 질문하기 (Gemini 웹 UI)

수동 문제 해결은 속도가 느리므로 AI 어시스턴트를 사용해 보겠습니다. Gemini 웹 애플리케이션은 강력한 범용 채팅 인터페이스입니다. 개념을 설명하고 코드 스니펫을 생성하는 데 탁월합니다. 하지만 특정 환경에 대한 컨텍스트가 전혀 없습니다. 파일을 보거나, 클러스터를 검사하거나, 명령어를 실행할 수 없습니다. 오류 메시지와 파일 콘텐츠를 수동으로 복사하여 붙여넣어야 합니다.

1. Gemini로 이동: 새 탭에서 gemini.google.com을 엽니다. 자신의 Google 계정으로 로그인해야 합니다.
2. 특정 오류에 대한 도움 요청: userservice 포드에 ImagePullBackOff 오류가 표시된다고 말합니다.
   👉💬 Gemini 웹 UI에 다음 프롬프트를 입력합니다.
   My Kubernetes deployment for 'userservice' is failing with ImagePullBackOff. Here is the image name: us-central1-docker.pkg.dev/bank-of-anthos-ci/bank-of-anthos/user-service:v0.6.9. What is wrong?
3. AI의 대답: Gemini는 일반적인 원인 목록을 제공합니다.
   • 이미지가 없습니다.
   • 풀할 권한이 없습니다.
   • 오타가 있습니다.
   레지스트리 또는 IAM 권한을 확인하라는 메시지가 표시됩니다. 하지만 프로젝트를 보지 않는 한 실제 이미지 이름이 userservice (하이픈 없음)인지 알 수 없습니다.

여기서 주요 문제점은 Gemini가 로컬 환경을 파악할 수 없다는 것입니다. 필요한 컨텍스트를 얻으려면 프롬프트를 사용하고 텍스트를 복사하여 붙여넣는 방식으로 수동으로 제공해야 하는데, 이는 시간이 많이 걸리고 오류가 발생하기 쉽습니다.

5. 2단계: 터미널 기능 (Gemini CLI)

이제 Gemini CLI를 사용하여 터미널로 이동합니다. Gemini CLI를 사용하면 Gemini 모델의 기능을 터미널에서 바로 사용할 수 있습니다. CLI는 작업 환경에 있습니다. 로컬 파일을 읽고, 파이프된 입력을 허용하며, 사용자의 승인을 받아 셸 명령어를 대신 실행하기도 합니다. 따라서 컨텍스트를 전환하지 않고 워크플로에 AI를 통합하는 데 매우 유용합니다. 자세한 정보와 고급 사용법은 공식 Gemini CLI 문서를 참고하세요.

참고: 현재 Antigravity CLI가 공식적으로 출시되었으며 Gemini CLI의 후속 제품입니다. 이 실습에서는 계속해서 Gemini CLI를 사용합니다. Antigravity CLI에 대한 자세한 내용은 공식 Antigravity CLI 문서를 참고하세요.

컨텍스트 및 가시성

안내를 살펴보기 전에 Gemini CLI의 프로젝트 가시성은 실행 위치에 따라 달라집니다. 모델은 현재 작업 디렉터리를 기준으로 파일과 폴더를 볼 수 있습니다. 프로젝트의 루트에서 실행하면 해당 프로젝트의 모든 파일에 액세스할 수 있습니다. 하위 디렉터리에서 실행하면 뷰가 해당 하위 디렉터리와 그 하위 요소로 제한됩니다. 모델에 파일 분석 또는 수정을 요청하기 전에 항상 올바른 디렉터리에 있는지 확인하세요.

Gemini CLI 시작

Cloud Shell에는 기본적으로 Gemini CLI가 포함되어 있습니다. 시작하기만 하면 로컬 파일과 함께 사용할 수 있습니다.

1. Cymbal Bank 디렉터리로 이동합니다.
   👉💻 다음 명령어를 실행하여 올바른 디렉터리에 있는지 확인합니다.

   cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/cymbal-bank
   

2. Gemini CLI 시작:
   👉💻 다음 명령어를 실행하여 Gemini CLI를 시작합니다.

   gemini
   

Gemini CLI 사용

이 애플리케이션에 대해 아는 것은 코드의 위치와 실패한다는 것뿐입니다. 자세히 알아보고 Gemini가 애플리케이션을 수정하는 데 어떻게 도움이 되는지 살펴보겠습니다. 먼저 볼 수 있어야 하는 애플리케이션 파일에 관해 질문하여 컨텍스트를 탐색하는 기능을 테스트해 보세요.

1. 코드베이스 탐색: Gemini에게 이 애플리케이션이 무엇이고 어떤 작업을 하는지 설명해 달라고 요청합니다.
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   What is this application and what does it do?
   Gemini CLI가 현재 디렉터리의 파일을 읽고 프로젝트의 개요를 제공합니다.
2. 코드베이스에서 문제 찾기: Gemini CLI가 파일을 볼 수 있으므로 불일치를 찾아 달라고 요청합니다.
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   The contacts service pod is running, but I can't reach the service. Review kubernetes-manifests/contacts.yaml and check for common issues
   Gemini CLI가 파일을 읽고 app: contacts-backend와 app: contacts 간의 불일치를 발견합니다. 이는 이전 단계에 비해 큰 발전입니다.
3. 수정 요청:
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   Fix the label mismatch in contacts.yaml so the service matches the deployment.
   Gemini CLI에 수정된 YAML이 표시되거나 명령어를 승인하면 변경사항이 적용됩니다.
4. 제한사항: 파일을 볼 수는 있지만 클러스터에서 실제로 실행되는 항목을 알지는 못합니다. 정적 YAML에서 명확하지 않은 런타임 오류로 인해 포드가 실패하는 경우 로그나 클러스터 상태가 없으면 지원할 수 없습니다.

참고: Gemini CLI는 명령어를 실행하거나 파일을 수정할 때 동의를 요청합니다. 이렇게 하면 환경을 계속 제어할 수 있습니다. 아래와 같은 프롬프트가 표시되면 'Enter' 키를 눌러 '1. '한 번 허용'을 선택합니다. 아래쪽 화살표 키를 탭하고 Enter 키를 눌러 '2. 이 세션 허용'을 선택하면 이 대화가 진행되는 동안 Gemini CLI가 항상 사용자의 허락을 요청하지 않고 독립적으로 해당 작업을 실행합니다. 하지만 Gemini CLI를 닫았다가 다시 열면 해당 권한이 더 이상 없으므로 작업을 수행하기 전에 다시 권한을 요청합니다.

참고: 막히거나 처음부터 다시 시도하려면 cymbal-bank 디렉터리에서 ../break.sh를 실행하여 언제든지 Kubernetes 매니페스트를 초기 깨진 상태로 재설정하세요.

참고: 사용량 한도에 도달하면 '중지'를 선택한 다음 /model을 실행하여 한도에 도달한 모델을 확인하고 gemini-2.5-flash-lite와 같은 다른 모델로 전환합니다. 그런 다음 '계속'으로 모델에 프롬프트를 표시하여 새 모델을 사용하여 실습을 계속합니다.

6. 3단계: 전체 컨텍스트 디버깅 (Gemini CLI + GKE MCP)

2단계에서는 AI가 파일을 볼 수 있을 때 얼마나 강력해질 수 있는지 보여주었지만, 소음도 많았습니다. 복잡한 디버그 세션 중에 상당한 마찰을 일으키는 모든 파일 읽기 및 도구 작업을 수동으로 승인해야 했습니다. 3단계에서는 이 문제를 해결하기 위해 GKE MCP 서버를 도입하여 AI에 직접적인 '인프라 인식'을 제공합니다. 이를 통해 Gemini는 수동 중단이 적은 로그, 이벤트, 메타데이터를 문제 해결하여 더 자동화되고 일관된 문제 해결 흐름을 만들 수 있습니다.

MCP란 무엇인가요?

MCP를 이해하려면 먼저 AI 세계의 도구 개념을 이해하는 것이 좋습니다. 도구는 기본적으로 LLM이 날씨 확인, 특정 스크립트 실행, 데이터베이스 쿼리와 같이 다른 방법으로는 액세스할 수 없는 작업을 실행하거나 데이터를 가져오는 데 사용할 수 있는 외부 함수 또는 애플리케이션입니다. 개별 도구는 강력하지만 다양한 AI 에이전트와 환경 간에 안전하고 일관되게 공유하는 것은 항상 어려운 일이었습니다. MCP는 이러한 도구를 호스팅하고 호환되는 AI 클라이언트에 노출할 수 있는 표준화된 플랫폼 역할을 하여 이 문제를 해결합니다.

모델 컨텍스트 프로토콜 (MCP)은 AI 모델이 외부 데이터 소스 및 도구에 안전하게 액세스할 수 있도록 지원하는 오픈소스 프로토콜입니다. MCP는 특정 도구 또는 데이터베이스마다 통합을 하드코딩하는 대신 모델이 환경과 상호작용할 수 있는 표준화된 방법을 제공합니다.

Gemini CLI 내에서 /mcp를 실행하여 Gemini CLI에서 사용할 수 있는 도구를 확인할 수 있습니다.

이 실습에서 GKE MCP 서버를 사용하면 Gemini CLI가 GKE 클러스터와 직접 상호작용할 수 있으므로 리소스를 검사하고, 로그를 읽고, 클러스터의 실시간 상태를 완전히 파악하여 문제를 디버깅할 수 있습니다. 이렇게 하면 AI가 정적 코드 분석기에서 인프라의 실시간 상태를 이해하는 능동적인 문제 해결 어시스턴트로 변환됩니다.

GKE MCP 확장 프로그램 구성

기본적으로 Gemini CLI는 범용 도구입니다. 구성 파일을 만들어 GKE MCP 서버를 구성합니다.

1. 👉💻 먼저 /quit를 입력하여 Gemini CLI를 종료합니다.
2. 👉💻 다음 명령어를 실행하여 확장 프로그램 디렉터리를 만듭니다.

   mkdir -p ~/.gemini/extensions/gke
   

3. 👉💻 다음 명령어를 실행하여 구성 파일을 만듭니다. 이 명령어는 파일에 PROJECT_ID를 자동으로 삽입합니다.

   cat << EOF > ~/.gemini/extensions/gke/gemini-extension.json
   {
     "name": "gke",
     "version": "1.0.0",
     "mcpServers": {
       "container": {
         "httpUrl": "https://container.googleapis.com/mcp",
         "authProviderType": "google_credentials",
         "oauth": {
           "scopes": ["https://www.googleapis.com/auth/container"]
         },
         "timeout": 30000,
         "headers": {
           "x-goog-user-project": "$PROJECT_ID"
         }
       }
     }
   }
   EOF
   

4. 👉💻 Gemini CLI 시작:

   gemini
   

5. Gemini CLI 내에서 /mcp를 입력하여 MCP 서버가 사용 설정되어 있는지 확인합니다.

클러스터 상태를 사용하여 디버그하도록 Gemini에 요청

1. 실패한 배포 디버그: 이제 Gemini에게 클러스터를 검사하고 발견된 내용을 기반으로 매니페스트를 수정해 달라고 요청합니다.
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   The frontend deployment is failing. Can you use your tools to check the logs and events of the pods, and then fix it?
   Gemini는 MCP 도구를 사용하여 백그라운드에서 kubectl 명령어를 호출합니다. ImagePullBackOff 오류를 확인하고 원인을 설명하며 올바른 해결 방법을 제안합니다.
2. 복잡한 문제 해결: 애플리케이션 수준 오류의 로그를 확인하도록 요청합니다.
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   Check the logs for the 'contacts' pod. Why is it failing to connect to the database?
   연결 거부 오류가 표시되고 config.yaml의 포트 불일치 또는 서비스 이름 불일치로 추적됩니다.
3. 반복: 0단계에서 발견한 다른 문제를 수정해 달라고 Gemini에 계속 요청합니다.
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   Check if the service 'contacts' is correctly routing traffic to its pods
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   Are there any pods failing due to resource limits?

참고: 막히거나 처음부터 다시 시도하려면 cymbal-bank 디렉터리에서 ../break.sh를 실행하여 언제든지 Kubernetes 매니페스트를 초기 깨진 상태로 재설정하세요.

7. 4단계: 팀 지원 (Agent Skills)

마지막으로 맞춤 에이전트 기술을 만들어 특정 요구사항에 맞게 AI의 기능을 확장하세요.

상담사 기술이란 무엇인가요?

에이전트 스킬은 전문 작업을 위해 AI 에이전트를 확장하는 요청 사항, 스크립트, 리소스 패키지입니다. 이를 통해 조직 표준을 성문화하고 복잡한 워크플로를 자동화할 수 있습니다. 스킬은 특정 디렉터리에 있으며 동작을 정의하는 SKILL.md 파일을 포함합니다. 스킬을 만들면 AI가 즉흥적으로 처리하는 대신 일관되고 반복 가능한 프로세스를 따릅니다.

일반적인 스킬 디렉터리는 다음과 같습니다.

my-skill/
├── SKILL.md          # Main instruction file (Required)
├── scripts/           # Helper scripts (Optional)
└── resources/         # Templates or data files (Optional)

Kubernetes 문제 해결 스킬 빌드

이러한 파일을 수동으로 만드는 대신 Gemini CLI는 자연어를 사용하여 스킬을 스캐폴딩하는 강력한 방법을 제공합니다.

방금 실행한 단계를 자동화하는 k8s-troubleshooter라는 스킬을 만들고 싶다고 가정해 보겠습니다.

1. 프롬프트를 통해 스킬 만들기: 오늘 학습한 내용을 바탕으로 Gemini CLI에 스킬을 만들어 달라고 요청할 수 있습니다.
   👉💬 Gemini CLI에 다음 프롬프트를 입력하세요.
   Create a new skill called 'k8s-troubleshooter' that helps diagnose issues with Kubernetes manifests and cluster state. It should be able to analyze pod logs, events, and resource descriptions to identify common deployment problems and configuration errors.
   도구를 호출하거나 작업을 실행할 때와 마찬가지로 Gemini CLI는 프롬프트로 인해 '스킬 생성기' 스킬이 활성화되었다고 알려줍니다. 이는 Gemini가 에이전트 스킬을 만들 수 있도록 Gemini CLI에 사전 구성된 스킬입니다.
   Gemini는 스킬 디렉터리를 만들 권한을 요청합니다. '1. 한 번 허용'을 선택하여 승인합니다.
   Gemini는 자동으로 다음 작업을 실행합니다.
   • ~/.gemini/skills/k8s-troubleshooter/에 디렉터리를 만듭니다.
   • 프롬프트를 기반으로 한 안내가 포함된 SKILL.md 파일을 생성합니다.
   • 표준 리소스 디렉터리를 만듭니다.
2. Gemini CLI 다시 시작:
   👉💻 Gemini CLI (/quit)를 닫은 다음 다시 시작합니다.

   gemini
   

3. 스킬이 로드되었는지 확인:
   👉💻 Gemini CLI 내에서 /skills를 입력하여 스킬이 활성 상태인지 확인합니다. 목록에 k8s-troubleshooter가 표시됩니다.
4. 실제 작동 방식: 이제 스킬을 호출합니다.
   👉💬 Gemini CLI에 다음 프롬프트를 입력합니다.
   Use the k8s-troubleshooter skill to find out why the contacts service is failing.
   AI는 즉흥적으로 대답하는 대신 SKILL.md의 구조화된 계획을 따르므로 결과가 더 일관됩니다.

연습: 자체 스킬 개념화하기

일상적인 워크플로를 생각해 보세요. 스킬로 자동화할 수 있는 반복적인 작업은 무엇인가요?

• 아이디어: 배포 전에 보안 권장사항에 따라 매니페스트를 감사하는 스킬
• 아이디어: 워크로드 유형에 따라 복잡한 GKE 클러스터 구성을 생성하는 스킬

8. 결론

이 실습에서는 다양한 수준의 AI 컨텍스트를 진행하여 클라우드 인프라와 상호작용하는 새로운 방법을 보여줍니다. 컨텍스트가 없는 상태에서 전체 인프라 컨텍스트 (Gemini CLI + GKE MCP)로 이동하면 AI 어시스턴트가 파일과 클러스터 상태를 볼 때 얼마나 더 효과적인지 확인할 수 있습니다.

실습 요약

• 컨텍스트의 중요성: 컨텍스트가 없는 AI 도구는 특정 코드베이스 문제를 해결할 수 없습니다.
• 터미널 컨텍스트: Gemini CLI를 사용하여 작업공간에서 직접 로컬 파일을 분석하고 구성 오류를 식별합니다.
• 전체 컨텍스트 디버깅: MCP와 함께 Gemini CLI를 사용하여 AI가 코드베이스 파일과 라이브 클러스터 상태를 상호 연관시켜 복잡한 문제를 진단하고 해결하도록 합니다.
• 확장성: 스킬과 스킬을 사용하여 조직의 지식을 코딩하는 방법을 알아봅니다.

삭제

지속적인 요금이 청구되지 않도록 하려면 정리 스크립트를 실행하세요. Qwiklabs에서 실습을 실행하는 경우에는 이 단계를 수행하지 않아도 됩니다.

👉💻 워크숍 디렉터리에서 다음 명령어를 실행합니다.

cd ~/devrel-demos/codelabs/ai-toolkit-lab-1/
./teardown.sh

다음 단계

다음은 추가로 읽어볼 만한 자료입니다.

• Gemini CLI 문서: Gemini CLI의 공식 문서입니다.
• GKE 문서: 모든 GKE 문서의 방문 페이지입니다.
• Google Cloud의 플랫폼 엔지니어링: Google Cloud에서 플랫폼 엔지니어링에 접근하는 방법에 관한 안내입니다.
• GKE의 AI 및 머신러닝: GKE에서 AI/ML 워크로드를 실행하는 방법에 관한 문서입니다.
• Google Cloud 아키텍처 센터: Google Cloud에서 워크로드를 빌드하기 위한 가이드 및 권장사항

9. 부록: 매니페스트 손상 해결 방법

문제가 발생하거나 오류를 확인하려면 manifests-broken/ 디렉터리에 도입된 중단 목록과 해결 방법을 참고하세요.

1. config.yaml의 잘못된 URL:
   • 오류: TRANSACTIONS_API_ADDR: "ledgerwriter::8080" (콜론 2개)
   • 이유: 애플리케이션이 주소를 파싱하지 못하여 연결 오류가 발생합니다.
   • 수정: "ledgerwriter:8080"로 다시 변경합니다.
2. contacts.yaml의 라벨이 일치하지 않음:
   • 오류: 서비스 선택기가 contacts 대신 app: contacts-backend로 설정되어 있습니다.
   • 이유: 서비스가 포드 (여전히 app: contacts 있음)를 찾을 수 없으므로 트래픽이 라우팅되지 않습니다.
   • 수정: 선택기를 app: contacts로 변경합니다.
3. userservice.yaml의 포트 불일치:
   • 오류: 서비스 targetPort이(가) 8080 대신 8081로 설정되었습니다.
   • 이유: 서비스로 전송된 트래픽이 잘못된 컨테이너 포트로 전달되어 연결이 거부됩니다.
   • 수정: targetPort를 8080로 다시 변경합니다.
4. config.yaml에서 서비스 이름이 일치하지 않음:
   • 오류: BALANCES_API_ADDR: "balance-reader:8080" (balancereader 대신)
   • 이유: 서비스 이름이 balancereader이므로 호스트 이름이 DNS에서 확인되지 않습니다.
   • 수정: "balancereader:8080"로 다시 변경합니다.
5. contacts.yaml의 이미지 가져오기 정책:
   • 오류: imagePullPolicy: Never.
   • 이유: K8s는 레지스트리에서 이미지를 가져오지 않고 로컬이라고 가정합니다. ErrImagePull로 실패합니다.
   • 수정: 선을 삭제하거나 IfNotPresent로 설정합니다.
6. userservice.yaml의 준비 프로브 실패:
   • 오류: 경로가 /ready 대신 /healthz로 변경되었습니다.
   • 이유: 컨테이너가 /healthz를 제공하지 않으므로 프로브가 실패하고 포드가 준비됨으로 표시되지 않습니다.
   • 수정: 경로를 /ready로 다시 변경
7. contacts.yaml의 리소스 한도:
   • 오류: 메모리 제한이 128Mi 대신 10Mi로 설정되었습니다.
   • 이유: 앱을 시작하는 데 더 많은 메모리가 필요하여 OOMKill됩니다.
   • 수정: 메모리 한도를 복원합니다.
8. frontend.yaml에 환경 변수가 누락됨:
   • 오류: REGISTERED_OAUTH_CLIENT_ID 환경 변수가 삭제되었습니다.
   • 이유: 예상되는 환경 변수가 누락되면 앱이 실패하거나 기능이 사용 중지될 수 있습니다.
   • 수정: 환경 변수 정의를 복원합니다.
9. frontend.yaml의 ConfigMap 키 불일치:
   • 오류: DEMO_LOGIN_USERNAME 대신 key: DEMO_USER
   • 이유: K8s가 ConfigMap에서 키를 찾을 수 없어 컨테이너가 시작되지 않습니다.
   • 수정: 키를 DEMO_LOGIN_USERNAME로 다시 변경합니다.
10. userservice.yaml의 이미지 이름에 오타가 있습니다.
    • 오류: userservice 대신 user-service
    • 이유: 이미지가 레지스트리에 없어 ImagePullBackOff가 발생합니다.
    • 수정: 이미지 이름을 수정합니다.
11. contacts.yaml의 서비스 계정 문제:
    • 오류: bank-of-anthos 대신 bank-of-anthos-sa
    • 이유: ServiceAccount가 존재하지 않거나 권한이 없습니다.
    • 수정: 올바른 ServiceAccount 이름을 사용합니다.