Why Terraplane
Terraform changes should be reviewable, repeatable, and tied to pull requests — not tribal knowledge or ad-hoc laptop runs. Comment on a PR, get a plan, apply when ready.
Terraplane keeps that workflow and shapes the execution model around two ideas: agents that can reach private infrastructure, and a small surface area you can actually operate.
Better architecture for where Terraform runs
Section titled “Better architecture for where Terraform runs”Most PR-driven Terraform automation is a single process that both:
- receives webhooks, and
- runs Terraform.
That’s fine when every target is reachable from wherever that process lives. It gets awkward fast when it isn’t.
Private APIs, internal control planes, VPC-only endpoints, on-prem systems — with a single remote runner you’d either:
- expose those targets (firewall holes, peering, public load balancers), or
- give up on automating them.
Terraplane splits the job:
| Piece | Responsibility |
|---|---|
| Orchestrator | Webhooks, job state, locks, PR feedback. Can live on the public internet. |
| Agents | Workers that poll the orchestrator over HTTP, claim jobs, and run Terraform where credentials and network already exist. |
Agents sit inside the network that can already reach the resources. They only need outbound HTTP to the orchestrator — no inbound connections, no firewall holes. The orchestrator never needs a path in.
Simpler to run than a full platform
Section titled “Simpler to run than a full platform”You don’t need organizations, workspaces UIs, private registries, identity-provider stacks, and a custom workflow language just to get PR-driven plan and apply.
Terraplane is intentionally narrow:
- a YAML file in your repo (
terraplane.yaml) - PR comments (
plan/apply/unlock) - an orchestrator + agents you can run with Compose or Helm
Environments and stacks route work to the right agent. Multi-account and multi-environment become a routing problem — not “stuff every credential into one box,” and not “adopt an entire Terraform control plane to get agents.”
What stays familiar
Section titled “What stays familiar”Terraform still belongs in the pull request. Plans and applies are reviewable on the PR itself. The commands are short on purpose.
Where Terraplane diverges is architecture and scope — remote agents with stack→agent routing, without the platform sprawl.