Skip to content
Forgeplane Docs

Self-hosted Terraform and OpenTofu orchestration

Forgeplane is a self-hosted control plane for governed Terraform and OpenTofu delivery. It keeps template versioning, run admission, approval, worker placement, audit evidence, and managed-state coordination inside infrastructure that you operate.

Use this page to decide whether Forgeplane fits your delivery model. It is a control plane around Terraform and OpenTofu; it does not remove the need to operate the coordinator, storage, keys, worker toolchains, cloud credentials, or target infrastructure.

When Forgeplane fits

Section titled “When Forgeplane fits”

Forgeplane is designed for teams that need to:

  • run Terraform or OpenTofu from worker pools under their operational control;
  • promote versioned infrastructure templates through environments and instances;
  • review a plan before an apply intent can execute;
  • keep requester, reviewer, inputs, artifacts, logs, and results in one audit chain;
  • place execution on workers with the required tool version, network access, and credentials;
  • monitor Terraform/OpenTofu instances for drift and use governed follow-up operations.

The platform also supports Ansible execution through the same queue and worker boundary, but Ansible is execute-only. It does not use Terraform/OpenTofu plan-to-apply promotion, teardown, managed state, or plan-based drift workflows.

How a governed delivery moves

Section titled “How a governed delivery moves”

A typical Terraform or OpenTofu delivery uses this sequence:

  1. Publish a template version. The registry stores the infrastructure source, input schema, tool requirements, and execution metadata.
  2. Create an environment and instance. The instance binds the published template lineage to a deployment context.
  3. Resolve the run context. Forgeplane combines environment defaults, explicit inputs, connections, secret bindings, worker requirements, feature gates, and approval policy.
  4. Run a plan. An eligible worker creates a plan artifact and streams status and logs to the coordinator.
  5. Review the change. Promotion creates a linked apply intent. When the environment requires approval, the intent waits in pending_approval for an authorized decision.
  6. Apply the reviewed artifact. Approval queues the intent, and Forgeplane verifies the reviewed artifact before the worker applies it.
  7. Retain evidence. The source plan, approval record, promoted intent, execution context, logs, status, and result remain linked.

See Run operations and Approval workflows for the detailed lifecycle.

What Forgeplane governs

Section titled “What Forgeplane governs”
Area Forgeplane responsibility
Template lineage Published versions, input contracts, tool requirements, and Git references.
Run admission Resolved inputs, secret and connection bindings, policy, feature gates, and worker eligibility.
Worker placement Scheduling to a pool that advertises the required capability and network placement.
Approval Separate requester and reviewer records for gated apply intents.
Artifact integrity Linkage and digest verification between the reviewed plan and apply intent.
Operations evidence Run status, streamed logs, artifacts, audit records, and follow-up lineage.
Managed state State identity, encrypted objects, generations, and fail-closed recovery when enabled for Terraform/OpenTofu instances.

What you still operate

Section titled “What you still operate”

A self-hosted deployment remains your responsibility. Plan for:

  • the coordinator and its PostgreSQL and NATS dependencies;
  • artifact storage and, when enabled, managed-state object storage;
  • encryption keys and the key backups required for recovery;
  • worker images containing the Terraform, OpenTofu, or Ansible versions you intend to run;
  • worker network placement, cloud credentials, IAM, and access to target infrastructure;
  • backups, restore tests, upgrades, observability, and access control for the deployment.

The default production worker image does not bundle infrastructure tools. A worker must contain the binary and supporting runtime for every capability it advertises.

See Container distribution, Helm chart, Workers, and Configuration for deployment boundaries.

Managed state and compatibility boundaries

Section titled “Managed state and compatibility boundaries”

Terraform and OpenTofu instances can use Forgeplane-managed state. When enabled, Forgeplane coordinates the state metadata, encrypted payload, key-backed verification, and generation checks needed to prevent a stale run from silently replacing newer state.

This is not a claim that every feature of every mature Terraform or OpenTofu backend is available. Treat the managed-state storage, backup, restore, and recovery contract as part of your deployment design, and verify it before production use.

Approval and least privilege

Section titled “Approval and least privilege”

Approval is an environment-controlled governance step, not a replacement for authorization. A principal still needs the required platform permission, organization membership, team scope, and resource access. Review Permissions and roles before assigning automation identities.

Use Approval workflows for the plan-to-apply sequence and Environments for policy and deployment boundaries.

Start here

Section titled “Start here”