Brief description of what your Terraform module does and its primary use case.
This module provides [key functionality] for [target infrastructure/use case]. Built with production-ready practices including comprehensive testing, documentation generation, and portable CI/CD pipelines.
Tip
Quick Start: Replace the placeholders in this README with your module's specific details. The development workflow and tooling are pre-configured and ready to use. It is essential to provide a clear and comprehensive description of your module. A well-written description helps users understand the purpose and functionality of your module. For more information on how to write effective module descriptions, please refer to the Terraform Registry documentation.
Tip
When describing the features of your module, focus on clarity and brevity. Highlight the key functionalities and benefits without unnecessary jargon. This helps users quickly grasp what your module offers and how it can be beneficial for their projects.
This module provides:
- 🚀 [Feature 1]: Description of key capability
- 🚀 [Feature 2]: Description of key capability
- 🚀 [Feature 3]: Description of key capability
- 🔧 Production Ready: Built-in testing, documentation, and CI/CD
- 📦 Registry Compatible: Follows Terraform Registry best practices
For examples, see the examples/ directory.
Tip
Module Organization: All Terraform modules are organized in the modules/ directory following our Module Guidelines. Each module is self-contained with comprehensive documentation, examples, and tests.
| Module | Description | Use Case |
|---|---|---|
| default | Template module for creating new infrastructure components | Starting point for new modules, demonstrates best practices |
| random-string-generator | Generates random strings with configurable length and character sets | Unique identifiers, suffixes, and random values |
| read-aws-metadata | Retrieves AWS account metadata (Account ID, Region, Partition) | Environment discovery, dynamic resource naming |
Note: When creating new modules, follow the structure and patterns established in these examples. See our Module Development Guidelines for detailed specifications.
This template includes powerful development tooling with Dagger for portable CI/CD and Just for command orchestration.
Option 1: Install tools individually
# Essential tools
brew install just dagger terraform
# Optional but recommended
brew install pre-commit terraform-docs tflintOption 2: Use Nix for reproducible environment
# Install Nix (if not already installed)
curl -L https://nixos.org/nix/install | sh
# Enter development shell with all tools
nix develop
# Or use with direnv for automatic activation
echo "use flake" > .envrc
direnv allow-
Initialize your environment:
just init
-
Develop your module:
# Edit files in modules/default/ # Add examples in examples/default/basic/ # Write tests in tests/modules/default/
-
Validate as you build:
# Run the same pipeline as CI locally just pipeline-infra-tf-ci default # Or run individual checks just tf-validate default just pipeline-action-terraform-static-analysis default just pipeline-action-terraform-build default
🔍 Core Development:
just init # Initialize development environment
just tf-validate MODULE # Validate Terraform code
just tf-fmt MODULE # Format Terraform code
just tf-docs MODULE # Generate documentation🧪 Testing:
just tf-test-unit MODULE # Run unit tests
just tf-test-examples MODULE # Run example tests
just pipeline-infra-tf-ci MODULE # Full CI pipeline locally🚀 Pipeline Operations:
just pipeline-infra-build # Build Dagger pipeline
just pipeline-infra-shell # Interactive debugging
just pipeline-action-terraform-static-analysis MODULETip
Run just to see all available commands. For detailed documentation, see our Pipeline Guide and Justfile Recipes Guide.
Multi-layered testing approach:
- Static Analysis: Terraform validation, formatting, and linting
- Unit Tests: Module configuration and output validation
- Integration Tests: End-to-end deployment with real resources
- Example Tests: All examples are automatically tested
# Run all tests locally (same as CI)
just pipeline-infra-tf-ci default
# Run specific test types
just tf-test-unit default
just tf-test-examples defaultTesting is implemented using Terratest for reliable infrastructure validation.
Portable pipeline that runs identically everywhere:
- Local Development:
just pipeline-infra-tf-ci MODULE - GitHub Actions: Automated on PRs and releases
- Interactive Debugging:
just pipeline-infra-shell
The Dagger pipeline provides:
- Cross-version Terraform compatibility testing
- AWS integration with multiple auth methods
- Comprehensive static analysis and security scanning
- Parallel execution with intelligent caching
Environment support:
.envfiles (automatically loaded by Just)- Environment variables
- AWS profiles and OIDC
- Terraform workspaces
# Example .env file
TF_VAR_environment=development
TF_VAR_region=us-west-2
AWS_PROFILE=my-dev-profileSee our Environment Variables Guide for complete configuration options.
We welcome contributions to improve this module!
Development Standards:
- Fork and clone this repository
- Use the development environment: Either install tools individually or use our Nix flake with
nix develop - Follow our standards: Terraform StyleGuides
- Test your changes:
just pipeline-infra-tf-ci default - Submit a PR: We'll review promptly!
Code Quality Requirements:
- All code must pass the complete CI pipeline
- New features require tests and documentation
- Follow our coding standards and best practices
- Use conventional commits for automated changelog generation
- Environment Variables Guide: Complete environment configuration
- Justfile Recipes Guide: All available commands
- Pipeline Guide: Comprehensive CI/CD documentation
- Module Guidelines: Module design principles
- Code Guidelines: Terraform coding standards
- Testing Guidelines: Testing patterns and practices
- Examples: Usage examples and patterns
- Testing Overview: Testing strategies
- Development Utilities: Helper scripts
This project is licensed under the MIT License - see the LICENSE file for details.
Built with Terraform Registry Module Template
Production-ready tooling • Portable CI/CD • Comprehensive testing