使用 Antigravity CLI 和 SRE 扩展程序调查 GKE 中断问题，并构建精美的事后分析报告

1. 简介

856ff52e60953a92.png

上次更新时间： 2026-05-13

使用 SRE 扩展程序调查 GKE 中断问题并构建精美的事后分析报告

欢迎参加本次 SRE 研讨会，面向希望在 Google Cloud 上试用 SRE 框架的运维人员！

此 Codelab 将引导您完成以下操作：

  1. 安装基于知名开源 微服务演示 的 GKE 集群。
  2. 通过以不同方式（有些更引人注目，有些更细致）破坏集群来创建中断。
  3. 安装并使用 Antigravity CLI（或类似框架）+ SRE 扩展程序 进行后续操作。
  4. 调查并解决中断问题。
  5. 创建事后分析报告。
  6. 使用图表 技能 生成有依据的图表，让查看者了解发生了什么以及何时发生。

Codelab 的分步结构如下：

Codelab 结构图

本次研讨会的目标是：

  1. 展示 SRE 扩展程序的功能，并向您展示其功能：OneMCP 设置、安全执行器、调查、事后分析报告生成、图表和 CSV 摘要。
  2. 教您调查自己的 Google Cloud 场景的技能。

里程碑 1：环境设置和中断模拟

此里程碑的目标是在 GKE Autopilot 上设置 Kubernetes 演示应用，安装 Antigravity CLI，并人为触发 GKE 集群中断场景以模拟生产事件。

里程碑 2：使用 SRE 扩展程序进行调查和缓解

破坏环境后，您将使用配备 SRE 扩展程序的代理 CLI 工具来系统地发现基础架构、对问题进行分类、为修复实施安全执行模式，并验证集群健康状况。

里程碑 3：事后分析报告和图表生成

解决问题后，您将生成结构化事件事后分析报告文档，并使用 GCM (Google Cloud Monitoring) API 提取真实指标数据，创建可视化图表来记录中断发生的时间和方式。

构建内容

在此 Codelab 中，您将使用 SRE 扩展程序调查和修复 GKE 中断问题。您将：

  • 使用网络政策阻止、有 bug 的 Canary 部署和防火墙规则更新来模拟 GKE 中断。
  • 使用由 SRE 扩展程序提供支持的 CLI 助理对集群中断进行分类。
  • 使用安全执行器模式安全地实施修复步骤。
  • 生成全面的事后分析报告文档。
  • 使用 Google Cloud Monitoring 时序查询绘制突发事件指标图表。

学习内容

  • 如何使用 SRE 扩展程序技能检查 GKE Kubernetes 资源和政策。
  • 如何利用安全执行器模式运行代理建议的命令并进行适当的风险评估。
  • 如何使用 monitoring-graphs 技能直接从 GCM 生成有依据的指标图表。
  • 如何以结构化的事后分析报告格式记录事件发现结果。

所需条件

  • 启用了结算功能的 Google Cloud 项目。
  • 命令行工具：gcloud、kubectl、terraform。
  • 在本地或 Cloud Shell 中安装的 Antigravity CLI。
  • IDE（例如 vscode、IntelliJ、RubyMine 或 Vim）。

为什么选择 SRE 扩展程序 + 代理 CLI？

生产中断节奏快，需要跨多个子系统（Kubernetes 资源、VPC 网络、Cloud Monitoring 指标、IAM 权限）进行关联。SRE 扩展程序允许代理 CLI 帮助程序（例如 Antigravity CLI）充当自主副驾驶员，执行预编译的剧本、查询监控图表并建议安全修复，同时让人工运维人员参与其中。

2. 准备工作

请选择以下选项之一：如果您想在自己的机器上运行此 Codelab，请选择自定进度的环境设置 ；如果您想完全在云端运行此

Codelab，请选择启动 Cloud Shell 。

自定进度的环境设置

  1. 登录 Google Cloud 控制台，然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号，则必须 创建一个。

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • 项目名称 是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
  • 项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
  • 此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。
  1. 接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台 中，点击右上角工具栏中的 Cloud Shell 图标：

激活 Cloud Shell

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

Google Cloud Shell 终端的屏幕截图，显示环境已连接

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 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 设置相同，因此您的 Shell 体验与 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

此脚本将动态检测您的操作系统和架构，下载最新编译的

agy

二进制文件，并配置您的 PATH。重新启动终端或重新加载 Shell 配置，以使更改生效。

efade99623113f1.png

身份验证

您需要 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

设置工作环境并部署微服务演示应用

我们来克隆微服务演示应用，并通过 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 ADDRESS] 并加载 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 来模拟前端与结账服务之间的连接中断。

  1. 转到场景文件夹： 
    cd breakage1-checkout
  2. 触发中断： 
    ./break.sh
    这会在 default 命名空间中创建一个名为 update-checkout-from-frontend 的 NetworkPolicy，该政策会拒绝向 checkoutservice 的入站流量，除非该流量来自带有标签 app: frontend-checkout-test（不存在）的 pod。
  3. 尝试在 Online Boutique 前端购买商品。结账页面将挂起或显示 HTTP 500 错误。

场景 2：有 bug 的 Canary 发布（使用 Istio 的 Autopilot）

此场景模拟了通过 Kubernetes Canary 部署发布有 bug 的前端版本的错误部署。

  1. 转到场景文件夹： 
    cd ../breakage2-canary
  2. 触发中断： 
    ./break.sh
    这会部署一个 Canary 部署 frontend-canary，其环境变量中存在拼写错误：PRODUCT_CATALOG_SERVICE_ADDR 配置为 productcatalogservices:3550 而不是 productcatalogservice:3550。
  3. 加载前端首页。它偶尔会失败（取决于路由权重），因为 Canary 服务无法解析产品目录。

场景 3：VPC 防火墙集群阻止

此场景模拟了 VPC 防火墙配置中的错误，该错误会阻止所有向 GKE 集群的入站流量。

  1. 转到场景文件夹： 
    cd ../breakage3-firewall
  2. 触发中断： 
    ./break.sh
    这会创建一个名为 frontend-ingress-v2 的 VPC 级防火墙规则，其 priority=1 和操作 DENY 针对端口 80、443 和 8080 的入站流量。
  3. Online Boutique 网站将完全无法访问，并且请求将超时。

5. 第 2 步：使用 SRE 扩展程序调查中断问题

现在应用已停机，我们来使用 CLI 助理 (Antigravity CLI) 开始调查。

  1. 返回到主要中断场景文件夹并启动 CLI 帮助程序： 
    cd ..
agy
  2. 让助理执行基础架构发现和诊断检查： 
    Investigate my GKE cluster for outages. Are all services healthy?
  3. 代理的工作内容：
    • 它会激活 investigation-entrypoint 和 gcp-playbooks 技能。
    • 它会列出 Kubernetes pod、部署和服务，以找到失败的目标。
    • 它会检查网络政策（对于场景 1）或部署配置（对于场景 2）或防火墙规则（对于场景 3）。
  4. 对于场景 1，代理应报告：🔴 已发现事件：名为 update-checkout-from-frontend 的 NetworkPolicy 正在隔离 checkoutservice pod。
  5. 对于场景 2，代理应报告：🔴 已发现事件：部署 frontend-canary 配置了无效的服务端点 productcatalogservices:3550 而不是 productcatalogservice:3550。
  6. 对于场景 3，代理应报告：🔴 已发现事件：VPC 防火墙规则 frontend-ingress-v2 正在拒绝端口 80、443 和 8080 上的入站流量。

6. 第 3 步：缓解和修复中断问题

我们来使用 CLI 的安全执行器模式来修复中断问题。

  1. 让 CLI 助理提出并应用修复方案： 
    Propose a fix for the outage and apply it.
  2. 安全执行器实操：
    • 在执行命令建议之前，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
  3. 在 CLI 提示时确认命令执行。
  4. 刷新 Online Boutique 首页，验证网站是否已恢复正常运行。
  5. 在 Shell 中，您可以运行相应的场景检查脚本来验证健康状况： 
    ./breakage1-checkout/check.sh
# or ./breakage2-canary/check.sh
# or ./breakage3-firewall/check.sh

7. 第 4 步：生成事件事后分析报告

SRE 生命周期的一个重要部分是记录突发事件，以便团队可以从中学习。我们来使用 postmortem-create 技能自动执行此操作。

  1. 在 CLI 助理中，让其编写事后分析报告文档： 
    Create a postmortem for the checkout service network policy outage.
  2. 代理将收集以下详细信息：
    • 突发事件的开始时间（从 CLI 命令历史记录/日志中检索）。
    • 根本原因（阻止 NetworkPolicy）。
    • 为缓解问题而采取的操作。
  3. 它将在您的工作区中编写一个名为 postmortem.md 的新 Markdown 文件。
  4. 打开 postmortem.md 以查看详细信息。您将看到以下部分：
    • 事件摘要
    • 事件时间表
    • 根本原因分析 (RCA)
    • 待办项 / 预防措施

8. 第 5 步：添加有依据的指标图表

为了使事后分析报告更专业，我们需要事件的视觉证据。我们将使用 monitoring-graphs 技能从 Google Cloud Monitoring (GCM) 提取时序数据，并生成显示错误峰值的 PNG 图表。

  1. 让 CLI 帮助程序生成图表并将其添加到事后分析报告中： 
    Query GCM for frontend HTTP request error rates over the last 1 hour, generate a line chart, and embed it into postmortem.md.
  2. 深入了解：
    • 代理会调用 monitoring-graphs Python 脚本来查询 Cloud Monitoring。
    • 它会提取指标（例如 kubernetes.io/container/restart_count 或 loadbalancing.googleapis.com/https/request_count）。
    • 它会使用 matplotlib 绘制图表，并将其另存为 incident_metrics.png。
    • 它会通过插入图片链接来更新 postmortem.md 文件： 
      ![Incident Metric Graph](incident_metrics.png)
  3. 打开生成的 incident_metrics.png 文件，查看说明集群停机和流量恢复正常的具体时间的图表。

9. 第 6 步：清理

为确保您的 Google Cloud 账号不会产生不必要的费用，我们来清理已部署的基础架构。

  1. 转到 Terraform 文件夹： 
    cd ../../microservices-demo/terraform
  2. 运行 destroy 命令： 
    terraform destroy -auto-approve
  3. 验证是否已成功删除所有 GCP GKE 资源。

10. 恭喜！

您已完成 GKE 集群中断和中断调查 Codelab！

所学内容：

  • 将 10 层 Online Boutique 微服务演示部署到 GKE。
  • 模拟了三个真实的 SRE 中断（网络政策拒绝、有 bug 的 Canary 发布、VPC 防火墙规则拒绝）。
  • 使用 Antigravity CLI 的 SRE 扩展程序发现并诊断中断问题。
  • 利用安全执行器模式查看和执行修复命令。
  • 创建了专业的 Markdown 事后分析报告。
  • 查询了 Cloud Monitoring 指标，以自动生成和嵌入有依据的突发事件图表。

如需详细了解如何扩展 CLI 代理，请查看 SRE 扩展程序 GitHub 页面。