1. 소개
최종 업데이트: 2026년 5월 13일
SRE 확장 프로그램으로 GKE 서비스 중단을 조사하고 멋진 사후 분석 보고서 작성하기
Google Cloud에서 SRE 하네스를 실험하려는 운영자를 위한 SRE 워크숍에 오신 것을 환영합니다.
이 Codelab에서는 다음을 안내합니다.
- 잘 알려진 오픈소스 microservices-demo를 기반으로 GKE 클러스터를 설치합니다.
- 다양한 방식으로 중단을 만들어 보세요 (일부는 더 눈에 띄고 일부는 더 미묘함).
- 다음 부분을 위해 Antigravity CLI (또는 유사한 하네스) + SRE 확장 프로그램을 설치하고 사용합니다.
- 정전 문제를 조사하고 해결합니다.
- 사후 분석을 작성합니다.
- 그래프 작성 기술을 사용하여 시청자가 무슨 일이 언제 일어났는지 이해할 수 있는 근거가 있는 그래프를 생성합니다.
다음은 Codelab의 단계별 구조입니다.
이 워크숍의 목표는 다음과 같습니다.
- SRE 확장 프로그램의 기능을 시연하고 OneMCP 설정, Safe Executor, 조사, 사후 분석 생성, 그래프, CSV gist와 같은 기능을 보여줍니다.
- 자체 Google Cloud 시나리오를 조사하는 데 필요한 기술을 알려줍니다.
마일스톤 1: 환경 설정 및 서비스 중단 시뮬레이션
이 마일스톤의 목표는 GKE Autopilot에 Kubernetes 데모 애플리케이션을 설정하고, Antigravity CLI를 설치하고, 프로덕션 인시던트를 시뮬레이션하기 위해 GKE 클러스터 중단 시나리오를 인위적으로 트리거하는 것입니다.
마일스톤 2: SRE 확장으로 조사 및 완화
환경을 중단한 후 SRE 확장 프로그램이 장착된 에이전트 CLI 도구를 사용하여 인프라를 체계적으로 검색하고, 문제를 분류하고, 수정사항에 대한 안전한 실행 패턴을 구현하고, 클러스터 상태를 확인합니다.
마일스톤 3: 사후 분석 및 그래프 생성
문제가 해결되면 구조화된 사고 사후 분석 문서를 생성하고 GCM (Google Cloud Monitoring) API를 사용하여 실제 측정항목 데이터를 가져와 서비스 중단이 언제 어떻게 발생했는지 문서화하는 시각적 차트를 만듭니다.
빌드할 항목
이 Codelab에서는 SRE 확장 프로그램을 사용하여 GKE 서비스 중단을 조사하고 수정합니다. 실습할 내용은 다음과 같습니다.
- 네트워크 정책 차단, 버그가 있는 카나리아 배포, 방화벽 규칙 업데이트를 사용하여 GKE 중단을 시뮬레이션합니다.
- SRE 확장 프로그램으로 구동되는 CLI 어시스턴트를 사용하여 클러스터 서비스 중단을 분류합니다.
- 안전한 실행기 패턴을 사용하여 해결 단계를 안전하게 구현합니다.
- 포괄적인 사후 문서를 생성합니다.
- Google Cloud Monitoring 시계열 쿼리를 사용하여 사고 측정항목을 그래프로 표시합니다.
학습할 내용
- SRE 확장 기술을 사용하여 GKE Kubernetes 리소스 및 정책을 검사하는 방법
- 안전한 실행기 패턴을 활용하여 적절한 위험 평가를 통해 에이전트 추천 명령어를 실행하는 방법
monitoring-graphs스킬을 사용하여 GCM에서 직접 근거가 있는 측정항목 차트를 생성하는 방법- 구조화된 사후 분석 형식으로 사고 발견 항목을 문서화하는 방법
필요한 항목
- 결제가 사용 설정된 Google Cloud 프로젝트
- 명령줄 도구:
gcloud,kubectl,terraform - Antigravity CLI가 로컬 또는 Cloud Shell에 설치되어 있어야 합니다.
- IDE (예: vscode, IntelliJ, RubyMine, Vim)
SRE 확장 프로그램 + 에이전트 CLI가 필요한 이유
프로덕션 중단은 빠르게 진행되며 여러 하위 시스템 (Kubernetes 리소스, VPC 네트워크, Cloud Monitoring 측정항목, IAM 권한) 간의 상관관계가 필요합니다. SRE 확장 프로그램을 사용하면 에이전트 CLI 도우미 (예: Antigravity CLI)가 자율 부조종사 역할을 하여 사전 컴파일된 플레이북을 실행하고, 모니터링 그래프를 쿼리하고, 안전한 해결 방법을 제안하면서 인간 운영자를 계속 참여시킬 수 있습니다.
2. 설정
다음 옵션 중 하나를 선택합니다. 이
자체 머신에서 Codelab을 실행하는 경우 Cloud Shell을 시작합니다. 클라우드에서 Codelab을 완전히 실행하려면 Cloud Shell을 시작합니다.
자습형 환경 설정
- Google Cloud Console에 로그인하여 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 아직 Gmail이나 Google Workspace 계정이 없는 경우 계정을 만들어야 합니다.
- 프로젝트 이름은 이 프로젝트 참가자의 표시 이름입니다. 이는 Google API에서 사용하지 않는 문자열이며 언제든지 업데이트할 수 있습니다.
- 프로젝트 ID는 모든 Google Cloud 프로젝트에서 고유하며, 변경할 수 없습니다(설정된 후에는 변경할 수 없음). Cloud 콘솔은 고유한 문자열을 자동으로 생성합니다. 일반적으로는 신경 쓰지 않아도 됩니다. 대부분의 Codelab에서는 프로젝트 ID (일반적으로
PROJECT_ID로 식별됨)를 참조해야 합니다. 생성된 ID가 마음에 들지 않으면 다른 임의 ID를 생성할 수 있습니다. 또는 직접 시도해 보고 사용 가능한지 확인할 수도 있습니다. 이 단계 이후에는 변경할 수 없으며 프로젝트 기간 동안 유지됩니다. - 참고로 세 번째 값은 일부 API에서 사용하는 프로젝트 번호입니다. 이 세 가지 값에 대한 자세한 내용은 문서를 참고하세요.
- 다음으로 Cloud 리소스/API를 사용하려면 Cloud 콘솔에서 결제를 사용 설정해야 합니다. 이 Codelab 실행에는 많은 비용이 들지 않습니다. 이 튜토리얼이 끝난 후에 요금이 청구되지 않도록 리소스를 종료하려면 만든 리소스 또는 프로젝트를 삭제하면 됩니다. Google Cloud 신규 사용자는 300달러(USD) 상당의 무료 체험판 프로그램에 참여할 수 있습니다.
Cloud Shell 시작
Google Cloud를 노트북에서 원격으로 실행할 수 있지만, 이 Codelab에서는 Cloud에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다.
Google Cloud Console의 오른쪽 상단 툴바에 있는 Cloud Shell 아이콘을 클릭합니다.
환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 완료되면 다음과 같이 표시됩니다.
가상 머신에는 필요한 개발 도구가 모두 들어있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab의 모든 작업은 브라우저 내에서 수행할 수 있습니다. 아무것도 설치할 필요가 없습니다.
3. 기본 요건 (설치)
이 튜토리얼에서는 다음을 설치해야 합니다.
1. Python 및 uv
python 및 uv (Python용 패키지 관리자) uv가 설치되어 있는지 확인합니다.
$ curl -LsSf https://astral.sh/uv/install.sh | sh
uv를 사용해야 하는 이유 원하는 Python 관리자를 사용할 수 있지만 uv를 사용하면 사용자와 Antigravity CLI의 Python ENV/PATH 설정이 동일하므로 셸 환경이 Antigravity CLI와 거의 동일해집니다. 예를 들어 virtualenv를 사용하는 경우 Antigravity CLI는 환경을 모방하기 위해 'source .env/venv/bin/activate && my-original-command'와 같은 작업을 강제로 실행합니다.
2. Antigravity CLI (agy)
공식 Antigravity CLI (agy 명령어)를 설치하려면 터미널을 열고 부트스트랩 설치 프로그램을 실행하세요.
macOS 및 Linux:
$ curl -fsSL https://antigravity.google/cli/install.sh | bash
Windows (PowerShell):
irm https://antigravity.google/cli/install.ps1 | iex
이 스크립트는 OS와 아키텍처를 동적으로 감지하고, 최신 컴파일된
agy
바이너리를 다운로드하고 PATH를 구성합니다. 변경사항이 적용되도록 터미널을 다시 시작하거나 셸 구성을 새로고침합니다.
인증
Google AI Studio API 키가 필요합니다.
API 키를 내보냅니다.
export GEMINI_API_KEY="your-api-key"
gcloud로 인증합니다.
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
gcloud auth application-default login
작업 환경 설정 및 마이크로서비스 데모 애플리케이션 배포
microservices-demo 애플리케이션을 클론하고 Terraform을 통해 인프라와 애플리케이션을 배포해 보겠습니다.
이때 IDE (Visual Studio Code, IntelliJ, RubyMine 등)를 열고 폴더를 열면 됩니다.
# 1. Find an empty directory, and download this repo.
git clone https://github.com/GoogleCloudPlatform/microservices-demo.git
cd microservices-demo/terraform
# 2. Update project ID to your gcloud project ID
sed -i 's/<project_id_here>/YOUR_ACTUAL_PROJECT_ID/g' terraform.tfvars
# 3. Deploy the microservices-demo application in GKE autopilot
# If there is a prompt answer yes and continue. This step can take up to 10 mins for provision gke autopilot cluster and deploy microservices-demo application
terraform init
terraform plan
terraform apply
# 4. Verify the IP address of frontend-service to access the online-boutique application
kubectl get service frontend-external | awk '{print $4}'
# 5. Find an empty directory , and download this repo.
git clone https://github.com/palladius/sre-testing-suite.git
cd sre-testing-suite/test-scenarios/microservices-demo-gke/breakage-scenarios
설정을 테스트하려면 http://[IP 주소] 에 액세스하여 online-boutique 앱을 로드하면 됩니다.
sre-antigravity-cli-extension을 위한 작업 환경 설정
# 1. Install the SRE Extension plugin globally
git clone https://github.com/gemini-cli-extensions/sre.git ~/.gemini/config/plugins/sre-extension
# 2. Launch the Antigravity CLI (agy)
agy # This runs the CLI under your current breakage-scenarios folder.
# Login with your corporate or personal account when prompted.
# 3. Within the agy agent prompt, configure your MCP servers and GCP project
Use the gcp-mcp-setup skill to setup my GCP project "<gcp_project_id>" with email jane-doe-sre@credible-company.com
4. 1단계: 서비스 중단 시뮬레이션 (중단 시나리오)
이 단계에서는 실제 프로덕션 사고를 시뮬레이션하기 위해 배포된 GKE 클러스터를 의도적으로 중단합니다. 다음 세 가지 시나리오 중에서 선택하거나 세 가지를 모두 순서대로 시도할 수 있습니다.
시나리오 1: 결제 서비스 네트워크 차단 (스탠더드/Autopilot)
이 시나리오에서는 트래픽 '블랙홀' 역할을 하는 Kubernetes NetworkPolicy를 적용하여 프런트엔드와 체크아웃 서비스 간의 연결이 끊어진 상황을 시뮬레이션합니다.
- 시나리오 폴더로 이동합니다.
cd breakage1-checkout
- 손상을 트리거합니다.
./break.sh
default네임스페이스에update-checkout-from-frontend라는 NetworkPolicy가 생성됩니다. 이 NetworkPolicy는 라벨이app: frontend-checkout-test인 포드 (존재하지 않음)에서 들어오지 않는 한checkoutservice로의 인그레스 트래픽을 거부합니다. - Online Boutique 프런트엔드에서 상품을 구매해 봅니다. 결제 페이지가 멈추거나 HTTP 500 오류가 표시됩니다.
시나리오 2: 버그가 있는 카나리아 출시 (Istio를 사용하는 오토파일럿)
이 시나리오는 버그가 있는 프런트엔드 버전이 Kubernetes 카나리아 배포를 통해 출시되는 잘못된 배포를 시뮬레이션합니다.
- 시나리오 폴더로 이동합니다.
cd ../breakage2-canary
- 손상을 트리거합니다.
./break.sh
frontend-canary를 배포합니다.PRODUCT_CATALOG_SERVICE_ADDR이productcatalogservice:3550대신productcatalogservices:3550로 구성됩니다. - 프런트엔드 홈페이지를 로드합니다. 카나리아 서비스가 제품 카탈로그를 확인할 수 없기 때문에 라우팅 가중치에 따라 가끔 실패합니다.
시나리오 3: VPC 방화벽 클러스터 차단
이 시나리오는 GKE 클러스터로 향하는 모든 인그레스 트래픽을 차단하는 VPC 방화벽 구성의 실수를 시뮬레이션합니다.
- 시나리오 폴더로 이동합니다.
cd ../breakage3-firewall
- 손상을 트리거합니다.
./break.sh
80,443,8080로 들어오는 인그레스 트래픽을 타겟팅하는priority=1및 작업DENY이 있는frontend-ingress-v2라는 VPC 수준 방화벽 규칙이 생성됩니다. - Online Boutique 웹사이트에 완전히 액세스할 수 없게 되고 요청이 시간 초과됩니다.
5. 2단계: SRE 확장 프로그램을 사용한 서비스 중단 조사
이제 애플리케이션이 다운되었으므로 CLI 어시스턴트 (Antigravity CLI)를 사용하여 조사를 시작해 보겠습니다.
- 기본 손상 시나리오 폴더로 돌아가서 CLI 도우미를 실행합니다.
cd .. agy
- 어시스턴트에게 인프라 검색 및 진단 확인을 실행해 달라고 요청합니다.
Investigate my GKE cluster for outages. Are all services healthy? - 상담사가 하는 일:
investigation-entrypoint및gcp-playbooks스킬을 활성화합니다.- 실패한 타겟을 찾기 위해 Kubernetes 포드, 배포, 서비스를 나열합니다.
- 네트워크 정책 (시나리오 1) 또는 배포 구성 (시나리오 2) 또는 방화벽 규칙 (시나리오 3)을 검사합니다.
- 시나리오 1의 경우 상담사는 🔴 사고 확인됨:
update-checkout-from-frontend라는 이름의NetworkPolicy이checkoutservice포드를 격리하고 있다고 신고해야 합니다. - 시나리오 2의 경우 상담사는 🔴 문제 확인됨: 배포
frontend-canary이productcatalogservice:3550대신 잘못된 서비스 엔드포인트productcatalogservices:3550로 구성되어 있다고 신고해야 합니다. - 시나리오 3의 경우 에이전트는 🔴 문제 확인됨: VPC 방화벽 규칙
frontend-ingress-v2이 포트80,443,8080의 인그레스 트래픽을 거부하고 있다고 보고해야 합니다.
6. 3단계: 서비스 중단 완화 및 해결
CLI의 안전한 실행기 패턴을 사용하여 서비스 중단을 해결해 보겠습니다.
- CLI 어시스턴트에게 수정사항을 제안하고 적용하도록 요청합니다.
Propose a fix for the outage and apply it. - 실행 중인 안전한 Executor:
- 명령어 제안을 실행하기 전에 SRE 확장 프로그램은
safe-sre-investigator스킬을 사용하여 안전 감사 기능을 실행합니다. - 실행하려는 정확한 명령어를 표시하고 위험 수준 (예: 낮음, 중간, 높음)을 평가합니다.
- 시나리오 1의 경우 다음과 같이 제안합니다.
kubectl delete networkpolicy update-checkout-from-frontend
- 시나리오 2의 경우 다음과 같이 제안합니다.
kubectl delete deployment frontend-canary
- 시나리오 3의 경우 다음과 같이 제안합니다.
gcloud compute firewall-rules delete frontend-ingress-v2 --quiet
- 명령어 제안을 실행하기 전에 SRE 확장 프로그램은
- CLI에서 메시지가 표시되면 명령어 실행을 확인합니다.
- Online Boutique 홈페이지를 새로고침하여 웹사이트가 다시 작동하고 완전히 기능하는지 확인합니다.
- 셸에서 해당 시나리오 확인 스크립트를 실행하여 상태를 확인할 수 있습니다.
./breakage1-checkout/check.sh # or ./breakage2-canary/check.sh # or ./breakage3-firewall/check.sh
7. 4단계: 인시던트 사후 분석 생성
SRE 수명 주기의 필수적인 부분은 팀이 학습할 수 있도록 인시던트를 문서화하는 것입니다. postmortem-create 스킬을 사용하여 이 작업을 자동화해 보겠습니다.
- CLI 어시스턴트에서 사후 분석 문서 작성을 요청합니다.
Create a postmortem for the checkout service network policy outage. - 상담사는 다음 사항에 관한 세부정보를 수집합니다.
- 인시던트 시작 시간 (CLI 명령어 기록/로그에서 가져옴)
- 근본 원인 (차단 NetworkPolicy)
- 완화하기 위해 취한 조치
- 작업공간에
postmortem.md이라는 새 마크다운 파일이 작성됩니다. postmortem.md을 열어 세부정보를 검토합니다. 다음과 같은 섹션이 표시됩니다.- 사고 요약
- 변경 일정
- 근본 원인 분석 (RCA)
- 조치 항목 / 예방 조치
8. 5단계: 그라운딩된 측정항목 그래프 추가
사후 분석을 전문적으로 진행하려면 사고의 시각적 증거가 필요합니다. monitoring-graphs 스킬을 사용하여 Google Cloud Monitoring (GCM)에서 시계열 데이터를 가져오고 오류 급증을 보여주는 PNG 차트를 생성합니다.
- CLI 도우미에게 그래프를 생성하여 포스트모템에 추가하도록 요청합니다.
Query GCM for frontend HTTP request error rates over the last 1 hour, generate a line chart, and embed it into postmortem.md. - 작동 방식:
- 에이전트는
monitoring-graphsPython 스크립트를 호출하여 Cloud Monitoring을 쿼리합니다. - 측정항목 (예:
kubernetes.io/container/restart_count또는loadbalancing.googleapis.com/https/request_count)을 가져옵니다. matplotlib를 사용하여 차트를 그리고incident_metrics.png로 저장합니다.- 이미지 링크를 삽입하여
postmortem.md파일을 업데이트합니다.
- 에이전트는
- 생성된
incident_metrics.png파일을 열어 클러스터가 다운된 정확한 순간과 트래픽이 정상으로 돌아온 순간을 보여주는 차트를 확인합니다.
9. 6단계: 삭제
Google Cloud 계정에 불필요한 요금이 청구되지 않도록 배포된 인프라를 정리해 보겠습니다.
- Terraform 폴더로 이동합니다.
cd ../../microservices-demo/terraform
- 다음과 같이 destroy 명령어를 실행합니다.
terraform destroy -auto-approve
- 모든 GCP GKE 리소스가 성공적으로 삭제되었는지 확인합니다.
10. 수고하셨습니다
GKE 클러스터 손상 및 중단 조사 Codelab을 완료했습니다.
학습한 내용:
- 10계층 Online Boutique 마이크로서비스 데모를 GKE에 배포했습니다.
- 실제 SRE 중단 3건 (네트워크 정책 거부, 버그가 있는 카나리아 출시, VPC 방화벽 규칙 거부)을 시뮬레이션했습니다.
- Antigravity CLI용 SRE 확장 프로그램을 사용하여 서비스 중단을 발견하고 진단했습니다.
- 안전한 실행기 패턴을 활용하여 수정 명령어를 검토하고 실행했습니다.
- 전문적인 마크다운 사후 분석을 만들었습니다.
- 그라운딩된 사고 그래프를 자동으로 생성하고 삽입하기 위해 Cloud Monitoring 측정항목을 쿼리했습니다.
CLI 에이전트 확장에 관한 자세한 내용은 SRE 확장 프로그램 GitHub 페이지를 참고하세요.