Open-source platform replacement for Terraform Enterprise.
Terrapod provides the collaboration, governance, state management, and UI layer that wraps around terraform or tofu as pluggable execution backends. It targets API compatibility with the HCP Terraform / TFE V2 API so that existing tooling -- the terraform CLI with cloud block, the go-tfe client, CI/CD integrations -- can point at a Terrapod instance with minimal reconfiguration.
Terrapod is not a fork of Terraform or OpenTofu. It orchestrates them.
Drop-in replacement for HCP Terraform. Point your existing
cloudblocks,go-tfeclients, and CI/CD pipelines at Terrapod — zero code changes required.
AI-augmented plans. Every plan can carry an LLM-generated change description, risk assessment, and (on failure) suggested fixes — provider-agnostic via LiteLLM. Wire AWS Bedrock (Claude, Nova, gpt-oss) with native IAM auth, or point at OpenAI, Anthropic, Gemini, Azure OpenAI, or any OpenAI-compatible endpoint. See docs/ai-plan-summary.md.
Policy-as-code with OPA. Block applies on policy violations using Open Policy Agent and the Rego language — the open-source equivalent of TFE's proprietary Sentinel. Policy sets are scoped to workspaces with the same label-based model as roles, evaluated on the runner against the plan JSON, and gated as
advisory(warn) ormandatory(block). See docs/policies.md.
| Feature | Status | Description |
|---|---|---|
| Workspaces | Implemented | Isolate state, variables, and runs per workspace |
| Remote State Management | Implemented | Versioned state storage with locking, rollback, encryption at rest via CSP services |
| Agent Execution | Implemented | Plan/apply runs on the server via K8s Job-based runner infrastructure |
| VCS Integration | Implemented | GitHub (App) and GitLab (access token); polling-first with optional webhooks |
| Variables & Secrets | Implemented | Per-workspace env and Terraform variables; sensitive values protected by database encryption-at-rest; variable sets |
| RBAC | Implemented | Label-based role system with hierarchical workspace permissions (read/plan/write/admin) |
| Private Module Registry | Implemented | Publish, version, and share modules internally |
| Private Provider Registry | Implemented | Publish, version, and share providers with GPG signing and network mirror caching |
| Binary Caching | Implemented | Pull-through cache for terraform/tofu CLI binaries |
| Agent Pools | Implemented | Named groups of runner listeners; join token → certificate exchange for auth |
| CLI-Driven Runs | Implemented | terraform plan / apply via cloud backend (both terraform and tofu verified) |
| TFE V2 API | Implemented | JSON:API surface compatible with go-tfe / terraform login |
| Audit Logging | Implemented | Immutable event log with configurable retention |
| SSO (OIDC / SAML) | Implemented | Pluggable identity providers (Auth0, Okta, Azure AD, etc.) |
| Drift Detection | Implemented | Scheduled plan-only runs to detect out-of-band changes |
| Run Triggers | Implemented | Cross-workspace dependency chains — source apply triggers downstream runs |
| AI Plan Summary | Implemented | LLM-generated change summary + risk assessment on every plan; failure analysis on errored plans. Provider-agnostic via LiteLLM — AWS Bedrock (Claude, Nova, gpt-oss…), OpenAI, Anthropic direct, Google Gemini, Azure OpenAI, vLLM. IAM-native auth for Bedrock (IRSA + optional cross-account sts:AssumeRole). |
| Policy-as-Code (OPA) | Implemented | Rego-based policy enforcement on plan output — the open-source equivalent of Sentinel. Advisory or mandatory sets, label-scoped to workspaces, evaluated on the runner against plan JSON, with admin-override on mandatory blocks. Author Rego, attach to workspaces by label, see pass/fail per policy on every run. |
| Notifications | Implemented | Webhook (HMAC-SHA512), Slack (Block Kit), and email alerts on run events |
| Run Tasks | Implemented | Pre/post-plan webhook hooks for external validation |
| Workspace Health | Implemented | Per-workspace health conditions, VCS polling status, drift detection indicators |
| Workspace Autodiscovery | Implemented | Atlantis-style monorepo autodiscovery — pattern-matched rules auto-create workspaces on PRs to new directories |
| Cloud Credentials | Implemented | Dynamic provider credentials via K8s workload identity (AWS IRSA, GCP WIF, Azure WI) |
Workspace overview with VCS integration, drift detection, and labels
Run detail with plan output and VCS metadata
Variables with sensitive masking and HCL support
Agent pools with listener health monitoring
+---------------------+
| Browser / CLI |
+----------+----------+
|
HTTPS (TLS)
|
+----------v----------+
| Ingress |
+----------+----------+
|
+----------v----------+
| Next.js Frontend | (BFF pattern)
| (Web UI + Proxy) |
+----+------------+---+
| |
/app/* | | /api/* /.well-known/*
(pages) | | (rewrite to API)
| |
+----v------------v---+
| FastAPI API Server |
+--+------+------+----+
| | |
+------------+ +--+--+ +------------+
| | | |
+-----v-----+ +-----v-+ +-v----------+ +----v-------+
| PostgreSQL | | Redis | | Object | | VCS Polls |
| (data, | | (sess | | Storage | | (GitHub, |
| state | | ions,| | (S3/Azure/ | | GitLab) |
| metadata) | | locks| | GCS/FS) | +------------+
+-----------+ +------+ +-----------+
^
+---------------+
| |
+---------v----------+ |
| Runner Listener | | (one or more, each
| (K8s Deployment, | | joins a pool via
| joins pool via | | join token)
| join token) | |
+---------+----------+ |
| |
+---------v----------+ |
| K8s Jobs | |
| (ephemeral | |
| terraform/tofu) | |
+--------------------+ +
- API-first -- every UI action is backed by a public API endpoint
- BFF pattern -- Next.js frontend is the single ingress entry point; browser never talks to the API directly
- Kubernetes-native -- deployed exclusively via Helm chart; runner Jobs are ephemeral K8s Jobs
- ARC-pattern execution -- listener creates Jobs on demand (like GitHub Actions Runner Controller)
- OpenTofu-first -- OpenTofu is the recommended execution backend;
terraformis also supported - Single organization -- one org per instance; every Terrapod API path that contains an organization segment uses the literal name
default - Native object storage -- speaks each cloud provider's native SDK (S3, Azure Blob, GCS) with filesystem fallback for dev
Terrapod runs only on Kubernetes (the runner uses the Jobs API). Deploy it onto any cluster — or a single-node k3s VM — with the Helm chart.
- A Kubernetes cluster (1.27+). No cluster?
curl -sfL https://get.k3s.io | sh -gives you one on a single VM, with an ingress controller (Traefik) and storage included. - Helm 3.x
- External PostgreSQL 14+ and Redis 7+ (the chart does not bundle them) — a managed service or run them on the cluster/VM.
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"Defaults give you filesystem storage on a PVC, local password auth, the migrations job, and a bootstrap admin user. Point your hostname's DNS at the ingress controller, then open https://terrapod.example.com and log in. (For a quick HTTP-only look, add --set ingress.tls=false.)
Object storage options: S3, Azure Blob, GCS, or the default PVC-backed filesystem.
# Create an API token in the UI (Settings → API Tokens), or: tofu login terrapod.example.com
export TERRAPOD_TOKEN="<your-api-token>"
curl -X POST https://terrapod.example.com/api/v2/organizations/default/workspaces \
-H "Authorization: Bearer $TERRAPOD_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
-d '{
"data": {
"type": "workspaces",
"attributes": {
"name": "my-first-workspace"
}
}
}'# main.tf
terraform {
cloud {
hostname = "terrapod.example.com"
organization = "default"
workspaces {
name = "my-first-workspace"
}
}
}tofu login terrapod.example.com
tofu init
tofu plan
tofu applyFor the full walkthrough (k3s bootstrap, DNS/ingress, agent mode, variables, registry) see docs/getting-started.md. For the complete production deployment guide — storage backends, external DB, SSO, scaling, TLS — see docs/deployment.md. To run Terrapod from source as a contributor, see docs/local-development.md.
Terrapod supports multiple authentication methods:
- Local passwords -- PBKDF2-SHA256 hashed, with zxcvbn strength validation
- OIDC -- Auth0, Okta, Azure AD, and any standards-compliant provider via authlib
- SAML -- Azure AD SAML and other SAML 2.0 providers via python3-saml
- terraform login -- OAuth2 Authorization Code with PKCE for CLI authentication
- API tokens -- long-lived tokens for automation, SHA-256 hashed at rest
See docs/authentication.md for setup guides.
| Document | Description |
|---|---|
| Architecture | System components, BFF pattern, storage, runners, auth flows |
| Getting Started | Deploy the Helm chart on Kubernetes (or k3s), first workspace, first plan/apply |
| Local Development | Run Terrapod from source with Tilt (contributors only) |
| Authentication | Local auth, OIDC, SAML, terraform login, API tokens |
| RBAC | Permission model, label-based access control, custom roles |
| API Reference | All API endpoints with examples |
| Deployment | Production Helm deployment, storage backends, scaling |
| Registry | Private module/provider registry, caching layers |
| Registry Publishing | Publishing providers/modules with terrapod-publish and the client-signed publish protocol |
| VCS Integration | GitHub and GitLab setup, polling, webhooks |
| Policies (OPA) | Rego policy authoring, advisory vs mandatory enforcement, label-based scoping, admin override |
| Autodiscovery | Atlantis-style monorepo workspace autodiscovery |
| Drift Detection | Scheduled plan-only runs to detect infrastructure drift |
| Run Triggers | Cross-workspace dependency chains |
| Notifications | Webhook, Slack, and email alerts on run events |
| Run Tasks | Pre/post-plan webhook hooks for external validation |
| Audit Logging | Immutable event log, query API, retention |
| Cloud Credentials | AWS IRSA, GCP WIF, Azure WI setup |
| Monitoring | Prometheus metrics, scraping, recommended alerts |
| Disaster Recovery | Break-glass state recovery from object storage |
| Layer | Technology |
|---|---|
| API server | Python 3.13+ / FastAPI / SQLAlchemy (async) / Pydantic |
| Database | PostgreSQL |
| Cache / Sessions | Redis |
| Object storage | AWS S3, Azure Blob, GCS, or filesystem (native SDKs) |
| Frontend | Next.js 15 / React 19 / TypeScript / Tailwind CSS / Radix UI |
| Runner listener | Python (same codebase as API) |
| Auth | authlib (OIDC), python3-saml (SAML) |
| Deployment | Helm chart on Kubernetes |
| CI | GitHub Actions |
All builds, tests, and linting run in Docker -- no local Python or Node.js install needed.
make dev # Start local dev environment (Tilt)
make dev-down # Stop local dev environment
make test # Run pytest in Docker (with LocalStack for S3)
make lint # Run ruff + mypy in Docker
make images # Build production Docker images- Commits: conventional commits (
feat:,fix:,docs:,chore:) - Branches: feature branches off
main; never push directly tomain - API contract: JSON:API spec; compatibility tested against
go-tfeclient - Migrations: Alembic with async SQLAlchemy
- Local dev: Tilt with live_update for Python and Node.js hot reload
Terrapod includes a three-layer pen testing framework. All tools run in Docker.
make pentest-sast # Static analysis (Semgrep)
make pentest-images # Container image CVE scan (Trivy)
make pentest-dast # Dynamic testing against live stack (Nuclei)
make pentest # All three layers| Layer | Tool | What it covers |
|---|---|---|
| SAST | Semgrep | OWASP Top 10, secrets detection, project-specific rules (naive datetimes, raw background tasks) |
| Container scanning | Trivy | HIGH/CRITICAL CVEs in terrapod-api and terrapod-web images |
| DAST | Nuclei | Auth bypass, header injection, CORS validation, state endpoint security, HTTP method restriction |
Reports are written to reports/pentest/. See SECURITY.md for the full security policy.
| Project | What it does | Gap vs full TFE replacement |
|---|---|---|
| OpenTofu | Open-source Terraform fork (CLI) | CLI only -- no collaboration platform |
| Atlantis | PR-based plan/apply automation | No UI, no state management, no registry, no RBAC |
| Digger | CI-native Terraform orchestration | Runs inside CI; no standalone platform |
| Terrateam | GitHub-integrated TF automation | GitHub-coupled; limited community edition |
| Spacelift | Commercial TF management platform | Not open source |
Terrapod is the only open-source project that covers the full TFE surface: state management, agent execution, private registry, RBAC, VCS integration, drift detection, OPA policy enforcement, and a production-grade UI -- all in a single self-hosted Kubernetes deployment.
Terrapod is a single, self-hosted platform covering the full TFE surface (state + runs + registry + governance + UI + API) under a copyleft (GPLv3) license.
GPLv3 -- strong copyleft ensures Terrapod and all derivative works remain open source.
Terrapod is not affiliated with, endorsed by, or a product of HashiCorp, Inc. or IBM. Terraform is a trademark of HashiCorp, Inc. OpenTofu is a project of the Linux Foundation.
Contributions are welcome. Please follow these guidelines:
- Fork the repository and create a feature branch from
main - Follow conventional commit format (
feat:,fix:,docs:,chore:) - Run tests (
make test) and linting (make lint) before submitting - Ensure all CI checks pass
- Open a pull request with a clear description of the change
For architecture questions or major changes, open an issue first to discuss the approach.