--- title: "Terraform Cheatsheet" description: "Practical Terraform cheatsheet covering essential CLI commands, state management, import, workspaces, and key HCL patterns for variables, locals, outputs, dynamic blocks, and more. Perfect for daily IaC workflows." author: "Mohammad Abu Mattar" canonical: https://mkabumattar.com/cheatsheets/terraform --- # Terraform Cheatsheet A practical cheatsheet covering the Terraform CLI commands engineers reach for constantly, init, plan, apply, import, taint, and state operations, alongside essential HCL patterns for variables, locals, outputs, and dynamic blocks. Browse the sections below to explore Terraform cheatsheet commands, syntax, and examples. ## Core CLI Commands Essential Terraform commands for initialization, validation, planning, applying, and destroying infrastructure. ### Initialization & Validation Commands to set up your Terraform workspace and check configuration validity. **Keywords:** terraform init #### Initializes the working directory, downloads providers and modules. ```bash terraform init ``` _output_ ```text Terraform has been successfully initialized! ``` #### Checks whether the configuration is valid (run after init). ```bash terraform validate ``` _output_ ```text Success! The configuration is valid. ``` #### Upgrades modules and providers to the latest allowed versions. ```bash terraform init -upgrade ``` **Best practices:** - Run terraform init early and often. Commit .terraform.lock.hcl to version control. - Use -input=false in automation to avoid interactive prompts. **Common errors:** - **Provider not found, ensure required_providers block is declared.**: Review documentation or configuration. **Advanced notes:** - **Note:** terraform init -migrate-state helps when changing backends. ### Plan & Apply Preview and execute infrastructure changes safely. **Keywords:** terraform plan, terraform apply #### Shows what Terraform will create, change, or destroy. ```bash terraform plan ``` #### Saves the plan to a file for later apply. ```bash terraform plan -out=plan.tfplan ``` #### Applies a saved plan without prompting. ```bash terraform apply plan.tfplan ``` #### Applies changes without confirmation (use in CI/CD). ```bash terraform apply -auto-approve ``` **Best practices:** - Never run terraform apply in production without reviewing the plan first. - Use -target for surgical changes, but prefer smaller modules for isolation. **Common errors:** - **Permission denied or authentication issues with the provider.**: Review documentation or configuration. **Advanced notes:** - **Note:** terraform apply -replace=resource.address forces replacement without tainting. ### Destroy Safely remove all managed infrastructure. **Keywords:** terraform destroy #### Destroys all resources managed by Terraform. ```bash terraform destroy ``` #### Destroys only the targeted resource. ```bash terraform destroy -target=aws_instance.example ``` **Best practices:** - Use with -auto-approve only in controlled environments. **Common errors:** - **Resources with prevent_destroy lifecycle rule will block destruction.**: Review documentation or configuration. **Advanced notes:** - **Note:** terraform plan -destroy shows what will be removed. ## State Management Commands for inspecting, manipulating, and synchronizing Terraform state. ### State Commands Core operations on the Terraform state file. **Keywords:** state management #### Lists all resources currently tracked in state. ```bash terraform state list ``` #### Shows detailed attributes of a specific resource in state. ```bash terraform state show aws_instance.example ``` #### Moves or renames a resource in state without recreating it. ```bash terraform state mv aws_instance.old aws_instance.new ``` #### Removes a resource from state (does not delete the actual infrastructure). ```bash terraform state rm aws_instance.example ``` **Best practices:** - Use terraform state mv when refactoring resource addresses or module structure. - Pull state before manual edits and push after. **Common errors:** - **Moving resources incorrectly can lead to orphaned infrastructure.**: Review documentation or configuration. **Advanced notes:** - **Note:** terraform state pull > state.tfstate && terraform state push state.tfstate for manual sync. ### Import & Taint Bring existing resources under management and force recreation. **Keywords:** terraform import #### Imports an existing EC2 instance into Terraform state. ```bash terraform import aws_instance.example i-1234567890abcdef0 ``` #### Replaces (recreates) a resource on the next apply (preferred over taint). ```bash terraform apply -replace=aws_instance.example ``` **Best practices:** - After import, run terraform plan and update configuration to match imported state. - Prefer import blocks (Terraform 1.5+) for declarative imports. **Common errors:** - **Import succeeds but plan shows drift, configuration must match reality.**: Review documentation or configuration. **Advanced notes:** - **Note:** For count/for_each resources, use proper addressing like aws_instance.example["key"]. ### State Pull & Push Synchronize local and remote state files. **Keywords:** state management #### Downloads the current remote state. ```bash terraform state pull ``` #### Uploads a local state file to the remote backend. ```bash terraform state push state.tfstate ``` **Best practices:** - Use only when necessary; let Terraform handle state automatically with backends. **Common errors:** - **Pushing an outdated state can cause conflicts or data loss.**: Review documentation or configuration. **Advanced notes:** - **Note:** Always backup state before push operations. ## Workspaces Manage multiple isolated state environments (dev, staging, prod) with the same code. ### Workspace Commands Create, switch, list, and delete workspaces. **Keywords:** terraform workspace #### Creates and switches to a new workspace named 'dev'. ```bash terraform workspace new dev ``` #### Lists all workspaces (* indicates current). ```bash terraform workspace list ``` #### Switches to the 'prod' workspace. ```bash terraform workspace select prod ``` #### Deletes the 'dev' workspace (must not be current). ```bash terraform workspace delete dev ``` **Best practices:** - Use workspaces for environment isolation when using the same configuration. - Combine with variable files: terraform apply -var-file=dev.tfvars **Common errors:** - **Deleting a workspace with resources leaves orphaned infrastructure.**: Review documentation or configuration. **Advanced notes:** - **Note:** Workspaces are not recommended for large team or complex environment separation, consider modules or separate repositories. ## HCL Essentials Core HashiCorp Configuration Language patterns used in every Terraform project. ### Variables, Locals & Outputs Input variables, computed locals, and exposed outputs. **Keywords:** variables #### Defines a variable with default, a local for reuse, and an output. ```bash variable "region" { type = string default = "us-east-1" } locals { common_tags = { Environment = var.environment ManagedBy = "Terraform" } } output "vpc_id" { value = aws_vpc.main.id description = "The ID of the VPC" } ``` **Best practices:** - Keep variables minimal and descriptive; use locals for derived values to reduce repetition. - Always add descriptions to outputs and sensitive = true where needed. **Common errors:** - **Variable not defined, declare it or pass via -var or .tfvars file.**: Review documentation or configuration. **Advanced notes:** - **Note:** Use data sources to fetch dynamic values instead of hardcoding in variables. ### Data Sources Read-only queries for external data. **Keywords:** data sources #### Fetches the latest Ubuntu AMI for use in resources. ```bash data "aws_ami" "ubuntu" { most_recent = true owners = ["099720109477"] # Canonical filter { name = "name" values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"] } } ``` **Best practices:** - Use data sources to avoid hardcoding IDs or dynamic values. **Common errors:** - **Data source returns empty, check filters and permissions.**: Review documentation or configuration. **Advanced notes:** - **Note:** Data sources run during plan and can depend on resources. ## Dynamic Blocks & for_each Advanced HCL patterns for repeatable configuration. ### for_each & Dynamic Blocks Create multiple resource instances and nested blocks dynamically. **Keywords:** for_each #### Creates one IAM user per item in the set using for_each. ```bash resource "aws_iam_user" "users" { for_each = toset(["alice", "bob"]) name = each.key } ``` #### Generates multiple ingress blocks dynamically from a list/map. ```bash resource "aws_security_group" "example" { name = "example" dynamic "ingress" { for_each = var.ingress_rules content { from_port = ingress.value.from_port to_port = ingress.value.to_port protocol = ingress.value.protocol cidr_blocks = ingress.value.cidr_blocks } } } ``` **Best practices:** - Use for_each over count for readability and stability (keys instead of indices). - Limit dynamic blocks to improve readability; prefer explicit blocks when possible. **Common errors:** - **for_each value must be a map or set, convert lists with toset().**: Review documentation or configuration. **Advanced notes:** - **Note:** Nested dynamic blocks are supported with different iterator names. ## Provider Configuration Common patterns for configuring Terraform providers. ### Provider Patterns Declaring and configuring providers, including aliases. **Keywords:** modules #### Required providers block and basic + aliased configuration. ```bash terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 5.0" } } } provider "aws" { region = var.region } # Aliased provider for multi-region provider "aws" { alias = "west" region = "us-west-2" } ``` **Best practices:** - Declare required_providers in the root module. Avoid configuring providers inside child modules. - Use aliases for multi-region or multi-account deployments. **Common errors:** - **Provider not initialized, run terraform init after adding providers.**: Review documentation or configuration. **Advanced notes:** - **Note:** Pass aliased providers to modules explicitly via the providers = { ... } meta-argument. ## Debugging Tools and techniques for troubleshooting Terraform issues. ### Logging & Terraform Console Enable detailed logs and test expressions interactively. **Keywords:** terraform console #### Enables the most verbose logging (TRACE, DEBUG, INFO, WARN, ERROR). ```bash TF_LOG=TRACE terraform plan ``` #### Interactive REPL to test expressions and functions. ```bash terraform console ``` _output_ ```text > join(", ", ["a", "b"]) "a, b" ``` **Best practices:** - Start with DEBUG or TRACE only when needed; logs can be extremely verbose. - Use terraform console to validate complex expressions before using them in code. **Common errors:** - **No output from console, ensure you're in a directory with initialized Terraform config.**: Review documentation or configuration. **Advanced notes:** - **Note:** Set TF_LOG_PATH to write logs to a file. ## Modules Package and reuse configurations with module blocks sourced from local paths, Git, or public/private registries with version pinning. ### Calling a Module A module block instantiates reusable config; source is required and version applies only to registry sources. **Keywords:** module, source, outputs #### Call a registry module with a version constraint ```hcl module "vpc" { source = "terraform-aws-modules/vpc/aws" # NAMESPACE/NAME/PROVIDER version = "~> 5.0" # pessimistic constraint name = "prod-vpc" cidr = "10.0.0.0/16" } ``` Instantiates a child module from the public registry; version is honored only for registry sources. - Modules also accept count, for_each, depends_on, and an explicit providers mapping. #### Reference a module output ```hcl resource "aws_instance" "web" { subnet_id = module.vpc.private_subnet_ids[0] # module.. } ``` A module exposes only values declared as output blocks; reach them as module... **Best practices:** - Keep module interfaces small - expose IDs and ARNs via output, take everything configurable via variable, and never reach into a module's internal resources from the caller. **Common errors:** - **Module not installed or "Module source has changed" on plan.**: Run terraform init (or terraform get) to fetch modules. After changing source or version you must re-run terraform init - plain terraform get will not update the lock. ### Source Types & terraform get Modules load from local paths, Git, or registries; terraform get and init keep them current. **Keywords:** git, registry, terraform get #### Source a module from Git at a pinned tag ```hcl module "network" { # // separates the repo from a subdirectory, ?ref pins a tag/branch/commit source = "git::https://github.com/org/repo.git//modules/vpc?ref=v1.4.0" } ``` Git source with a subdirectory and a pinned ref for reproducible init. - The GitHub shorthand github.com/org/repo//modules/vpc?ref=v1.4.0 expands to this HTTPS form. #### Download and upgrade modules ```bash terraform get # download modules into .terraform/modules terraform get -update # upgrade modules to the newest allowed terraform init -upgrade # upgrade modules AND providers, rewrite the lock ``` terraform get fetches modules only; init -upgrade also handles providers and rewrites .terraform.lock.hcl. **Best practices:** - Use terraform init -upgrade when intentionally bumping versions and commit the updated lock; use plain terraform init in CI to enforce the locked versions. ## Variables & Outputs Parameterize configurations with typed, validated inputs and expose results through outputs, supplied via tfvars, flags, or environment. ### Declaration, Types & Validation Declare typed input variables with optional defaults and custom validation rules checked at plan time. **Keywords:** variable, validation, type #### Typed variable with a default ```hcl variable "instance_count" { type = number # string | number | bool | list()/set()/map()/object() default = 2 # omit default to make the variable required } ``` Without a default the variable is required; complex types use list(...), map(...), object({...}). #### Enforce allowed values with validation ```hcl variable "env" { type = string validation { condition = contains(["dev", "staging", "prod"], var.env) error_message = "env must be dev, staging, or prod." } } ``` The validation block fails fast at plan time; error_message must be a full sentence ending in a period. **Best practices:** - Give every input a type and a description, and use validation to reject bad input up front rather than letting the provider fail mid-apply. ### Supplying Values & Outputs Values come from tfvars, -var flags, or TF_VAR_ env vars by precedence; outputs surface results and can be marked sensitive. **Keywords:** tfvars, TF_VAR, output #### Pass variables by flag, file, or environment ```bash terraform apply -var="instance_count=3" # inline (highest precedence) terraform apply -var-file="prod.tfvars" # from a file export TF_VAR_instance_count=3 # environment form ``` Precedence low to high - TF_VAR_* < terraform.tfvars < *.auto.tfvars < -var/-var-file (last on the line wins). - terraform.tfvars and *.auto.tfvars load automatically; named files need -var-file. #### Declare an output and read it for scripts ```bash # output "db_endpoint" { value = aws_db_instance.main.address } terraform output # all outputs, human-readable terraform output -json # machine-readable terraform output -raw db_endpoint # raw string, no quotes ``` -raw and -json are the scripting-friendly forms; mark secrets sensitive = true to redact them from CLI and plan output. **Best practices:** - Mark credential outputs sensitive = true, but remember state is plaintext - protect the backend rather than relying on sensitive as encryption. **Common errors:** - **"No value for required variable" in non-interactive CI.**: Pass -var/-var-file or set TF_VAR_*, and add -input=false so the run fails fast instead of hanging on a prompt. ## Backends & Remote State Store state remotely with locking (S3, HCP Terraform) and consume other stacks' outputs via the terraform_remote_state data source. ### S3 Backend with Native Locking Store state in S3 with encryption and a native lockfile (Terraform 1.10+), replacing the deprecated DynamoDB lock table. **Keywords:** backend, s3, locking #### S3 backend with native lockfile (TF 1.10+) ```hcl terraform { backend "s3" { bucket = "my-tf-state" key = "prod/network/terraform.tfstate" region = "us-east-1" encrypt = true use_lockfile = true # native S3 lock, no DynamoDB (TF 1.10+) } } ``` use_lockfile uses an S3 conditional-write lock object; requires bucket versioning. dynamodb_table is deprecated as of 1.11. - Enable bucket versioning and encrypt = true; you can run use_lockfile and dynamodb_table together during migration, then drop DynamoDB. **Best practices:** - Back up state before any backend change with terraform state pull > backup.tfstate. **Common errors:** - **Error acquiring the state lock (stale lock).**: Resolve the interrupted run, then terraform force-unlock . Never force-unlock while another apply may still be live. ### Remote State & Migration Read another config's outputs with terraform_remote_state, connect to HCP Terraform, and migrate between backends. **Keywords:** terraform_remote_state, cloud, migrate-state #### Consume another stack's outputs ```hcl data "terraform_remote_state" "network" { backend = "s3" config = { bucket = "my-tf-state" key = "prod/network/terraform.tfstate" region = "us-east-1" } } # use: data.terraform_remote_state.network.outputs.private_subnet_ids[0] ``` Read-only access to another configuration's published outputs; only declared output values are visible. #### Migrate or reconfigure the backend ```bash terraform init -migrate-state # copy state into a newly changed backend terraform init -reconfigure # reinit backend, ignore existing state terraform init -backend-config=backend.hcl # partial config from a file ``` -migrate-state copies existing state into the new backend; -reconfigure discards the old association without copying. **Best practices:** - Use the cloud block (HCP Terraform, renamed from Terraform Cloud) for managed runs; it is mutually exclusive with a backend block. Run terraform login first. ## Functions & Expressions Transform and compute values with built-in functions, for/conditional/splat expressions, and the interactive console. ### Common Built-in Functions Encode/decode data, merge maps, provide defaults, and compute network ranges with built-in functions. **Keywords:** functions, templatefile, jsonencode #### Everyday functions ```hcl user_data = templatefile("${path.module}/init.tftpl", { port = var.port }) config = jsonencode({ name = var.name, tags = var.tags }) merged = merge(var.default_tags, var.extra_tags) # right map wins name = coalesce(var.name, "unnamed") # first non-empty port = try(var.settings.port, 8080) # first that succeeds subnet = cidrsubnet("10.0.0.0/16", 8, 4) # -> 10.0.4.0/24 ``` templatefile renders external templates (use it instead of the removed template_file data source); try swallows evaluation errors. - jsondecode/yamldecode parse strings back into HCL values; lookup(map, key, default) reads a map with a fallback. **Best practices:** - Reach for try() to handle optional nested attributes gracefully, but do not let it silently mask real configuration errors. ### for, Conditionals & Console Reshape collections with for expressions, choose with conditionals, collect with splat, and prototype in terraform console. **Keywords:** for, splat, console #### for, conditional, and splat expressions ```hcl upper_names = [for n in var.names : upper(n) if n != ""] # list + filter by_id = { for s in var.subnets : s.id => s.cidr } # produce a map instance_type = var.env == "prod" ? "m5.large" : "t3.micro" # ternary all_ips = aws_instance.web[*].private_ip # splat ``` [...] yields a list, {...} yields a map; splat [*] pulls one attribute across every instance. #### Prototype expressions in the console ```bash terraform console # interactive REPL echo 'cidrsubnet("10.0.0.0/16", 8, 2)' | terraform console # pipe input ``` Evaluates functions, variables, and resource attributes against real state without running a plan. **Best practices:** - Prototype tricky for and function expressions in terraform console before wiring them into config - it evaluates against actual state values. ## Testing & Validation Validate, format, and test configurations with the native test framework, lifecycle assertions, check blocks, and ecosystem linters. ### validate & fmt Check syntax and enforce canonical style, with non-mutating forms for CI gates. **Keywords:** validate, fmt, ci #### Validate and format ```bash terraform validate # syntax + internal consistency terraform fmt -check -recursive # exit non-zero if anything is unformatted terraform fmt -diff # show changes without writing ``` validate needs init first; fmt -check -recursive is the CI-friendly, non-mutating form. **Best practices:** - Run terraform fmt -check -recursive and terraform validate as required PR checks so style and basic errors never reach review. **Common errors:** - **terraform validate reports "Backend initialization required".**: Run terraform init -backend=false first - validate needs providers and modules installed but not a live backend. ### terraform test & Assertions Write native tests in .tftest.hcl and enforce invariants with precondition, postcondition, and check blocks. **Keywords:** test, precondition, check #### A native test file (TF 1.6+) ```hcl # tests/vpc.tftest.hcl run "creates_vpc" { command = plan # "plan" (fast) or "apply" (real infra) variables { cidr = "10.0.0.0/16" } assert { condition = aws_vpc.this.cidr_block == "10.0.0.0/16" error_message = "VPC CIDR did not match input." } } ``` The native framework is stable in Terraform 1.6+; run terraform test to execute every *.tftest.hcl file. - Prefer command = plan for fast unit-style assertions; command = apply creates then destroys real infrastructure. #### Lifecycle and check assertions ```hcl lifecycle { precondition { condition = data.aws_ami.selected.architecture == "x86_64" error_message = "AMI must be x86_64." } } # check "health" { ... } -> failed check is a WARNING, not an error (TF 1.5+) ``` precondition/postcondition (TF 1.2+) hard-stop on failure; check blocks (TF 1.5+) only warn, good for post-deploy validation. **Best practices:** - Layer the tools - terraform validate for correctness, tflint for provider-aware linting, and checkov for security policy - rather than expecting one tool to cover all three.