agents-cli 的 variables.tf 全解：8 个关键 Terraform 变量详解

agents-cli 的 variables.tf 全解：8 个关键 Terraform 变量详解

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli

一句话了解 agents-cli 与 variables.tf

agents-cli是 Google 开源的命令行工具，它把任意编码助手变成"Google Cloud 上创建、评估、部署 AI Agent 的专家"。其中 variables.tf 是整个 CI/CD 基础设施的"总开关"——一条agents-cli infra cicd命令背后，就是这 8 个关键 Terraform 变量在决定你的 Agent 部署到哪个项目、哪个区域、连哪个仓库。

8 个关键变量一览表

在动手之前，先花 30 秒扫一眼全局。这 8 个变量可以分成4 组，每组解决一类问题：

💡 命名规律很好记：2 个环境 ID + 1 个流水线 ID + 1 个区域 + 1 个名字 + 2 个仓库信息 + 1 个连接名。

变量详解：分组逐个讲

🏷️ 第 1 组：资源命名 ——project_name

variables.tf 第 15-19 行 定义了它：

variable "project_name" { type = string description = "Project name used as a base for resource naming" default = "{{ cookiecutter.project_name | replace('_', '-') }}" }

它是所有 GCP 资源的"命名基底"。比如 Cloud Build 触发器会直接叫pr-${var.project_name}、cd-${var.project_name}（见 build_triggers.tf）。默认值由脚手架自动生成——你把下划线写成什么样，Terraform 里就会自动替换成连字符。

📦 第 2 组：三个 GCP 项目 ID

这是新手最容易混淆的一组，其实职责非常清晰：

• staging_project_id：预发环境。合并代码后，流水线先部署到这里跑集成测试和负载测试。
• prod_project_id：生产环境。通过预发验证后，人工审批再部署到这里。
• cicd_runner_project_id：流水线自己"住"的项目——API 密钥、触发器、日志桶都建在这里（见 apis.tf）。

🎯最佳实践：三者可以是同一个项目 ID（快速验证），但生产环境强烈建议分开，实现环境隔离与独立的成本核算。agents-cli infra cicd通过--staging-project/--prod-project参数传入，详见 docs/src/guide/cicd.md。

🌍 第 3 组：部署区域 ——region

默认us-east1。它决定了 Cloud Build 连接、构建触发器、日志桶等资源的地理位置。选区口诀：离你的用户和数据源越近，延迟越低。改一个变量，全栈资源跟着走，非常省心。

🔗 第 4 组：仓库与连接三件套

三者组合成完整的仓库引用路径：projects/${cicd_runner_project_id}/locations/${region}/connections/${host_connection_name}/repositories/${repository_name}（见 build_triggers.tf 第 24 行）。

变量在哪里填？env.tfvars 模板帮你省心

好消息是：你几乎不需要手写这些变量。脚手架在生成项目时，会基于 env.tfvars 模板 自动生成一份填好大部分默认值的文件：

project_name = "my-agent-project" prod_project_id = "your-production-project-id" # ← 只需填这 3 行 staging_project_id = "your-staging-project-id" # ← cicd_runner_project_id = "your-cicd-project-id" # ← region = "us-east1"

之后执行agents-cli infra cicd --staging-project ... --prod-project ...，CLI 就会自动渲染 Terraform 模板并创建资源。

两个进阶变量，顺带认识一下

除了上述 8 个核心参数，variables.tf 里还有两组权限列表变量，它们由脚手架按你的技术选型自动生成：

• app_sa_roles：应用服务账号的角色。启用 BigQuery 分析会自动追加roles/bigquery.dataOwner等；
• cicd_roles/cicd_sa_deployment_required_roles：CI/CD 服务账号角色，按 Cloud Run / GKE 目标动态切换。

另外，单项目部署模板 single-project/variables.tf 更精简：只有project_name、project_id、region三个必改项，还多了一个telemetry_logs_filter——用来把 Agent 遥测日志导入 Cloud Logging，配合 OpenTelemetry 实现全链路可观测：

总结：5 分钟上手清单

1. 命名：确认project_name（自动生成，一般不用管）；
2. 三个项目 ID：staging / prod / cicd，快速验证可填同一个，生产请分开；
3. 区域：默认us-east1，按需修改；
4. 仓库三件套：owner、name、连接名，与你的 Git 仓库对齐；
5. 运行agents-cli infra cicd，剩下的交给 Terraform。

理解了这 8 个变量，你就掌握了 agents-cli 部署体系的地基——从此再看生成的 Terraform 配置，任何资源"住哪儿、叫什么、连谁"，一眼就能读懂。🚀

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli