Terrapod #

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

核心架构 #

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

关键设计：

• BFF 模式：Next.js 前端是唯一入口，浏览器不直接访问 API
• ARC 模式执行：Runner 按需创建 Job（类似 GitHub Actions Runner Controller）
• 出站优先：Runner 通过出站 SSE 连接控制平面，无需入站网络——适合隔离 VPC、跨区域、本地数据中心
• 单组织设计：每个实例一个组织（default），需要多租户则部署多个实例

核心功能 #

平台基础 #

治理与安全 #

注册表与缓存 #

AI（可选，默认关闭） #

快速体验 #

# 一键启动（创建本地 kind/k3d 集群 + 安装 Terrapod）
make eval
# → 打开 http://localhost:8080  (登录: admin / terrapod)

# 清理
make eval-down

前提：Docker、kubectl、helm、kind 或 k3d

生产部署 #

前提 #

• Kubernetes 集群（1.27+），单节点 k3s 即可
• Helm 3.x
• 外部 PostgreSQL 14+ 和 Redis 7+（生产环境不建议用内置的）

Helm 部署 #

helm install terrapod oci://ghcr.io/mattrobinsonsre/terrapod \
  --namespace terrapod --create-namespace \
  --set ingress.enabled=true \
  --set ingress.hostname="terrapod.example.com" \
  --set ingress.className=traefik \
  --set postgresql.url="postgresql+asyncpg://terrapod:PASSWORD@PGHOST:5432/terrapod" \
  --set redis.url="redis://REDISHOST:6379" \
  --set bootstrap.adminEmail="admin@example.com" \
  --set bootstrap.adminPassword="change-me-now"

配置 OpenTofu / Terraform #

# main.tf — 只需将 cloud block 指向 Terrapod
terraform {
  cloud {
    hostname     = "terrapod.example.com"
    organization = "default"

    workspaces {
      name = "my-first-workspace"
    }
  }
}

# 登录并执行
tofu login terrapod.example.com
tofu init
tofu plan
tofu apply

💡 零代码迁移：现有 cloud block 只需改 hostname 指向 Terrapod，CLI 和 CI/CD 通常无需其他改动。

与 Terraform Enterprise / HCP Terraform 对比 #

与同类开源方案对比 #

Terrapod vs Terrakube（两个最接近的开源方案） #

高可用与生产特性 #

Terraform Provider #

Terrapod 提供自己的 Terraform Provider——用 Terraform 管理 Terrapod 本身：

# 25 个资源 + 9 个数据源
resource "terrapod_workspace" "example" {
  name = "my-workspace"
}

resource "terrapod_variable" "aws_region" {
  workspace_id = terrapod_workspace.example.id
  key          = "AWS_REGION"
  value        = "cn-hangzhou"
  sensitive    = false
}

resource "terrapod_role" "viewer" {
  name = "viewer"
  capabilities = ["workspace:read", "run:plan"]
}

支持的资源：terrapod_workspace、terrapod_variable、terrapod_role、terrapod_vcs_connection、terrapod_agent_pool、terrapod_run_task、terrapod_catalog_item、terrapod_execution_hook 等。

学习路线 #

1. 快速体验（30 分钟）
   └─ make eval → 浏览 UI → 查看示例 Workspace 和 Run

2. 部署到测试集群（1 小时）
   └─ k3s/kind + Helm 部署 → 创建 Workspace → 配置 cloud block → plan/apply

3. 深入功能（1-2 天）
   └─ RBAC 配置 → OPA 策略 → 安全扫描 → 漂移检测 → 通知集成

4. 生产就绪（1 周）
   └─ 外部 Postgres/Redis → SSO → 对象存储 → HA 部署 → 迁移工具

5. 高级特性
   └─ 空气隔离部署 → AI 审查层 → 自定义执行钩子 → Provider 开发

Reference #

• GitHub 仓库
• 架构文档
• 部署指南
• 迁移指南
• RBAC 文档
• API 参考
• 生产检查清单
• TACOS 概念