Using Terraform Registry

1. Finding Provider Documentation

Provider	Documentation URL	Version	Notes
aws	https://registry.terraform.io/providers/hashicorp/aws/latest/docs	`5.0+`	Official AWS provider documentation
azure	https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs	`3.0+`	Official Azure provider documentation
google	https://registry.terraform.io/providers/hashicorp/google/latest/docs	`4.0+`	Official Google Cloud provider documentation
kubernetes	https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs	`2.0+`	Official Kubernetes provider documentation

Example: Using provider documentation in a module

module "aws_s3" {
  source  = "terraform-aws-modules/s3-bucket/aws"
  version = "4.0.0"

  bucket = "my-terraform-bucket"
}

Note: Always check the provider version compatibility before using documentation examples.

Warning: Provider documentation may change between versions. Ensure you're referencing the correct version.

2. Finding Module Documentation

Documentation Source	Description	Access Method
Terraform Registry	Official module documentation hosted by HashiCorp	Visit `registry.terraform.io`
Module README	Primary documentation within the module's source repository	Check `README.md` in the module’s GitHub/GitLab repo
Module Examples	Sample configurations demonstrating usage patterns	Found under `/examples` directory in the module repo
Module Variables	List of input variables with descriptions and defaults	Available in the `variables.tf` file or registry page
Module Outputs	Output values provided by the module	Found in `outputs.tf` or registry page
Module Dependencies	Required providers and other modules	Viewed in `providers.tf` or registry page

Example: Module Documentation URL Format


https://registry.terraform.io/modules/<ORGANIZATION>/<MODULE_NAME>/<PROVIDER>/<VERSION>

Note: Documentation includes version-specific details and may differ between versions.

Warning: Ensure you're viewing documentation for the correct provider version.

3. Publishing Public Modules

To publish a Terraform module to the public registry, you must first ensure it meets the requirements for publishing.

Requirement	Description	Status
Module Structure	Module must follow the standard Terraform module structure with main configuration files (e.g., `main.tf`, `variables.tf`, `outputs.tf`)	Required
Versioning	Module must use semantic versioning (e.g., `v1.0.0`) for releases	Required
Documentation	Module must include a `README.md` with usage instructions and examples	Required
License	Module must include a valid open-source license (e.g., MIT, Apache-2.0)	Required
Changelog	Module must include a `CHANGELOG.md` documenting changes between versions	Recommended

Example: Publishing a Module

terraform init
terraform plan -out=tfplan
terraform apply tfplan

Note: Modules must be published under an organization or user namespace in the Terraform Registry.

Warning: Once a module version is published, it cannot be modified or deleted.

Steps to Publish a Module

Create a new repository for your module on GitHub or another Git provider
Ensure the repository follows Terraform module conventions
Tag a new release with a semantic version (e.g., v1.0.0)
Go to the Terraform Registry and create a new module entry under your namespace
Link the repository to the registry and configure the module settings
Verify that the module is correctly indexed and published

4. Versioning Published Modules

Version Format	Description	Notes
semantic versioning	`v1.2.3`	Must follow SemVer format
pre-release tags	`v1.2.3-rc.1`	Allowed for release candidates and betas
build metadata	`v1.2.3+build.1`	Ignored for version comparison

Example: Module Version Constraint

module "aws_instance" {
  source  = "terraform-aws-modules/ec2-instance/aws"
  version = ">= 2.0.0, < 3.0.0"
}

Note: Terraform Registry enforces strict semantic versioning. Modules must be tagged with valid SemVer versions to be published.

Version Constraint	Meaning	Example
exact version	Must match exactly	`= 2.0.0`
compatible range	Same major version, any minor/patch	`>= 2.0.0, < 3.0.0`
latest patch	Same major and minor, latest patch	`= 2.1.0`
greater than or equal	Any version greater than or equal to specified	`>= 2.0.0`
less than or equal	Any version less than or equal to specified	`<= 2.1.0`
wildcard	Any version matching pattern	`= 2.1.*`

Example: Using Wildcard Version

module "aws_s3_bucket" {
  source  = "terraform-aws-modules/s3-bucket/aws"
  version = "= 3.1.*"
}

Warning: Using wildcard versions can lead to unexpected behavior if a new patch version introduces breaking changes. Always pin to specific versions in production.

5. Using Module Examples

Example: Using a Public Module

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = "3.10.0"

  name = "my-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.10.0/24", "10.0.11.0/24", "10.0.12.0/24"]
}

Example: Using a Module with Variables

module "web_server" {
  source = "./modules/web-server"

  instance_type = "t3.micro"
  ami_id        = "ami-0c55b159cbfafe1d0"
  count         = 2
}

Property	Description	Required	Default
source	Location of the module (registry, git, local path)	Yes	-
version	Version of the module to use (optional)	No	-
count	Number of instances to create	No	1

Note: When using modules from the Terraform Registry, ensure that the version is pinned to avoid unexpected changes.

6. Searching Registry

Field	Description	Example
search term	Keyword or phrase to search for in the registry	`aws`
category	Filter by category (e.g., cloud, database)	`cloud`
provider	Filter by provider (e.g., aws, google)	`aws`
version	Filter by version constraint (e.g., >= 1.0.0)	`>= 1.0.0`

Example: Search for AWS modules

terraform search aws

Example: Search with version filter

terraform search 'aws s3' --version ">= 1.0.0"

Note: The terraform search command is available in Terraform v1.0 and later.

7. Viewing Module Sources

Source Type	Description	Example	Notes
registry.terraform.io	Official Terraform Registry for modules and providers	`module "aws_instance" { source = "registry.terraform.io/terraform-aws-modules/vpc/aws" }`	Default registry for Terraform modules
github.com	GitHub repositories hosting Terraform modules	`module "example" { source = "github.com/organization/module" }`	Requires full path to module directory
git::https://	Git repositories over HTTPS	`module "example" { source = "git::https://github.com/organization/module.git" }`	Supports branch, tag, or commit
http::	HTTP/HTTPS URLs to module files	`module "example" { source = "http::https://example.com/module.tf" }`	Module must be a single file
local	Local directory paths	`module "example" { source = "./local-module" }`	Useful for development and testing

Example: Viewing Module Source in Registry

terraform search registry.terraform.io

Note: The Terraform Registry provides a searchable catalog of modules and providers. You can view module sources directly in the registry UI or via CLI commands.

8. Using Verified Modules

Verified modules are Terraform modules that have been reviewed and approved by the Terraform Registry team for quality, security, and best practices.

Field	Description	Example
source	The module source path in the registry	`registry.terraform.io/hashicorp/aws`
version	Version constraint for the module	`>= 4.0.0`

Example: Using a Verified Module

module "vpc" {
  source  = "registry.terraform.io/hashicorp/aws"
  version = ">= 4.0.0"

  vpc_cidr = "10.0.0.0/16"
  subnet_cidr = "10.0.1.0/24"
}

Note: Verified modules are marked with a VERIFIED badge in the Terraform Registry.

Warning: Ensure that the module version is compatible with your Terraform version.

9. Reviewing Module Downloads

Field	Description	Example
source	Module source identifier	`terraform-aws-modules/vpc/aws`
version	Module version constraint	`>= 3.0.0`
name	Module name (optional)	`vpc-module`

Example: Module Source Configuration

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = ">= 3.0.0"
}

Note: Terraform Registry modules are downloaded to .terraform/modules directory.

Module Download Process

Terraform resolves module source and version constraints
Downloads module to local cache
Extracts module files into .terraform/modules
Applies configuration from downloaded module

10. Contributing to Modules

Step	Description	Action
1	Set up local development environment	Clone the module repository and install required tools (e.g., Terraform, linters)
2	Create or update documentation	Update README.md and other docs with usage examples and parameter descriptions
3	Write tests	Add unit and integration tests using Terraform's test framework or external tools like Terratest
4	Validate module structure	Ensure the module follows best practices (e.g., inputs, outputs, modules)
5	Submit pull request	Push changes to a feature branch and open a PR against the upstream repository

Example: Module structure


module/
  main.tf
  variables.tf
  outputs.tf
  README.md
  examples/
    basic/
      main.tf

Note: Ensure all modules are compatible with the latest stable version of Terraform.

Key Guidelines

Follow the module structure conventions
Include comprehensive documentation
Test all changes before submitting
Adhere to semantic versioning (SemVer)