Run Terraform and OpenTofu in private networks

Many infrastructure targets should not accept public ingress: internal Kubernetes APIs, private cloud endpoints, on-premises systems, and restricted management networks. The execution process must run where it can reach those targets without moving the whole control plane into every network.

Forgeplane uses customer-controlled workers. Named worker pools let you place execution near the target while the coordinator retains admission, policy, scheduling, run records, and audit evidence.

Forgeplane is in private beta. Request access before planning a deployment around this model.

Compare private execution patterns

Pattern	Control boundary	Main design work
Self-hosted CI runner	CI owns job admission and history; the runner reaches the private target	Build state, approval, artifact, retry, and IaC-specific evidence around the CI job.
Vendor control plane with private agent	The agent runs in your network; the vendor operates the control plane	Review which data and credentials cross the boundary and how vendor availability affects execution.
Self-hosted control plane and workers	You operate the coordinator, durable services, and execution pools	Own availability, upgrades, TLS, credentials, worker images, storage, and recovery.

Forgeplane uses the third model. This is not an air-gap claim. Workers still need configured connectivity to coordinator gRPC, NATS job delivery, source services when the worker fetches source directly, optional telemetry, and the infrastructure targets they operate. Artifact, run, and managed-state transfer uses the coordinator path; workers do not need direct object-storage access for that transfer.

Worker placement model

1. A worker registers with the coordinator and joins a named pool.
2. It advertises only the tool capabilities present in its image.
3. The coordinator selects a connected worker that matches the requested pool and tool.
4. Assignment and lease checks fence job delivery.
5. The worker prepares a disposable workspace, runs the tool, and streams status and logs.
6. The coordinator retains the durable run, artifact, state, and audit records.

A queue message alone is not authority to execute. The worker and coordinator still enforce assignment and lease ownership.

See Workers and capability-based execution for the full scheduling contract.

Design pools around trust boundaries

Use separate pools when targets require different:

• network routes or DNS;
• cloud accounts and IAM roles;
• Kubernetes credentials;
• tool versions or provider plugins;
• environment sensitivity;
• egress policy; or
• scaling and maintenance windows.

A pool name is routing metadata, not an isolation guarantee. Enforce the boundary with real network policy, workload identity, credentials, namespaces or clusters, and image provenance. The current Helm chart’s built-in egress policy uses a release-wide selector that includes the coordinator and every worker pool. Use component- or pool-scoped external policies when their allowed destinations must differ.

For example, development and production can use different worker pools even when both run OpenTofu. Production can then have separate network access, credentials, image pinning, capacity, and drain procedures.

Build an honest capability contract

The default production worker image contains no infrastructure tools and advertises an empty capability list. A tool-enabled image must contain every binary it advertises and advertise nothing else.

Workload	Capability
Terraform	terraform
OpenTofu	tofu (opentofu is accepted as an alias)
Ansible	ansible

Use reviewed worker image tags and verify the resolved image digest through your registry or deployment controls. The current Helm chart renders repository:tag and does not expose a separate digest value. Test the exact tool and provider versions before assigning production credentials. A capability label does not install a binary or prove that its plugins are available.

Keep credentials inside the execution boundary

Separate coordinator credentials from worker credentials. Give a pool only the provider, cluster, or SSH access required for its targets. Materialize secrets through the governed execution path rather than ordinary inputs, image layers, or repository files.

Restrict worker egress to required endpoints where practical. Workspaces and temporary files are disposable; they are not the backup authority for plans, artifacts, or managed state.

Use Secret management and Connections for the current delivery and rotation boundaries.

Capacity and maintenance

Each worker advertises a maximum concurrent-job count. The scheduler assigns work only within that capacity. A draining worker finishes current work but accepts no new assignments; an offline worker is not schedulable.

Plan for:

• enough capacity for the queue and approval pattern;
• failure when no eligible worker is available;
• safe draining before image, credential, or network maintenance;
• lease expiry and reassignment behavior; and
• observation of worker health without treating a stale heartbeat as successful execution.

Kubernetes deployment checklist

For a Helm deployment:

1. Create one worker pool for each real capability and trust boundary.
2. Use a reviewed image that contains the declared toolchain.
3. Configure secure coordinator-worker gRPC, including client certificates where required.
4. Mount writable storage only for temporary directories, workspaces, and an optional tool cache.
5. Disable unnecessary ServiceAccount token access and grant explicit workload identity instead.
6. Allow only the DNS, coordinator gRPC, NATS queue, direct source, optional telemetry, and target traffic the pool needs. Do not grant workers direct object-storage access for coordinator-mediated artifact or state transfer. Because the built-in chart policy is release-wide, use a component- or pool-scoped external policy when coordinator-only PostgreSQL or object-storage access must not reach workers.
7. Test target reachability and a provider-free no-change run before granting mutation credentials.
8. Drain the pool and verify queue behavior during maintenance.

Read the Helm deployment guide for the current security context, storage, certificate, and worker-pool values. Use Run operations for cancellation, timeout, logs, and retries.