OpenTofu is an open-source tool for building, changing, and versioning infrastructure safely and efficiently. It can manage existing and popular service providers as well as custom in-house solutions. It originally derived from HashiCorp Terraform after its license change to BSL in 2023.

Key features:

Define your infrastructure with providers and resources, then drive it through the core workflow.

These read-only commands report on the current state and configuration without changing anything.

tofu graph emits the resource dependency graph in Graphviz DOT format, which dot renders into an image:

Workspaces let a single configuration manage multiple independent state files — typically one per environment (dev, staging, prod) — without duplicating code. Each workspace has its own state, but they share the same configuration and backend. The active workspace name is available in config as terraform.workspace.

OpenTofu maintains a state file that tracks the current state of your infrastructure. This allows it to know what resources have been created and what changes need to be made. State is stored in .tfstate files.

Add to .gitignore:

By default, state is stored via the local backend — a plain-text terraform.tfstate file in your working directory. This is fine for solo development, but not suitable for teams or production.

In a team setting you need a centralized, lockable state backend. The two most common options are S3 and HTTP.

The S3 backend is the most popular choice for AWS users. It supports state locking via DynamoDB.

Setting up the DynamoDB lock table (one-time, can be done via the AWS CLI):

The S3 bucket itself should have versioning enabled so you can recover from accidental state corruption:

A generic HTTP backend suitable for self-hosted state servers (e.g. GitLab, Terraform HTTP backend implementations):

After configuring a new backend, run tofu init to migrate your existing state to it.

Sometimes you need to manipulate state directly — when refactoring config, recovering from drift, or cleaning up. The tofu state subcommands operate on the state file.

The modern, plan-visible alternative to taint is -replace, which shows the recreation in the plan before you commit:

If a plan/apply is interrupted (crash, lost connection), the state lock can be left held, blocking further runs. Release it manually with the lock ID printed in the error message:

OpenTofu configuration is written in HCL (HashiCorp Configuration Language). It's also possible to write raw HCL JSON, or use Nix via Terranix.

Variables allow you to parameterize your configuration and are referenced via var.<name>:

Variable values are resolved in this priority order (highest to lowest):

Locals are computed values you can reuse across your config without exposing them as inputs:

Outputs expose values after apply, useful for passing data between modules or displaying results:

Providers are plugins that let OpenTofu interact with external services and APIs. They're declared in a required_providers block and configured separately:

Some useful providers from the registry:

Resources represent actual infrastructure objects. They're the core building block of OpenTofu configuration:

The key syntax is resource "<type>" "<name>" {} where <type> is provider-specific and <name> is your local identifier for referring to this resource elsewhere (e.g. cloudflare_dns_record.www.id).

Resources can be imported from existing infrastructure if the provider supports it:

Data sources let you fetch read-only information from providers without managing it:

Meta-arguments are special arguments accepted inside resource and module blocks (regardless of the provider) that change how OpenTofu manages the object.

count creates N identical instances of a resource or module. Each instance gets an index via count.index (starting at 0), and instances become a list addressed as <resource>[0], <resource>[1], …

count can also act as a conditional toggle (count = var.enabled ? 1 : 0).

for_each creates one instance per entry of a map or set of strings. Each instance is keyed by a stable string (each.key / each.value) rather than a positional index, addressed as <resource>["key"].

Declares an explicit dependency when OpenTofu can't infer it from references. Use sparingly — implicit dependencies (referencing another resource's attribute) are preferred.

Selects a non-default (aliased) provider configuration for a resource — useful for multi-region or multi-account setups.

Customizes how OpenTofu creates, updates, and destroys a resource. Common settings:

The lifecycle block also hosts precondition and postcondition assertions — see Custom Conditions.

moved blocks aren't a meta-argument but are closely related to refactoring: they record that a resource was renamed or relocated so OpenTofu updates state in place instead of destroying and recreating. They're the declarative alternative to tofu state mv.

OpenTofu can validate assumptions about inputs and outputs directly in configuration, surfacing clear error messages instead of obscure downstream failures. There are three kinds, differing in when they run and whether they halt the operation.

Validates an input value before anything uses it, acting as a gatekeeper for module inputs:

Declared inside a resource, data source, or output's lifecycle block. A precondition asserts something that must hold before the object is processed (an assumption); a postcondition asserts a guarantee after it's processed. Both refer to the object itself via self. A failure produces an error and halts the operation.

A top-level check block validates infrastructure as a whole, independent of any single resource's lifecycle. It can include up to one scoped data source and one-or-more assert blocks, and runs last — after OpenTofu has planned or provisioned everything.

The crucial difference: a failed assert reports a warning and does not halt the operation, unlike pre/postconditions which error out. This makes checks ideal for continuous, non-blocking health validation (e.g. "is the deployed site actually serving 200s?").

Modules are reusable, self-contained packages of OpenTofu configuration:

Modules can be sourced from the registry, a local path (./modules/vpc), or a Git URL.