opentofu

name	opentofu
description	Infrastructure as code with OpenTofu (open-source Terraform fork) and Pulumi. Covers OpenTofu HCL syntax, providers, resources, data sources, modules, state management with remote backends, workspaces, importing existing infrastructure, plan/apply workflow, variable management, output values, provisioners, and state encryption (OpenTofu-exclusive). Includes Pulumi TypeScript/Python SDKs, stack management, component resources, config/secrets, state backends, policy as code, and automation API. Common patterns for multi-environment setups, module composition, CI/CD integration, drift detection, and secret management. Use when writing or reviewing HCL configurations, managing cloud infrastructure state, migrating from Terraform to OpenTofu, building Pulumi programs in TypeScript or Python, setting up multi-environment IaC pipelines, or implementing state encryption.
license	MIT
metadata	{"author":"oakoss","version":"1.0","source":"https://opentofu.org/docs"}
user-invocable	false

OpenTofu

Overview

OpenTofu is an open-source infrastructure as code tool that uses HCL (HashiCorp Configuration Language) to declaratively manage cloud infrastructure. It is a community-driven fork of Terraform, fully compatible with existing Terraform providers and modules, with exclusive features like native state encryption. Pulumi provides an alternative IaC approach using general-purpose languages (TypeScript, Python, Go) instead of HCL.

When to use: Managing cloud infrastructure declaratively, provisioning multi-cloud resources, enforcing infrastructure consistency across environments, encrypting state at rest (OpenTofu), using familiar programming languages for IaC (Pulumi).

When NOT to use: One-off scripts better suited to CLI tools, application-level configuration management (use Ansible/Chef), container orchestration logic (use Kubernetes manifests), simple static hosting (use platform-native tools).

Quick Reference

Pattern	Tool / Command	Key Points
Initialize project	tofu init	Downloads providers, initializes backend
Preview changes	tofu plan	Shows diff without applying
Apply changes	tofu apply	Provisions/updates resources
Destroy resources	tofu destroy	Tears down managed infrastructure
Import resource	tofu import <addr> <id>	Brings existing resource under management
State encryption	terraform.encryption block	OpenTofu-exclusive, AES-GCM with key providers
Remote backend	backend "s3" / backend "gcs"	Store state in cloud storage with locking
Workspaces	tofu workspace new <name>	Isolated state per environment
Module usage	module "name" { source = "..." }	Reusable infrastructure components
Output values	output "name" { value = ... }	Expose values for other configs or CI
Variable files	terraform.tfvars / -var-file	Environment-specific variable overrides
Pulumi new project	pulumi new typescript	Scaffold TypeScript IaC project
Pulumi preview	pulumi preview	Shows planned changes
Pulumi deploy	pulumi up	Provisions/updates resources
Pulumi config	pulumi config set key value	Stack-scoped configuration
Pulumi secrets	pulumi config set --secret key val	Encrypted config values
Pulumi stacks	pulumi stack select <name>	Switch between environments
Automation API	LocalWorkspace.createOrSelectStack()	Programmatic stack management

Common Mistakes

Mistake	Correct Pattern
Storing state locally in team environments	Configure remote backend (S3, GCS, Azure Blob) with state locking
Hardcoding provider credentials in HCL	Use environment variables or provider-specific auth chains
Using tofu apply without reviewing plan	Run tofu plan -out=plan.tfplan then tofu apply plan.tfplan
Editing state manually	Use tofu state mv, tofu state rm, or tofu import
Ignoring .terraform.lock.hcl	Commit lock file for reproducible provider versions
Using count for complex conditional resources	Prefer for_each with maps for stable resource addressing
Sharing one workspace for all environments	Use separate workspaces or backend config per environment
Putting secrets in terraform.tfvars	Use sensitive = true variables, vault, or environment variables
Pulumi: creating resources outside component classes	Wrap related resources in ComponentResource for reuse
Pulumi: not awaiting async operations	Ensure all resource operations complete before stack export
Skipping tofu plan in CI/CD	Always plan and require approval before apply in pipelines
Not using -target carefully	Prefer full plans; -target can leave state inconsistent

Delegation

• Infrastructure pattern discovery: Use Explore agent
• IaC code review: Use Task agent
• Drift detection analysis: Use Task agent

If the amazon-web-services skill is available, delegate AWS resource patterns to it. If the docker skill is available, delegate container infrastructure patterns to it. If the github-actions skill is available, delegate CI/CD pipeline patterns to it.

References

• HCL syntax, resources, data sources, and providers
• Modules, composition, and reusable infrastructure
• State management, remote backends, and locking
• State encryption with OpenTofu-exclusive key providers
• Variables, outputs, and environment configuration
• Workspaces and multi-environment setups
• Import existing infrastructure and migration patterns
• Pulumi TypeScript and Python SDK patterns
• Pulumi stacks, config, secrets, and automation API
• CI/CD integration and drift detection