Infrastructure as Code on Learning Notes

IaC Agent

Mon, 01 Jan 0001 00:00:00 +0000

通过自然语言生成 Infrastructure as Code #

核心场景：运维工程师通过 UI 界面提交自然语言需求，后端自动生成符合项目规范的 IaC 代码并提交到 Git 仓库。

技术栈：LLM + RAG（检索增强生成）+ Git + CI/CD

完整解决方案架构 #

┌─────────────────────────────────────────────────────────────────┐
│ UI 界面（Web） │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 需求提交 │ │ 任务状态 │ │ 代码预览 │ │
│ │ │ │ │ │ │ │
│ │ · 选择项目 │ │ · 排队中 │ │ · 生成的 .tf │ │
│ │ · 自然语言 │ │ · 生成中 │ │ · Diff 对比 │ │
│ │ 描述需求 │ │ · 验证中 │ │ · 一键复制 │ │
│ │ · 选择环境 │ │ · 待审批 │ │ │ │
│ │ · 提交 │ │ · 已合并 │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────┬────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 后端服务（API Server） │
│ │
│ 1. 接收需求 │
│ ├─ 解析自然语言需求 │
│ ├─ 识别目标项目（新/旧） │
│ └─ 确定代码结构 │
│ │
│ 2. 仓库分析 │
│ ├─ 克隆项目仓库 │
│ ├─ 提取上下文（modules/variables/tags） │
│ └─ 向量化存储（RAG） │
│ │
│ 3. 代码生成 │
│ ├─ 检索相关代码片段 │
│ ├─ 调用 LLM 生成代码（带上下文） │
│ └─ 格式化 + 路径规划 │
│ │
│ 4. 验证与集成 │
│ ├─ terraform fmt / validate / tflint / checkov │
│ ├─ 创建 Git 分支 │
│ ├─ 提交代码 │
│ └─ 创建 Pull Request │
│ │
│ 5. 状态更新 │
│ └─ 更新 UI 任务状态 + 通知运维工程师 │
└────────────────────┬────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ Git 仓库（按项目区分） │
│ │
│ project-a-infra/ project-b-infra/ new-project/ │
│ ├─ modules/ ├─ modules/ ├─ modules/ │
│ ├─ environments/ ├─ environments/ ├─ environments/ │
│ ├─ variables.tf ├─ variables.tf ├─ variables.tf │
│ └─ ... └─ ... └─ ... │
└─────────────────────────────────────────────────────────────────┘

核心需求场景 #

场景 1：已有项目，添加资源 #

运维工程师操作：
① UI 界面选择项目："project-a"
② 输入需求：
 "为生产环境添加 Redis 集群，3 节点，启用持久化，
 使用与现有 VPC 相同的网络配置"
③ 选择环境："production"
④ 点击"提交"

后端处理：
① 克隆 project-a-infra 仓库
② 分析现有结构（modules/vpc、modules/common）
③ 提取上下文（变量、标签、命名规范）
④ 生成 modules/redis/ 代码
⑤ 创建分支 feature/add-redis-cluster
⑥ 提交代码 + 创建 PR
⑦ UI 显示："代码已生成，PR #42 已创建，等待审批"

运维工程师后续操作：
① 查看生成的代码（UI 预览）
② Review PR
③ 批准 + 合并
④ CI/CD 自动执行 terraform plan
⑤ 确认后执行 terraform apply

场景 2：新项目，创建仓库 #

运维工程师操作：
① UI 界面选择项目："新建项目"
② 输入项目名称："project-x"
③ 输入需求：
 "VPC + 3 层架构（web/app/db）+ EKS 集群 + RDS PostgreSQL"
④ 点击"提交"

后端处理：
① 从模板仓库创建 project-x-infra
② 初始化项目结构（modules/、environments/）
③ 生成所有模块代码（VPC、EKS、RDS）
④ 验证 + 提交
⑤ UI 显示："项目已创建，代码已提交，PR #1 已创建"

运维工程师后续操作：
① 查看生成的完整代码
② Review + 合并
③ 执行 terraform apply
④ 基础设施就绪，开始使用

技术实现方案 #

方案 A：自研 Web 应用 + RAG（推荐） #

技术栈：

TACOS

Mon, 01 Jan 0001 00:00:00 +0000

TACOS (Terraform Automation and Collaboration Software) #

TACOS = Terraform Automation and COllaboration Software 专为 Terraform / OpenTofu 工作流设计的自动化与协作平台，将 CLI 工具升级为团队级基础设施管理平台。

为什么需要 TACOS？ #

团队规模增长后，纯 CLI + CI/CD 管理 Terraform 的痛点：

 ① 状态管理 → 分布式团队的状态文件存储、锁、版本控制
 ② 协作困难 → 多人修改、Plan 审查、Apply 审批流程复杂
 ③ 治理缺失 → 无法强制执行安全策略、合规检查、成本控制
 ④ 可见性差 → 缺乏"谁在何时对什么资源做了什么"的审计链
 ⑤ 漂移检测 → 云控制台手动变更后无法自动发现
 ⑥ 自助服务 → 开发者无法安全地自助创建/销毁测试环境

TACOS 核心功能 #

功能	说明
远程状态管理	安全存储 State 文件，提供锁机制防止并发修改，维护变更历史
VCS 集成	与 GitHub/GitLab/Bitbucket 集成，PR 驱动 GitOps 工作流
RBAC	细粒度权限控制（谁能在哪个环境执行 plan/apply）
策略即代码	集成 OPA / Checkov 等，在 Plan 阶段自动拦截不合规变更
自动化运行	VCS 事件或定时触发 terraform plan/apply，减少人工错误
漂移检测	持续对比实际基础设施与代码，发现差异后告警或自动修复
私有模块注册表	集中管理可复用的 Terraform 模块，促进标准化和自助服务
私有 Provider 注册表	托管自定义/内部审批的 Provider，带 GPG 签名和审计
成本估算	集成 Infracost 等工具，在 Plan 阶段预估费用
审计日志	完整记录所有 Terraform 活动，支持追溯和合规
自定义 Hook	在 Plan/Apply 前后注入自定义脚本或集成外部工具

TACOS 产品全景（2026） #

产品	类型	支持 IaC 工具	定价模式	特点
Terraform Cloud / Enterprise	商业（HashiCorp 官方）	Terraform	按用量（2026.3 起取消免费层）	官方产品，HCP 托管
Scalr	商业（Pure-play）	Terraform, OpenTofu	按 Run 计费（Free: 50 runs/月）	纯 Terraform/OpenTofu，层级 RBAC 继承，BYOK 加密
Spacelift	商业（Multi-IaC）	Terraform, OpenTofu, Pulumi, CloudFormation, Ansible, K8s	按 Worker 计费	最可定制，自定义 Runner 镜像，OPA 策略最灵活
env0	商业（Multi-IaC）	Terraform, OpenTofu, Pulumi, Terragrunt, Helm, K8s	按环境/Apply 计费（Free: 250 runs/月）	真实成本关联，环境 TTL 自动销毁
Terrakube	开源-Github	Terraform, OpenTofu	免费（自托管）	开源 TACOS，私有模块/Provider 注册表，VCS 集成，自定义工作流（OPA/Infracost），RBAC，远程后端
Terrapod	开源-Github	Terraform, OpenTofu	免费（自托管）	Terraform Enterprise 的开源替代，提供协作、治理（RBAC + OPA/Rego）、状态管理和 Web UI
Atlantis	开源-Github	Terraform	免费（自托管）	PR 驱动工作流的先驱，需自行搭建管理平面
Digger / OpenTaco	开源-Github	Terraform, OpenTofu	免费	复用现有 CI（GitHub Actions），不额外运行计算
stategraph / Terrateam	开源-Github	Terraform, OpenTofu, CDKTF, Terragrunt, Pulumi	免费	GitOps 编排，与 GitHub 深度集成
Terramate	开源-Github	Terraform, OpenTofu, Terragrunt, K8s	免费	编排 + 代码生成引擎，运行在现有 CI 之上

Pure-play vs Multi-IaC #

Pure-play（仅 Terraform/OpenTofu）:
 Scalr
 └─ 优势：单一状态模型，可深度报告资源/模块/Provider/版本/漂移
 └─ 适合：已统一使用 Terraform/OpenTofu 的团队

Multi-IaC（支持多种 IaC 工具）:
 Spacelift / env0
 └─ 优势：统一管控 Terraform + Pulumi + CloudFormation + Ansible
 └─ 适合：多团队使用不同 IaC 工具的组织
 └─ 注意：抽象层越厚，差异越容易泄漏（Leaky Abstractions）

TACOS vs CI/CD 自建方案 #

维度	CI/CD 自建（GitHub Actions 等）	TACOS 平台
状态锁	需自行实现	✅ 内置
策略执行	需手动集成 OPA	✅ 内置 OPA/Checkov
漂移检测	需自建定时任务	✅ 内置持续检测
RBAC	需自行设计	✅ 细粒度内置
私有注册表	需额外部署	✅ 内置
成本估算	需集成 Infracost	✅ 内置
审计链	需自行拼接	✅ 完整内置
维护成本	高（随规模增长）	低（平台托管）
灵活性	极高	中等
初期成本	低	中-高

是否需要 TACOS？决策树 #

你是个人开发者或 2-3 人团队？
 └─ 是 → CLI + 远程后端 即可，不需要 TACOS

你使用 GitHub Actions 就能满足需求？
 └─ 是 → 继续用 CI/CD，暂不需要

你有多个团队 + 多个环境 + 合规要求？
 └─ 是 → 需要 TACOS

你想要 PR 驱动但不想引入商业平台？
 └─ 是 → Atlantis（开源先驱）

你同时使用 Terraform + Pulumi + CloudFormation？
 └─ 是 → Multi-IaC TACOS（Spacelift / env0）

选型检查清单 #

并发数和 Agent 配额是否满足需求？
状态存储位置？能否使用自己的 Bucket？
RBAC 粒度？是否支持自定义角色？
是否支持层级继承（变量/凭证/模块从上层传递到 Workspace）？
能否通过 CLI 设置 TACOS 为远程后端？
是否专注 Terraform/OpenTofu，还是通用 CI/CD？
集成便捷性（Slack/Datadog 等，API Key 即用还是需要复杂插件）？
是否有模块/Provider/版本使用报告？
GitOps 工作流中是否将 Plan 详情回写到 PR？
是否支持私有 Provider 注册表（不仅是模块注册表）？
是否支持 BYOK（自带加密密钥）？
计费单位是什么？（Run / Worker / 并发数）—— 按实际 Run 量对比

参考资源 #

Reference #

Terrapod

Mon, 01 Jan 0001 00:00:00 +0000

Terrapod #

Terrapod 是一个免费、开源、自托管的 TACOS（Terraform Automation and Collaboration Software）平台，定位为 Terraform Enterprise / Terraform Cloud 的开源替代品。它不是 Terraform 或 OpenTofu 的 fork，而是它们的编排层——将 CLI 工具升级为团队级基础设施管理平台。

属性	说明
定位	Terraform Enterprise / HCP Terraform 的开源替代
协议	MPL-2.0（与 OpenTofu 相同，文件级 copyleft，内部使用无披露义务）
技术栈	FastAPI (Python) + Next.js (前端) + PostgreSQL + Redis + Go (工具链)
部署方式	Helm Chart on Kubernetes（单节点 k3s 即可启动）
支持引擎	Terraform、OpenTofu（推荐）、Terragrunt
仓库	github.com/mattrobinsonsre/terrapod

核心架构 #

┌─────────────────────────────────────────────────────────┐
│ Browser / CLI │
└──────────────────────┬──────────────────────────────────┘
 │ HTTPS
 ▼
┌─────────────────────────────────────────────────────────┐
│ Terrapod 控制平面 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐ │
│ │ Next.js BFF │────▶│ FastAPI API │ │
│ │ (Web UI + │ │ (多副本，无 leader election) │ │
│ │ 反向代理) │ │ │ │
│ └──────────────┘ └──────────────────────────────┘ │
│ │ │ │ │
└────────────────────────────┼────┼────┼───────────────────┘
 │ │ │
 ┌──────────────┘ │ └──────────────┐
 ▼ ▼ ▼
 ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
 │ PostgreSQL │ │ Redis │ │ Object Storage │
 │ (状态+元数据) │ │ (会话/锁/事件)│ │ (状态/计划/日志) │
 └──────────────┘ └──────────────┘ └──────────────────┘
 ▲
 │ 数据不离开你的边界
 │
┌─────────────┴───────────────────────────────────────────┐
│ 执行集群（可在任意网络） │
│ │
│ ┌────────────────┐ ┌────────────────────────────┐ │
│ │ Runner Listener │────▶│ 临时 K8s Job │ │
│ │ (出站 SSE 连接) │ │ (terraform / tofu 执行) │ │
│ └────────────────┘ └────────────────────────────┘ │
│ │
│ 执行集群 → 控制平面（出站），控制平面 ✗ → 执行集群 │
└──────────────────────────────────────────────────────────┘

关键设计：

Terramate

Mon, 01 Jan 0001 00:00:00 +0000

Terramate #

Terramate 是一个开源的 IaC 编排与代码生成引擎，用于管理 Terraform / OpenTofu / Terragrunt 的大规模代码库。它不是 TACOS，也不是 Terraform 的替代——它运行在你现有的 CI/CD 之上，把巨型 Terraform 仓库拆成可独立部署的 Stack，并提供变更检测、并行执行、DRY 代码生成。

属性	说明
定位	IaC 编排 + 代码生成引擎（运行在现有 CI 之上）
协议	MPL-2.0（文件级 copyleft，内部使用无披露义务）
语言	Go（单二进制 CLI）
支持引擎	Terraform、OpenTofu、Terragrunt（也可编排 Helm、K8s、CloudFormation 等任意命令）
部署形态	CLI（本地 / CI 中运行）+ 可选 Terramate Cloud（SaaS 观测平面）
仓库	github.com/terramate-io/terramate（3.6k+ stars）

1. 核心架构 #

┌───────────────────────────────────────────────────────────────┐
│ Git 仓库（= Terramate 项目） │
│ │
│ ┌───────────────── root.tm.hcl（可选，全局配置/Globals） │
│ │ │
│ │ stacks/ │
│ │ ├── alice/ │
│ │ │ ├── stack.tm.hcl ← Stack 定义（name/id/tags） │
│ │ │ ├── main.tf ← 原生 Terraform 代码 │
│ │ │ └── _terramate_generated_backend.tf ← 生成的代码 │
│ │ └── bob/ │
│ │ └── ... │
└──┼─────────────────────────────────────────────────────────────┘
 │
 ▼
┌──────────────────┐ 变更检测（对比 git commits） ┌──────────────────┐
│ terramate CLI │ ───────────────────────────────▶ │ Git │
│ │ └──────────────────┘
│ · create/list │ 编排执行（依赖感知 + 并行）
│ · generate │ ───────────────────────────────▶ terraform / tofu
│ · run │ （init/plan/apply）
│ · list --changed│
└────────┬─────────┘
 │ 可选：同步 drift / deployment / insights
 ▼
┌──────────────────┐
│ Terramate Cloud │ 观测平面：Dashboard、漂移检测、告警、
│ （免费个人版） │ PR 预览、DORA 指标、资产清单
└──────────────────┘

关键设计：

Crucible

Mon, 01 Jan 0001 00:00:00 +0000

Crucible IAP 学习笔记 #

Resouces:

https://www.forgedinfeatherstechnology.com/crucible-iap

https://github.com/ponack/crucible-iap

一、项目定位：Crucible 是什么 #

Crucible IAP（Infrastructure Automation Platform，基础设施自动化平台） 是一个 自托管（self-hosted）、隐私优先 的 IaC 编排平台，定位为 Spacelift / Terraform Cloud 的开源替代品。

一句话理解它的工作流：

推送代码 → Crucible 自动执行 plan → 人工/策略审批 → apply

它解决的核心痛点：

云端 IaC 平台的问题	Crucible 的回答
按资源/按运行/按席位收费，规模越大越贵	自托管，成本固定，无 per-run / per-resource 费用
plan 输出、state 文件、密钥经过第三方基础设施	0 第三方暴露，数据全部留在自己的环境
SaaS 黑盒，不可控	你的基础设施你做主，AGPL-3.0 开源

支持的 IaC 工具：OpenTofu、Terraform、Terragrunt、Ansible、Pulumi。

二、核心概念（先记住这 6 个词） #

概念	含义
Stack（栈）	管理的基本单元：一个 Git 仓库 + 分支 + 工作目录 + 工具 + 运行行为的组合。类似 Spacelift 的 Stack、TFC 的 Workspace
Run（运行）	一次完整的执行实例，状态机：`queued → planning → unconfirmed → applying → finished`
Policy（策略）	OPA/Rego 编写的守门规则，在 plan/apply 前强制评估，deny 则拦截
Drift（漂移）	实际基础设施与声明的 state 不一致；Crucible 可定时检测甚至自动修复
Blueprint（蓝图）	参数化的自服务模板：平台团队发布表单，应用团队填表即部署，不用碰 IaC
Variable Set（变量集）	一组命名的环境变量，加密存储，可复用挂载到多个 Stack

Run 的类型 #

触发方式	类型	行为
推送到跟踪分支	`tracked`	plan → 等确认 → apply
推送到跟踪分支（auto_apply=true）	`tracked`	策略通过即自动 apply
Pull Request / Merge Request	`proposed`	仅 plan，结果回帖 PR，不 apply
手动触发（UI/API）	`tracked` / `proposed` / `destroy`	按配置执行
漂移检测	`proposed`	仅 plan，发现 diff 告警

三、整体架构 #

GitHub / GitLab / Bitbucket / Azure DevOps webhook
 │
 ▼
Reverse proxy (Caddy bundled, or nginx / Traefik / your own)
 │
 ├── /auth, /api, /health → Crucible API (Go + Echo)
 │ │
 │ ┌──────────┼──────────────┐
 │ ▼ ▼ ▼
 │ PostgreSQL MinIO OPA engine
 │ (DB + queue (state, (embedded,
 │ + audit log) plans, Rego)
 │ logs)
 │ │
 │ River job queue (PostgreSQL)
 │ │
 │ Crucible Worker (separate container)
 │ (no public ports, has Docker socket)
 │ │
 │ Docker SDK → ephemeral runner container
 │ (tofu / terraform / ansible / pulumi)
 │
 │ — or —
 │ crucible-agent (external host, any cloud / on-prem)
 │ polls /api/v1/agent/claim → runs same Docker images
 │ streams logs back → reports outcome
 │
 └── /* → Crucible UI (SvelteKit SSR)

架构要点（学习时重点理解）：

RAG Framework for IaC Agent

Mon, 01 Jan 0001 00:00:00 +0000

开源 LLM + RAG 框架选型：面向 IaC Agent 开发 #

目标：选择开源 RAG 框架作为基座，二次开发出 IaC Agent（自然语言生成基础设施代码）。

核心需求：开源 + UI 界面 + 方便二次开发 + 适合构建 IaC Agent

IaC Agent 对 RAG 框架的特殊要求 #

IaC Agent 与普通知识库问答不同，对 RAG 框架有更高的技术要求：

IaC Agent 工作流程：
┌──────────────────────────────────────────────────────────────┐
│ 1. 用户在 UI 输入自然语言需求 │
│ "为 project-a 创建一个 4C8G 的 ECS 实例，部署在 cn-shanghai" │
└───────────────────────┬──────────────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────────────────────┐
│ 2. RAG 检索：从已有 IaC 代码库中检索相似代码作为上下文 │
│ ├─ 检索同项目的已有资源定义（参考命名、标签、模块结构） │
│ ├─ 检索类似资源的代码模板（ECS / RDS / VPC 等） │
│ └─ 检索 Terraform Provider 文档和最佳实践 │
└───────────────────────┬──────────────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────────────────────┐
│ 3. LLM 生成 IaC 代码（带 RAG 上下文增强） │
│ ├─ 参考已有代码风格 │
│ ├─ 生成 Terraform / OpenTofu / Pulumi 代码 │
│ └─ 确保代码符合项目规范（命名、标签、模块划分） │
└───────────────────────┬──────────────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────────────────────┐
│ 4. 自定义工具调用（关键！） │
│ ├─ 调用 terraform fmt / validate 验证代码 │
│ ├─ 调用 tflint / checkov 做安全和规范检查 │
│ ├─ 调用 Git API（创建分支、提交代码、创建 PR） │
│ ├─ 调用仓库分析工具（解析已有目录结构） │
│ └─ 调用云 API（验证资源配额、检查冲突） │
└───────────────────────┬──────────────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────────────────────┐
│ 5. 结果返回 UI │
│ ├─ 生成的代码（可预览、可编辑） │
│ ├─ PR 链接 │
│ └─ 验证报告（通过/失败/警告） │
└──────────────────────────────────────────────────────────────┘

因此，IaC Agent 对 RAG 框架的核心要求是：