Infrastructure-as-code best practices on AWS — the senior-engineer reference (2026).

IWhat "good IaC on AWS" actually looks like in 2026

Before the tool debate, agree on the target. A healthy infrastructure-as-code estate has a small number of observable properties. If you can answer yes to all of them, the tool you picked is almost irrelevant. If you cannot, no tool will save you.

A mature estate is reproducible: any environment can be rebuilt from code in a fresh account with no undocumented manual steps. It is reviewable: every change to production infrastructure arrives as a pull request with a machine-generated plan attached, so a second engineer can see exactly which resources will be created, changed, or destroyed before anyone clicks merge. It is isolated: a mistake in the staging networking module cannot take down production, because the blast radius of any single apply is bounded by design.

It is governed: policy runs automatically against every plan — no public S3 buckets, no unencrypted volumes, no 0.0.0.0/0 SSH — so compliance is enforced by the pipeline rather than by a human remembering. And it is honest: the code matches reality, because drift is detected on a schedule and the console is effectively read-only for humans. Manual changes are the exception that triggers an alert, not the norm.

Almost every real-world IaC problem is a violation of one of those five properties, not a bug in Terraform or CDK. A team that says "Terraform is painful" usually means "we share one state file across five environments and our applies block each other" (an isolation failure) or "our root module is 4,000 lines and every change touches everything" (a blast-radius failure). The rest of this guide is organized around getting those five properties right, in roughly the order they bite.

IIChoosing the tool: Terraform, OpenTofu, CDK, CloudFormation, Pulumi

There are five credible tools in 2026, and the honest framing is that the choice is mostly about your team and your estate, not about a technical winner. Below is what each is genuinely good at, what it costs you, and the situations where it is the right default.

The decision splits on two axes. First, declarative configuration (HCL, YAML) vs real programming languages (TypeScript, Python, Go): configuration languages are easier to read and review and harder to abuse; real languages give you loops, abstractions, and unit tests at the cost of unbounded complexity. Second, multi-cloud vs AWS-native: if you are AWS-only forever, native tools integrate more deeply; if you run or might run anything else, a cloud-agnostic engine avoids a rewrite.

The single most important rule across all five: pick one primary tool per estate and standardize on it. The most common avoidable mess in 2026 is a company running Terraform for networking, CDK for application stacks, and ad-hoc CloudFormation for "that one legacy thing," with no shared state strategy and three sets of conventions. A second tool is justified only when there is a hard boundary — for example, CDK for application teams who ship constructs, with a platform team owning the foundational accounts in Terraform — and even then the boundary must be explicit and the state stores must not overlap.

IIIRemote state and locking — get this wrong and nothing else matters

State is where IaC estates actually fail. The tool tracks what it believes exists in a state file; if two people apply at once, or the file lives on someone's laptop, or it has no isolation between environments, you get corruption, race conditions, and the worst outcome of all — an apply that destroys production because the state disagreed with reality.

For Terraform and OpenTofu on AWS, the canonical pattern is an S3 backend for the state object plus locking. Historically locking used a DynamoDB table; as of late 2024 the S3 backend supports native state locking via the use_lockfile option, which removes the separate DynamoDB dependency for new setups. Either way, the non-negotiables are the same: server-side encryption on the bucket, versioning enabled (so you can roll back a corrupted state), bucket policies that block public access, and a lock so that a second apply blocks rather than racing.

CDK and CloudFormation sidestep the state-file problem because AWS manages state inside the stack — there is no terraform.tfstate to lose. That is a genuine operational advantage. The flip side is that you inherit CloudFormation's drift-detection and rollback model, and you give up the granular plan/state introspection that Terraform users rely on. Pulumi defaults to its hosted backend, which similarly removes the "where does state live" decision at the cost of a managed dependency.

The isolation rule is universal and is the part teams most often get wrong: one state file per environment per component, never a single shared state for everything. A monolithic state where dev, staging, and production networking all live together means every plan locks every environment, blast radius is unbounded, and a fat-fingered destroy can cascade. Split state by environment first (dev / staging / prod in separate accounts and separate state objects), then by component within an environment (networking, data, application) once an environment's state grows large enough that plans become slow or scary.

IVModule design and reuse — small, versioned, explicit

Modules are how you stop copy-pasting infrastructure. Done well, a module is a reliable building block; done badly, it becomes a god-object whose every change ripples unpredictably across environments. The difference is almost entirely about size, interface discipline, and versioning.

A good module does one thing and exposes a small, explicit interface: a clear set of input variables with types and sensible defaults, and a clear set of outputs. It should be possible to read a module's inputs and outputs and understand exactly how it composes into the rest of the estate without reading its internals. Resist the urge to build a single "platform" module that provisions networking, compute, data, and IAM in one call — that is a god-object, and it forces every consumer to upgrade in lockstep.

The reuse boundary that matters most is the line between foundational modules (a VPC, a baseline IAM setup, a logging configuration) that change rarely and are shared across the whole org, and composition (the root configuration for a given environment that wires foundational modules together with environment-specific values). Foundational modules should live in their own repository or registry, be semantically versioned, and be consumed by pinned version. Composition lives close to the environment it describes.

Versioning is the discipline that makes reuse safe. Pin module versions explicitly — never consume a shared module from a floating main branch, because then any merge to that module silently changes every environment that references it. Pin to a tag or a version constraint, bump deliberately, and let the change flow environment-by-environment through the normal review pipeline. The same applies to providers: pin the AWS provider version and the required tool version so that an unrelated upgrade does not surprise you mid-apply.

• One module, one responsibility — A module provisions a coherent unit (a VPC, a service, a bucket-with-policy). If you cannot describe it in one sentence, split it.
• Explicit typed inputs, explicit outputs — Every variable typed with a description and a default where safe; outputs that downstream modules actually consume. The interface is the contract.
• Pin versions — never float on main — Consume shared modules and providers by version tag or constraint. Floating references turn one merge into an estate-wide change.
• Separate foundational modules from composition — Shared building blocks live in their own versioned repo/registry; environment root configs wire them together with local values.
• Prefer composition over deep inheritance — Wire small modules together at the root rather than nesting modules many layers deep — deep nesting hides blast radius and makes plans hard to read.
• Keep environment differences in variables, not in forks — Dev and prod should run the same module code with different inputs. If they have diverged into separate copies, drift is inevitable.

VMulti-account and multi-environment structure

On AWS, the account is the strongest isolation boundary there is — stronger than a VPC, stronger than an IAM policy. Serious 2026 estates use multiple accounts deliberately, and the IaC structure should mirror that account topology rather than fight it.

The widely adopted pattern is a multi-account landing zone: a management/organization account at the root, with separate accounts (or organizational units) for security/audit, shared services, logging, and then per-workload-per-environment accounts — a distinct account for production, another for staging, another for development. This is what AWS Control Tower and AWS Organizations are built to manage, and it gives you hard blast-radius boundaries: a runaway process in dev cannot touch production resources, and per-account billing makes cost attribution trivial.

IaC structure should follow that topology. Each account-environment gets its own state (for Terraform/OpenTofu) or its own set of stacks (for CDK/CloudFormation), and cross-account concerns — a centralized logging bucket, an organization-wide guardrail — are provisioned from the account that owns them and referenced by ID elsewhere. Resist the temptation to provision production resources from a state that also contains dev; the account boundary is only as strong as the isolation of the thing that writes into it.

Two structural anti-patterns are worth naming. The first is one giant account with everything in it, distinguished only by resource tags — tags are not a security boundary, and a single compromised credential or a single bad apply reaches everything. The second is directory-per-environment with copy-pasted code, where dev/ and prod/ contain forked copies of the same configuration that have quietly drifted apart. The healthy middle is shared module code consumed by thin per-environment root configurations, each pointing at its own account and its own state, differing only in variable values.

VICI/CD for IaC — every change is a reviewed plan

The pipeline is what turns a pile of HCL or TypeScript into a governed system. The defining property of a healthy IaC pipeline is that <strong>nobody applies from a laptop</strong>: changes flow through pull requests, a plan is generated automatically and posted for review, and apply happens only from CI after the plan is approved.

The canonical flow for Terraform/OpenTofu is: a pull request triggers fmt, validate, a lint pass, a security scan, and a plan; the plan output is posted as a comment on the PR so a reviewer can read exactly what will change; on merge to the main branch, CI runs apply against the saved plan artifact — never a fresh plan, because re-planning at apply time can pick up changes the reviewer never saw. CDK and CloudFormation follow the same shape: synth/diff on PR, deploy on merge, with change sets giving CloudFormation users an equivalent of the plan-review step.

The apply gate is the load-bearing control. Production applies should require an explicit human approval after the plan is reviewed (a protected environment or a manual approval step), so that even a merged change pauses before it touches production. Many teams run apply automatically for dev, require review-then-auto-apply for staging, and require review-plus-manual-approval for production. The point is graduated friction that scales with blast radius.

A few execution details separate robust pipelines from fragile ones. Save the plan as an artifact and apply that exact artifact so review and apply cannot diverge. Use short-lived credentials — OIDC federation from the CI provider into an AWS IAM role, not long-lived access keys baked into CI secrets. Serialize applies per state so two merges cannot apply against the same state concurrently. And make plans legible by keeping state files small enough that a plan is reviewable in a minute, not a 600-line diff nobody reads.

VIIPolicy-as-code, testing, and secrets

Review by a human catches design problems; it does not reliably catch a forgotten encryption flag at 6pm on a Friday. Policy-as-code and automated tests are how you make the non-negotiables non-negotiable — enforced by the pipeline rather than by vigilance.

Policy-as-code evaluates rules against your plan before apply and fails the build on a violation. The three common engines: Sentinel (HashiCorp's policy language, tightly integrated with Terraform Cloud/Enterprise), OPA/Rego (Open Policy Agent — vendor-neutral, works across tools and beyond IaC), and Checkov (an open-source scanner from Bridgecrew/Prisma with a large library of built-in checks for AWS misconfigurations). A typical policy set blocks public S3 buckets, unencrypted EBS volumes and RDS instances, security groups open to 0.0.0.0/0 on sensitive ports, IAM policies with wildcard actions on wildcard resources, and missing mandatory tags. The win is that these rules run on every plan automatically — compliance becomes a property of the pipeline.

Testing spans a spectrum. At the cheapest end, tflint and validate catch syntax and provider misuse in seconds. Static security scanners (tfsec, Checkov) catch misconfigurations without deploying anything. At the more expensive end, Terratest (a Go library) and Terraform's native test framework actually deploy resources into a sandbox account, assert that they behave correctly, and tear them down — real integration tests for infrastructure. CDK and Pulumi users get unit testing in their native language essentially for free, asserting on the synthesized template. Most teams should run lint plus static scanning on every PR and reserve full deploy-and-assert tests for the highest-value modules.

Secrets must never live in state in plaintext, in variable files committed to git, or in plan output. Terraform/OpenTofu state can contain sensitive values, so encrypt state at rest (S3 SSE, or OpenTofu/Pulumi native state encryption) and pull secrets at apply time from AWS Secrets Manager, SSM Parameter Store (SecureString), or a vault — referenced by name, not embedded. Mark sensitive variables as such so they are redacted from logs, and prefer IAM roles and short-lived credentials over any stored long-lived key. The cardinal sin is a long-lived AWS access key committed to a .tfvars file in the repo.

VIIIDrift detection and migrating off ClickOps

The two slow killers of an IaC estate are drift (reality diverging from code) and ClickOps (humans changing infrastructure in the console). They are the same disease: every manual change makes the code a little more of a lie until, eventually, nobody trusts a plan and people stop using the pipeline at all.

Drift happens when something changes a resource outside your IaC — an engineer tweaks a security group in the console during an incident, an auto-scaling process adjusts capacity, or a separate tool mutates a tag. The defense is detection on a schedule: run terraform plan (or CloudFormation drift detection, or the Pulumi equivalent) on a cron, and alert when the plan is non-empty against an unchanged codebase. Detected drift forces a decision — either the change was legitimate and should be codified, or it was a mistake and should be reverted by re-applying. What you must not do is let drift accumulate silently; a quarter of unaddressed drift turns every future plan into a minefield.

Migrating off ClickOps — adopting IaC for an estate that was built by hand — is the most common real-world starting point, and it is an incremental, one-way journey rather than a big-bang rewrite. The sequence that works: inventory what exists; write module code that describes the target state; import the existing resources into state so the tool adopts them without recreating them (Terraform/OpenTofu import blocks make this far less painful than the old per-resource CLI imports; CloudFormation supports importing existing resources into a stack); reconcile until plan shows no changes; then repeat for the next set of resources. Start with the highest-blast-radius, slowest-changing resources (networking, IAM, data stores) because those are where a manual mistake hurts most and where codification pays off fastest.

The decisive final step is closing the one-way door: once a resource is under IaC, take write access away from humans in the console. Scope human IAM to read-only for managed resource types and let the CI role be the only principal that can mutate them. Until you do this, drift will keep returning, because the path of least resistance during an incident is always the console. Making the pipeline the only thing that writes is what converts IaC from "we have some Terraform" into "infrastructure is genuinely code."

• Detect drift on a schedule — Run plan / drift detection on a cron and alert on any non-empty diff against unchanged code. Never let drift accumulate silently.
• Codify or revert — decide every time — Each detected drift is a fork: legitimate change → bring it into code; mistake → re-apply to revert. Leaving it unresolved is the failure mode.
• Import the highest-blast-radius resources first — Networking, IAM, and data stores before stateless app resources. Use import blocks (Terraform/OpenTofu) or stack resource import (CloudFormation).
• Accept a messy interim state — A half-migrated estate is normal and fine. Converge incrementally; do not block on a perfect big-bang cutover.
• Close the door: read-only console for humans — Once a resource is managed, the CI role is the only principal that may write it. This is what makes the migration stick.

IXThe IaC best-practices checklist

The compressed reference. If you are auditing an existing AWS IaC estate or standing one up from scratch, work down this list. Each item maps to one of the five properties from the opening section — reproducible, reviewable, isolated, governed, honest.

No estate hits all of these on day one, and that is fine — the list is a direction, not a gate. The ordering roughly tracks how badly each gap will hurt: state and isolation first, because they cause the catastrophic failures; review gates and policy next, because they prevent the recurring ones; testing and drift discipline last, because they are what keep a healthy estate healthy over years.

• One primary tool, standardized — A single primary IaC tool per estate with documented conventions. A second tool only at an explicit, non-overlapping boundary.
• Remote state, encrypted, versioned, locked — State in S3 (or managed by CDK/CloudFormation/Pulumi), encrypted at rest, versioned, with locking so concurrent applies cannot race.
• State isolated per environment and per component — No single shared state across environments. Split by env first, then by component as state grows. Mirror your AWS account topology.
• Small, versioned, explicitly-typed modules — One responsibility per module; pinned versions, never floating on main; foundational modules separated from environment composition.
• Multi-account landing zone — Separate AWS accounts per environment (and for security/logging/shared services). Tags are not a security boundary; the account is.
• PR-driven plan, CI-only apply — Every change is a PR with a machine-generated plan posted for review. Apply the saved plan artifact from CI — never from a laptop, never a fresh re-plan.
• Graduated apply gates — Auto-apply dev, review staging, review-plus-manual-approval for production. Friction scales with blast radius.
• Short-lived CI credentials (OIDC) — CI federates into an AWS IAM role via OIDC. No long-lived access keys in CI secrets or repos.
• Policy-as-code on every plan — Sentinel / OPA / Checkov enforce org guardrails — no public buckets, no unencrypted volumes, no wildcard IAM, mandatory tags — automatically.
• Tiered testing — Lint + static scan on every PR; deploy-and-assert integration tests (Terratest / native test / CDK assertions) for high-value modules.
• Secrets out of state and out of git — Pull from Secrets Manager / SSM SecureString / vault at apply time; encrypt state; mark sensitive variables; never commit keys.
• Scheduled drift detection + read-only console — Cron drift detection with alerting; codify-or-revert every diff; revoke human console write access once a resource is managed.