genmedia-for-commerce 基础设施部署指南Cloud Run 与 Agent Runtime 双目标 Terraform 实践【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本指南以 ADK 示例项目 genmedia-for-commerce 的 infra/README.md 为骨架系统讲解如何为电商媒体生成智能体ADK agent REST API MCP server React 前端在 Google Cloud 上落地基础设施。你将掌握make deploy与make deploy-agent-engine两条部署路径的取舍、Terraform 各资源文件的职责与参数含义以及从agents-cli scaffold enhance到手工terraform apply的完整实操流程。一、两种部署目标先想清楚要部署什么genmedia-for-commerce 不是单一的 agent而是一个由 ADK 智能体、REST APIVTO 虚拟试穿、spinning 旋转展示等、MCP server 和 React 前端组成的完整应用。因此infra/目录同时承载了两套部署语义部署文档 将它们划分为两个目标对比维度Cloud Runmake deployAgent Runtimemake deploy-agent-engine部署内容完整应用ADK agent REST API MCP server React 前端仅 ADK agent会话式对话接口打包方式使用 Dockerfile 构建容器gcloud run deploy --source .无需 Dockerfile源码直接打包上传适用场景完整应用部署、自定义基础设施、事件驱动工作负载托管基础设施、极简运维、纯 agent 部署入口模块genmedia4commerce/fast_api_app.pygenmedia4commerce/agent_engine_app.py关键限制—REST API 端点VTO、spinning 等不包含在内仍需要 Cloud Run 支撑Cloud Run 路径的入口 fast_api_app.py 是一个三合一组合应用通过adk的get_fast_api_app挂载 ADK agent APIchat、sessions 等通过mcp_server路由暴露 REST 端点再托管前端静态文件——这解释了为什么它代表完整应用。二、两种上手路径CLI 脚手架 vs 手工 Terraform文档推荐的路径是使用 agents-cli 自动完成基础设施与 CI/CD 的搭建# 在项目根目录执行 agents-cli scaffold enhance . --cicd-runner github_actions该命令会自动生成 GitHub Actions CI/CD 流水线所需的资源与配置。若你想完全掌控每一步也可以跳过脚手架手工执行 Terraform。无论选择哪条路径底层的 Terraform 配置都位于 infra/terraform/ 目录两者殊途同归。手工部署的完整命令链仓库的 Makefile 已将手工流程封装为四个目标可对照阅读# 1. 一次性初始化基础设施创建 Artifact Registry、Cloud Run、IAM 绑定 make setup-infra # 2. 预览将要发生的变更等价于 terraform plan make tf-plan # 3. 全量部署到 Cloud Run完整应用通过 Cloud Build 构建镜像 make deploy-cloudrun # 4. 仅将 ADK agent 部署到 Agent Runtime源码直传无容器 make deploy-agent-engine # 5. 清理基础设施 make tf-destroy其中setup-infra的实现值得注意它先校验config.env存在设置 gcloud 项目然后通过一段TF_VARS宏把config.env中的PROJECT_ID、DEFAULT_REGION、SERVICE_NAME、MEMORY、CPU、TIMEOUT、CONCURRENCY、MIN_INSTANCES、MAX_INSTANCES导出为TF_VAR_*环境变量再执行terraform init terraform apply。这意味着你只需要维护一份config.envTerraform 变量会自动与之同步无需重复编辑terraform.tfvars。三、Terraform 资源清单与逐文件解读infra/terraform/共包含 8 个文件职责划分非常清晰main.tfprovider 与 API 启用variables.tf全部输入变量及默认值cloudrun.tfCloud Run v2 服务iam.tf服务账号与角色绑定artifact_registry.tfDocker 镜像仓库storage.tf媒体存储桶outputs.tf部署产物输出terraform.tfvars.example变量填写模板3.1 provider 与 API 预启用main.tfmain.tf 要求 Terraform 1.0.0同时声明hashicorp/google与hashicorp/google-beta两个 provider均要求 5.0.0后者用于 IAP、service identity 等 beta 特性。最关键的是它会一次性启用 11 个 GCP APIcompute、cloudbuild、run、artifactregistry、aiplatform、 iap、cloudresourcemanager、storage、vision、iam、telemetry这些 API 与部署链路一一对应run托管 Cloud Run、artifactregistry承载镜像、aiplatform支撑 Agent Engine 与 AI 推理、vision服务视觉相关的 VTO/分类能力、iap用于身份代理鉴权、telemetry对接遥测日志。disable_on_destroy false意味着销毁基础设施时不会顺带停用 API。3.2 输入变量与默认值variables.tfvariables.tf 定义了全部参数结合 terraform.tfvars.example 可直接套用变量默认值说明project_id无必填GCP 项目 IDregionus-central1Cloud Run / Cloud Build 区域service_namegenmedia-for-commerceCloud Run 服务名同时派生仓库名memory32GiCloud Run 内存配额媒体生成负载较重cpu8CPU 配额timeout3600请求超时秒长耗时生成任务需要大值concurrency7单实例最大并发请求数min_instances2最小实例数保证冷启动可控max_instances10最大实例数弹性上限模板文件同时给出两个可选配置auth_mode取值none/iam/iap默认iam用于选择鉴权模式iap_access_domain可在使用 IAP 时对整个域名放行。使用时按注释操作即可cp terraform.tfvars.example terraform.tfvars # 编辑 terraform.tfvars至少填入 project_id3.3 Cloud Run v2 服务定义cloudrun.tfcloudrun.tf 创建google_cloud_run_v2_service.main关键设计点ingress INGRESS_TRAFFIC_ALL允许所有流量入口缩放在min_instance_count/max_instance_count之间弹性伸缩image初始为占位符gcr.io/cloudrun/placeholder实际镜像由 Cloud Build 在部署时替换——因此lifecycle块声明了ignore_changes [template, client, client_version, invoker_iam_disabled]避免terraform apply回滚 Cloud Build 写入的镜像与模板注入PROJECT_ID与LOCATION两个环境变量cpu_idle false等价于关闭 CPU 节流对应--no-cpu-throttling确保长耗时生成任务期间 CPU 不被回收使用专用服务账号google_service_account.cloudrun.email运行。3.4 双服务账号的 IAM 设计iam.tfiam.tf 是本项目最值得研读的部分它围绕三类身份做最小权限绑定默认 Compute Engine SA*-computedeveloper.gserviceaccount.comgcloud run deploy --source构建时由 Cloud Build 使用授予storage.objectAdmin、artifactregistry.writer、logging.logWriter专用 Cloud Run SAgenmedia-cloudrun运行时身份授予aiplatform.user调用 AI 平台/Agent Engine、storage.objectAdmin读写媒体桶、logging.logWriter、iam.serviceAccountUserAI Platform 服务代理通过google_project_service_identity.aiplatform获取通用 AI Platform 服务账号并显式授予 Reasoning Engine 服务代理gcp-sa-aiplatform-restorage.objectAdmin这是 Agent Engine 运行时访问媒体文件的必要条件。这种构建身份 / 运行身份 / 平台服务代理三层分离的模式是生产级 agent 部署的安全基线。3.5 镜像仓库与媒体桶artifact_registry.tf / storage.tfartifact_registry.tf 创建${service_name}-repo的 DOCKER 格式仓库并内置清理策略keep-recent保留最近 10 个版本镜像防止存储无限膨胀。storage.tf 创建${project_id}-genmedia-for-commerce-media-payloads桶承载用户上传与 AI 输出媒体开启uniform_bucket_level_access true统一桶级访问控制force_destroy false保护数据不被误删。3.6 部署产物输出outputs.tfoutputs.tf 暴露 5 个关键输出service_urlCloud Run 访问地址、project_id、region、service_name、artifact_registry_repo形如${region}-docker.pkg.dev/${project_id}/${repo}以及cloudrun_service_account供 CI/CD 流水线消费。四、Makefile 部署目标的执行细节infra/README.md提到的两个目标在 Makefile 中均有完整实现可结合源码理解其差异make deploy先用uv export导出依赖到genmedia4commerce/app_utils/.requirements.txt再调用genmedia4commerce.app_utils.deploy以genmedia4commerce/agent_engine_app的agent_engine对象为入口部署到 Agent Runtime支持AGENT_IDENTITYtrue启用每 agent 独立 IAM 身份Preview并可用SECRETSKEYSECRET_ID,...注入密钥。make deploy-agent-engine是deploy的资源定制版额外通过--cpu8 --memory32Gi --min-instances2 --max-instances10 --container-concurrency7显式声明与 Terraform 默认值一致的资源配额并额外打包startup_scripts目录内含 OpenCV 修复脚本 fix_opencv.sh。make deploy-cloudrun走gcloud run deploy --source .参数与 Terraform 变量一一对应--memory/--cpu/--timeout/--concurrency/--min-instances/--max-instances绑定genmedia-cloudrun$PROJECT_ID.iam.gserviceaccount.com--no-allow-unauthenticated默认拒绝匿名访问--no-cpu-throttling与 Terraform 的cpu_idlefalse呼应传入USE_IAPtrue时追加--iap。五、上手建议与注意事项先跑 Agent Runtime 再跑 Cloud Run如果只是验证 agent 对话能力make deploy-agent-engine无需 Docker、链路最短需要 VTO、spinning 等 REST 端点或前端时再补 Cloud Run 部署。make setup-infra只跑一次它负责创建仓库、服务与 IAM 绑定后续迭代部署deploy-cloudrun会通过 Cloud Build 覆盖镜像无需重复执行。config.env是单一事实来源Makefile 通过TF_VARS宏将其同步为 Terraform 变量务必先cp config.env.example config.env并填写否则setup-infra会直接报错退出。鉴权默认是 IAM 模式--no-allow-unauthenticated意味着需要具备相应 IAM 权限的调用方才能访问需要浏览器直接访问时再评估 IAPauth_mode iap方案。资源配额不可随意调小媒体生成场景默认32Gi内存 /8CPU /3600s超时是模型推理与图像后处理的合理基线贸然缩小可能导致 OOM 或请求超时。六、小结genmedia-for-commerce 的infra/目录演示了 ADK 项目一基座双目标的部署范式一套 Terraform 配置同时支撑 Cloud Run完整应用与 Agent Runtime纯 agent两条路径通过 IAM 三层身份隔离、Artifact Registry 镜像保留策略、统一桶级访问控制等设计满足生产要求。无论你通过agents-cli scaffold enhance自动生成 CI/CD还是手工执行make setup-inframake deploy-cloudrun理解本指南中的变量映射与资源依赖都能让部署过程完全透明可控。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考