从意图到基础架构：通过代理将应用迁移到 GKE

1. 简介

在此 Codelab 中，您将学习如何使用 AI 智能体自动执行复杂的基础设施迁移。您无需手动编写 Kubernetes 清单或运行自动化脚本，只需用自然语言表达您的意图，智能体就会使用 Model Context Protocol (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 中，我们将以 Gemma 为例，介绍如何在 GKE 上自行托管强大的开放模型。将其暂存在 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 时收到“Permission denied”（权限遭拒）错误，可能需要通过运行 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。点击该网址，即可在浏览器中打开聊天机器人。您现在可以与聊天机器人互动，该聊天机器人目前基于 Gemini 2.5 Flash 运行。

下载模型

在此步骤中，我们将暂存 Cloud Storage 存储分区中的 Gemma 模型。虽然我们从托管式 Gemini API 开始，但您也可以选择运行自定义微调模型或其他自定义开放模型。或者，您可能只是出于安全或合规性考虑，希望在自己的集群中管理模型执行。在此处暂存模型，可为从受管理的 Gemini API 迁移到 GKE 上的自托管模型做好准备。

运行第 2 步，将 Gemma 模型下载到您的 GCS 存储分区。您需要 Hugging Face 令牌。此流程在您的 GKE 集群上运行，大约需要 15 分钟（或更长时间，具体取决于流量）才能从 Hugging Face 下载模型并将其上传到您的存储分区以供日后使用。

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

此 Terraform 命令会在 GKE 集群上创建一个 Kubernetes 作业来处理下载。只要作业在运行，Terraform 脚本就会保持有效状态。

如果您想从其他 shell 会话监控进度，或者在运行后验证是否已完成，可以运行：

kubectl get jobs

4. 设置代理和 MCP

现在，我们将配置执行迁移的代理。我们将使用 gemini-cli 并为其配备规则，以便与环境互动。

Gemini Cloud Assist (GCA) MCP 服务器是此流程的关键组成部分。它充当客户端代理与 Google Cloud 之间的桥梁，使客户端代理能够执行调查、生成计划（例如 gcloud 和 kubectl 命令），并直接对云项目中的资源应用更改。

确保您已被授予允许调用 MCP 工具的角色，例如 roles/geminicloudassist.user。如果您日后遇到权限问题，请参阅有关为 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 界面中启用变更功能。

1. 点击 Google Cloud 控制台窗口右上角的 Gemini 徽标，打开 Gemini Assist 侧边栏。
   
   
2. 启用边栏中列出的所有必要 API。
   
   
3. 前往边栏中的“设置”，然后勾选启用 Cloud Assist 以执行操作。
   
   
   

配置代理规则

项目目录在文件夹 (intent-to-infrastructure) 的根目录中包含一个自定义 gemini.md 文件。此文件包含用于引导代理使用正确工具的规则。

验证此文件是否存在于您的目录中。您应从此目录运行 gemini，以便其能够访问 Terraform 文件、应用代码和 gemini.md 规则文件。

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

（如果不同，则替换为代理生成的服务的实际名称）。

测试聊天机器人。它应该仍然会使用 Gemini API（如在 Cloud Run 中配置的那样）进行回答。

6. 第 2 步：通过 vLLM 部署 Gemma 并重新连接

在此步骤中，我们将使用代理在 GKE 上部署自托管的 Gemma 模型，并将应用重新连接到该模型。

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，以更改环境变量（或配置），使其指向新的 vLLM 服务，而不是 Gemini API。
   • 要求确认以应用更改。
3. 使用 yes 应用更改。

验证 - 第 2 步

1. 再次获取 pod 列表：

kubectl get pods

您现在应该会看到聊天机器人和 vLLM 的 Pod。

注意：即使 vLLM pod 处于 Running 状态，由于模型大小较大，服务器也可能需要长达 10 分钟的时间才能从存储分区中完全加载模型权重并开始提供服务。您可以通过查看日志来监控加载进度：

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

2. vLLM 准备就绪后，根据需要再次进行聊天机器人服务端口转发，然后进行测试。现在，它应该由您自托管的 Gemma 模型提供支持！

7. 清理

为避免系统向您的 Google Cloud 账号持续收取费用，请删除在此 Codelab 中创建的资源。

运行基础架构的销毁命令：

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。