Terraform modules are how you turn raw Terraform into a reusable, versioned \u201clibrary\u201d of infrastructure components. In this article we\u2019ll go through what modules are, the types you\u2019ll see in practice, how to create them, when to factor code into a module, how to update them safely, how to publish them, and finally how to consume them from your stacks.<\/p>\n
At its core, a module is just a directory containing Terraform configuration that can be called from other Terraform code.<\/p>\n
.tf<\/code> files is a module.<\/li>\n- The directory where you run
terraform init\/plan\/apply<\/code> is your root module<\/strong>.<\/li>\n- A root module can call child modules<\/strong> via
module<\/code> blocks, which is how you achieve reuse and composition.<\/li>\n<\/ul>\nConceptually, a module is like a function in code:<\/p>\n
\n- Inputs \u2192 variables<\/li>\n
- Logic \u2192 resources, locals, data sources<\/li>\n
- Outputs \u2192 values other code can depend on<\/li>\n<\/ul>\n
Good modules hide internal complexity behind a clear, minimal interface, exactly as you\u2019d expect from a well\u2011designed API.<\/p>\n
\nTypes of modules you\u2019ll deal with<\/h2>\n
In practice you\u2019ll encounter several \u201ctypes\u201d or roles of modules:<\/p>\n
\n- Root module<\/strong>\n
\n- The entrypoint of a stack (e.g.
envs\/prod<\/code>), where you configure providers, backends, and call other modules.<\/li>\n- Represents one deployable unit: a whole environment, a service, or a single app stack.<\/li>\n<\/ul>\n<\/li>\n
- Child \/ reusable modules<\/strong>\n
\n- Reusable building blocks: VPCs, EKS clusters, RDS databases, S3 buckets, etc.<\/li>\n
- Usually live under
modules\/<\/code> in a repo, or in a separate repo entirely.<\/li>\n- Called from root or other modules with
module "name" { ... }<\/code>.<\/li>\n<\/ul>\n<\/li>\n- Public registry modules<\/strong>\n
\n- Published to the public Terraform Registry, versioned and documented.<\/li>\n
- Example:
terraform-aws-modules\/vpc\/aws<\/code><\/li>\n- Great for standard primitives (VPCs, security groups, S3, etc.), less so for business\u2011specific patterns.<\/li>\n<\/ul>\n<\/li>\n
- Private\/organizational modules<\/strong>\n
\n- Hosted in private registries or Git repos.<\/li>\n
- Usually represent your organization\u2019s conventions and guardrails (\u201ca compliant VPC\u201d, \u201ca hardened EKS cluster\u201d).<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n
Architecturally, many teams settle on layers:<\/p>\n
\n- Layer 0: cloud and providers (root module).<\/li>\n
- Layer 1: platform modules (VPC, KMS, logging, IAM baselines).<\/li>\n
- Layer 2: product\/service modules (service X, API Y) that compose platform modules.<\/li>\n<\/ul>\n
\nCreating a Terraform module<\/h2>\nStandard structure<\/h3>\n
A well\u2011structured module typically has:<\/p>\n
\nmain.tf<\/code> \u2013 core resources and module logic<\/li>\nvariables.tf<\/code> \u2013 input interface<\/li>\noutputs.tf<\/code> \u2013 exported values<\/li>\nversions.tf<\/code> (optional but recommended) \u2013 provider and Terraform version constraints<\/li>\nREADME.md<\/code> \u2013 usage, inputs, outputs, examples<\/li>\n<\/ul>\nThis structure is not required by Terraform but is widely used because it keeps interfaces clear and tooling friendly.<\/p>\n
Simple working example<\/h3>\n
Let\u2019s build a small AWS S3 bucket module and then consume it from a root module.<\/p>\n
Module: modules\/aws_s3_bucket<\/code><\/h4>\nmodules\/aws_s3_bucket\/versions.tf<\/code>:<\/p>\nterraform {\n required_version = ">= 1.6.0"\n\n required_providers {\n aws = {\n source = "hashicorp\/aws"\n version = ">= 5.0"\n }\n }\n}<\/code><\/pre>\nmodules\/aws_s3_bucket\/variables.tf<\/code>:<\/p>\nvariable "bucket_name" {\n type = string\n description = "Name of the S3 bucket."\n}\n\nvariable "environment" {\n type = string\n description = "Environment name (e.g., dev, prod)."\n default = "dev"\n}\n\nvariable "extra_tags" {\n type = map(string)\n description = "Additional tags to apply to the bucket."\n default = {}\n}<\/code><\/pre>\nmodules\/aws_s3_bucket\/main.tf<\/code>:<\/p>\nresource "aws_s3_bucket" "this" {\n bucket = var.bucket_name\n\n tags = merge(\n {\n Name = var.bucket_name\n Environment = var.environment\n },\n var.extra_tags\n )\n}<\/code><\/pre>\nmodules\/aws_s3_bucket\/outputs.tf<\/code>:<\/p>\noutput "bucket_id" {\n description = "The ID (name) of the bucket."\n value = aws_s3_bucket.this.id\n}\n\noutput "bucket_arn" {\n description = "The ARN of the bucket."\n value = aws_s3_bucket.this.arn\n}<\/code><\/pre>\nRationale:<\/p>\n
\nvariables.tf<\/code> defines the module\u2019s public input contract.<\/li>\noutputs.tf<\/code> defines the public output contract.<\/li>\nversions.tf<\/code> protects you from incompatible provider\/Terraform versions.<\/li>\nmain.tf<\/code> stays focused on resources and any derived locals.<\/li>\n<\/ul>\nRoot module consuming it<\/h3>\n
In your root directory (e.g. project root):<\/p>\n
versions.tf<\/code>:<\/p>\nterraform {\n required_version = ">= 1.6.0"\n\n required_providers {\n aws = {\n source = "hashicorp\/aws"\n version = ">= 5.0"\n }\n }\n}<\/code><\/pre>\nproviders.tf<\/code>:<\/p>\nprovider "aws" {\n region = "us-east-1"\n\n # Fake credentials for LocalStack\n access_key = "test"\n secret_key = "test"\n\n skip_credentials_validation = true\n skip_metadata_api_check = true\n skip_requesting_account_id = true\n s3_use_path_style = true\n\n # Point AWS services at LocalStack\n endpoints {\n s3 = "http:\/\/localhost:4566"\n # add more if needed, e.g. dynamodb = "http:\/\/localhost:4566"\n }\n}<\/code><\/pre>\nvariables.tf<\/code>:<\/p>\nvariable "aws_region" {\n type = string\n description = "AWS region to deploy into."\n default = "ap-southeast-2"\n}\n\nvariable "environment" {\n type = string\n description = "Environment name."\n default = "dev"\n}<\/code><\/pre>\nmain.tf<\/code>:<\/p>\nmodule "logs_bucket" {\n source = ".\/modules\/aws_s3_bucket"\n bucket_name = "my-org-logs-${var.environment}"\n environment = var.environment\n extra_tags = {\n owner = "platform-team"\n }\n}\n\noutput "logs_bucket_arn" {\n value = module.logs_bucket.bucket_arn\n description = "Logs bucket ARN."\n}<\/code><\/pre>\nHow to validate this example<\/h3>\n
From the root directory:<\/p>\n
\n- \n
Start LocalStack<\/strong> (for example, via Docker):<\/p>\ndocker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack\/localstack<\/code><\/pre>\nThis exposes the LocalStack APIs on http:\/\/localhost:4566<\/code> as expected by the provider config.<\/p>\n<\/li>\n- \n
terraform init<\/code><\/p>\n<\/li>\n<\/ol>\n\n- Ensures Terraform and the AWS provider are set up; discovers the local module.<\/li>\n<\/ul>\n
\nterraform validate<\/code><\/li>\n<\/ol>\n\n- Confirms syntax, types, required variables satisfied.<\/li>\n<\/ul>\n
\nterraform plan<\/code><\/li>\n<\/ol>\n\n- You should see one S3 bucket to be created, with the name
my-org-logs-dev<\/code> by default.<\/li>\n- Confirm that the tags include
Environment = dev<\/code> and owner = platform-team<\/code>.<\/li>\n<\/ul>\n\nterraform apply<\/code><\/li>\n<\/ol>\n\n- After apply, run
terraform output logs_bucket_arn<\/code> and check that:\n\n- The ARN looks correct for your region.<\/li>\n
- The bucket exists in AWS with expected tags.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
If these checks pass, your module and consumption pattern are wired correctly.<\/p>\n
\nWhen to create a module<\/h2>\n
You should not modularise everything; the trick is to modularise at the right abstraction boundaries.<\/p>\n
Good reasons to create a module<\/h2>\n\n- You\u2019re copy\u2011pasting the same pattern<\/strong> across stacks or repos\n
\n- Example: the same cluster pattern for dev, stage, prod.<\/li>\n
- A module eliminates duplication and concentrates fixes in one place.<\/li>\n<\/ul>\n<\/li>\n
- You have a logical component<\/strong> with a clear responsibility\n
\n- Examples: \u201cnetworking\u201d, \u201cobservability stack\u201d, \u201cGeneric service with ALB + ECS + RDS\u201d.<\/li>\n
- Each becomes a module with focused inputs and outputs.<\/li>\n<\/ul>\n<\/li>\n
- You want to hide complexity and provide sane defaults<\/strong>\n
\n- Consumers shouldn\u2019t need to know every IAM policy detail.<\/li>\n
- Provide a small set of inputs; encode your standards inside the module.<\/li>\n<\/ul>\n<\/li>\n
- You want a contract between teams<\/strong>\n
\n- Platform team maintains modules; product teams just configure inputs.<\/li>\n
- This aligns nicely with how you manage APIs or libraries internally.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
When not to create a module (yet)<\/h2>\n\n- One\u2011off experiments or throwaway code.<\/li>\n
- A single, simple resource that is unlikely to be reused.<\/li>\n
- When you don\u2019t yet understand the pattern \u2014 premature modularisation leads to awkward, unstable interfaces.<\/li>\n<\/ul>\n
A good heuristic: if you\u2019d be comfortable writing a README with \u201cwhat this does, inputs, outputs\u201d and you expect re\u2011use, it\u2019s a good module candidate.<\/p>\n
\nUpdating a module safely<\/h2>\n
Updating modules has two dimensions: changing the module itself, and rolling out the updated version to consumers.<\/p>\n
Evolving the module interface<\/h3>\n
Prefer backwards\u2011compatible<\/strong> changes when possible:<\/p>\n\n- Add new variables with sensible defaults instead of changing existing ones.<\/li>\n
- Add new outputs without altering the meaning of existing outputs.<\/li>\n
- If you must break behaviour, bump a major version and document the migration path.<\/li>\n<\/ul>\n
Internally you might refactor resources, adopt new provider versions, or change naming conventions, but keep the external contract as stable as you can.<\/p>\n
Versioning strategy<\/h3>\n
For modules in a separate repo or registry:<\/p>\n
\n- Use semantic versioning:
MAJOR.MINOR.PATCH<\/code>.\n\n- PATCH: bugfixes, no breaking changes.<\/li>\n
- MINOR: new optional features, backwards compatible.<\/li>\n
- MAJOR: breaking changes.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
Tag releases (v1.2.3<\/code>) and use those tags in consumers (Git or registry).<\/p>\nRolling out updates to consumers<\/h3>\n
For a Git\u2011sourced module:<\/p>\n
module "logs_bucket" {\n source = "git::https:\/\/github.com\/my-org\/terraform-aws-s3-bucket.git?ref=v1.3.0"\n # ...\n}<\/code><\/pre>\nTo upgrade:<\/p>\n
\n- Change
ref<\/code> from v1.2.0<\/code> to v1.3.0<\/code>.<\/li>\n- Run
terraform init -upgrade<\/code>.<\/li>\n- Run
terraform plan<\/code> and review changes carefully.<\/li>\n- Apply in lower environments first, then promote the same version to higher environments (via branch promotion, pipelines, or workspace variables).<\/li>\n<\/ol>\n
For a registry module, the pattern is the same but with a version<\/code> argument:<\/p>\nmodule "vpc" {\n source = "terraform-aws-modules\/vpc\/aws"\n version = "~> 5.3.0"\n}<\/code><\/pre>\nPinning versions gives you reproducibility and avoids surprise changes across environments.<\/p>\n
\nPublishing a module<\/h2>\n
Publishing is about making your module discoverable and consumable by others, with strong versioning and documentation.<\/p>\n
Public registry (high\u2011level)<\/h3>\n
To publish a module publicly (e.g. to the Terraform Registry):<\/p>\n
\n- Place the module in a public VCS repo (commonly GitHub).<\/li>\n
- Name the repo using the convention:
terraform-<PROVIDER>-<NAME><\/code>\n\n- Example:
terraform-aws-s3-bucket<\/code>.<\/li>\n<\/ul>\n<\/li>\n- Ensure the repo root contains your module (
main.tf<\/code>, variables.tf<\/code>, outputs.tf<\/code>, etc.).<\/li>\n- Tag a version (e.g.
v1.0.0<\/code>).<\/li>\n- Register the module on the registry UI (linking your VCS account).<\/li>\n<\/ul>\n
Once indexed, users can consume it as:<\/p>\n
module "logs_bucket" {\n source = "my-org\/s3-bucket\/aws"\n version = "1.0.0"\n\n bucket_name = "my-org-logs-prod"\n environment = "prod"\n}<\/code><\/pre>\nPrivate registries and Git<\/h3>\n
For internal usage, many organizations prefer:<\/p>\n
\n- Private registry<\/strong> (Terraform Cloud\/Enterprise, vendor platform, or self\u2011hosted).\n
\n- Similar flow to the public registry, but scoped to your org.<\/li>\n<\/ul>\n<\/li>\n
- Direct Git usage<\/strong>\n
\n- Modules are consumed from Git with
?ref=<\/code> pointing to tags or commits.<\/li>\n- Simpler setup, but you lose some of the browsing and discoverability that registries provide.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
The key idea is the same: modules are versioned artefacts, and consumers should pin versions<\/strong> and upgrade intentionally.<\/p>\n
\nConsuming modules (putting it all together)<\/h2>\n
To consume any module, you:<\/p>\n
\n- Add a
module<\/code> block.<\/li>\n- Set
source<\/code> to a local path, Git URL, or registry identifier.<\/li>\n- Pass the required inputs as arguments.<\/li>\n
- Use the module\u2019s outputs via
module.<name>.<output_name><\/code>.<\/li>\n<\/ol>\nExample: consuming a local network module and a registry VPC module side by side.<\/p>\n
# Local module (your own)\nmodule "network" {\n source = ".\/modules\/network"\n\n vpc_cidr = "10.0.0.0\/16"\n public_subnets = ["10.0.1.0\/24", "10.0.2.0\/24"]\n private_subnets = ["10.0.11.0\/24", "10.0.12.0\/24"]\n}\n\n# Registry module (third-party)\nmodule "logs_bucket" {\n source = "terraform-aws-modules\/s3-bucket\/aws"\n version = "~> 4.0"\n\n bucket = "my-org-logs-prod"\n\n tags = {\n Environment = "prod"\n }\n}\n\noutput "network_vpc_id" {\n value = module.network.vpc_id\n}\n\noutput "logs_bucket_arn" {\n value = module.logs_bucket.s3_bucket_arn\n}<\/code><\/pre>\nThe root module becomes a composition layer, wiring together multiple modules rather than directly declaring many low\u2011level resources.<\/p>\n
\nSummary of key practices<\/h2>\n\n- Treat modules as APIs<\/strong>: clear inputs, clear outputs, stable contracts.<\/li>\n
- Use a predictable structure:
main.tf<\/code>, variables.tf<\/code>, outputs.tf<\/code>, versions.tf<\/code>, README.md<\/code>.<\/li>\n- Only create modules where there is clear reuse or a meaningful abstraction.<\/li>\n
- Version modules and pin those versions when consuming them.<\/li>\n
- Use lower environments and
terraform plan<\/code> to validate updates before promoting.<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"Terraform modules are how you turn raw Terraform into a reusable, versioned \u201clibrary\u201d of infrastructure components. In this article we\u2019ll go through what modules are, the types you\u2019ll see in practice, how to create them, when to factor code into a module, how to update them safely, how to publish them, and finally how to […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[94],"tags":[],"_links":{"self":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2147"}],"collection":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2147"}],"version-history":[{"count":1,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2147\/revisions"}],"predecessor-version":[{"id":2148,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2147\/revisions\/2148"}],"wp:attachment":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2147"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2147"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2147"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}