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
1---
2name: opentofu
3description: |
4 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.
5
6 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.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.0'
11 source: 'https://opentofu.org/docs'
12user-invocable: false
13---
14
15# OpenTofu
16
17## Overview
18
19OpenTofu 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.
20
21**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).
22
23**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).
24
25## Quick Reference
26
27| Pattern | Tool / Command | Key Points |
28| ------------------ | -------------------------------------- | ---------------------------------------------- |
29| Initialize project | `tofu init` | Downloads providers, initializes backend |
30| Preview changes | `tofu plan` | Shows diff without applying |
31| Apply changes | `tofu apply` | Provisions/updates resources |
32| Destroy resources | `tofu destroy` | Tears down managed infrastructure |
33| Import resource | `tofu import <addr> <id>` | Brings existing resource under management |
34| State encryption | `terraform.encryption` block | OpenTofu-exclusive, AES-GCM with key providers |
35| Remote backend | `backend "s3"` / `backend "gcs"` | Store state in cloud storage with locking |
36| Workspaces | `tofu workspace new <name>` | Isolated state per environment |
37| Module usage | `module "name" { source = "..." }` | Reusable infrastructure components |
38| Output values | `output "name" { value = ... }` | Expose values for other configs or CI |
39| Variable files | `terraform.tfvars` / `-var-file` | Environment-specific variable overrides |
40| Pulumi new project | `pulumi new typescript` | Scaffold TypeScript IaC project |
41| Pulumi preview | `pulumi preview` | Shows planned changes |
42| Pulumi deploy | `pulumi up` | Provisions/updates resources |
43| Pulumi config | `pulumi config set key value` | Stack-scoped configuration |
44| Pulumi secrets | `pulumi config set --secret key val` | Encrypted config values |
45| Pulumi stacks | `pulumi stack select <name>` | Switch between environments |
46| Automation API | `LocalWorkspace.createOrSelectStack()` | Programmatic stack management |
47
48## Common Mistakes
49
50| Mistake | Correct Pattern |
51| ---------------------------------------------------- | ----------------------------------------------------------------- |
52| Storing state locally in team environments | Configure remote backend (S3, GCS, Azure Blob) with state locking |
53| Hardcoding provider credentials in HCL | Use environment variables or provider-specific auth chains |
54| Using `tofu apply` without reviewing plan | Run `tofu plan -out=plan.tfplan` then `tofu apply plan.tfplan` |
55| Editing state manually | Use `tofu state mv`, `tofu state rm`, or `tofu import` |
56| Ignoring `.terraform.lock.hcl` | Commit lock file for reproducible provider versions |
57| Using `count` for complex conditional resources | Prefer `for_each` with maps for stable resource addressing |
58| Sharing one workspace for all environments | Use separate workspaces or backend config per environment |
59| Putting secrets in `terraform.tfvars` | Use `sensitive = true` variables, vault, or environment variables |
60| Pulumi: creating resources outside component classes | Wrap related resources in ComponentResource for reuse |
61| Pulumi: not awaiting async operations | Ensure all resource operations complete before stack export |
62| Skipping `tofu plan` in CI/CD | Always plan and require approval before apply in pipelines |
63| Not using `-target` carefully | Prefer full plans; `-target` can leave state inconsistent |
64
65## Delegation
66
67- **Infrastructure pattern discovery**: Use `Explore` agent
68- **IaC code review**: Use `Task` agent
69- **Drift detection analysis**: Use `Task` agent
70
71> If the `amazon-web-services` skill is available, delegate AWS resource patterns to it.
72> If the `docker` skill is available, delegate container infrastructure patterns to it.
73> If the `github-actions` skill is available, delegate CI/CD pipeline patterns to it.
74
75## References
76
77- [HCL syntax, resources, data sources, and providers](references/hcl-fundamentals.md)
78- [Modules, composition, and reusable infrastructure](references/modules.md)
79- [State management, remote backends, and locking](references/state-management.md)
80- [State encryption with OpenTofu-exclusive key providers](references/state-encryption.md)
81- [Variables, outputs, and environment configuration](references/variables-outputs.md)
82- [Workspaces and multi-environment setups](references/workspaces.md)
83- [Import existing infrastructure and migration patterns](references/import-migration.md)
84- [Pulumi TypeScript and Python SDK patterns](references/pulumi-sdk.md)
85- [Pulumi stacks, config, secrets, and automation API](references/pulumi-stacks.md)
86- [CI/CD integration and drift detection](references/cicd-integration.md)
oakoss