home / skills / first-fluke / fullstack-starter / terraform-module-library

terraform-module-library skill

/.agents/skills/terraform-module-library

This skill helps you design, standardize, and reuse Terraform modules with best practices for structuring, naming, and documentation.

npx playbooks add skill first-fluke/fullstack-starter --skill terraform-module-library

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: terraform-module-library
description: Expert guidance for creating, managing, and using Terraform modules. Use this skill when the user wants to create reusable infrastructure components, standardize Terraform patterns, or needs help with module structure and best practices for AWS, GCP, or Azure.
---

# Terraform Module Library

This skill provides standardized patterns and best practices for creating and using Terraform modules.

## When to Use

- Creating new reusable Terraform modules
- Refactoring existing Terraform code into modules
- Standardizing infrastructure patterns across the project
- implement specific infrastructure components (VPC, GKE, RDS, etc.) using best practices

## Module Structure

Standard directory structure for a Terraform module:

```
module-name/
├── main.tf       # Primary logic and resources
├── variables.tf  # Input variable definitions
├── outputs.tf    # Output value definitions
├── versions.tf   # Provider and Terraform version constraints
├── README.md     # Module documentation
└── examples/     # Example configurations
    └── complete/ # Full example usage
```

## Best Practices

### Cloud Providers

#### Google Cloud Platform (GCP)
- Use `google-beta` provider for beta features if necessary, but prefer GA.
- Follow Google's "Cloud Foundation Toolkit" patterns where applicable.
- Resource naming: Use standardized prefixes/suffixes (e.g., `gcp-vpc-{env}`).

#### AWS
- Use standard `aws` provider resources.
- Tag all resources with consistent tags (Owner, Environment, Project).

### General
- **Version Pinning**: Always pin provider and Terraform versions in `versions.tf`.
- **Variables**: Include `description` and `type` for all variables. Use `validation` blocks for constraints.
- **Outputs**: Document all outputs.
- **State**: Do not include backend configuration in modules; state is managed by the root configuration.

## Common Module Patterns

### Private Module Registry
If using a private registry, ensure source paths follow the registry's convention.

### Local Modules
For local development or monorepos:
```hcl
module "network" {
  source = "./modules/network"
  # ...
}
```

## Review Checklist

1. [ ] Does the module have a `README.md` with input/output documentation?
2. [ ] Are all variables typed and described?
3. [ ] Are resource names deterministic or correctly scoped?
4. [ ] Does it include `examples/`?
5. [ ] Is `terraform_remote_state` avoided within the module?

Overview

This skill provides expert guidance for creating, managing, and using Terraform modules to build reusable infrastructure components across AWS, GCP, and Azure. It focuses on module structure, versioning, variable/output conventions, and practical patterns for monorepos and private registries. Use it to standardize Terraform patterns and accelerate safe, maintainable infrastructure code.

How this skill works

The skill inspects module layout, variable and output definitions, version constraints, and example usage to ensure consistency and reusability. It highlights provider-specific recommendations (AWS, GCP, Azure), enforces version pinning, and checks for anti-patterns such as embedding backend/state logic or using terraform_remote_state inside modules. It also provides a review checklist and concrete examples for local and registry-based module consumption.

When to use it

Creating a new reusable Terraform module for any cloud provider
Refactoring standalone Terraform code into a standardized module
Enforcing module conventions across a monorepo or team
Implementing common infrastructure components (VPC, GKE/AKS/EKS, RDS/Cloud SQL)
Preparing modules for private registry publishing

Best practices

Keep a predictable module directory with main, variables, outputs, and examples for usage
Pin Terraform and provider versions in a versions file to avoid drift
Declare variable type, description, and validation blocks for clearer contracts
Document all outputs and give them stable, descriptive names
Avoid backend configuration and remote state links inside modules; manage state at the root
Tag or label cloud resources consistently (Owner, Environment, Project)

Example use cases

Create a reusable network module with standardized naming and subnets for dev/prod
Refactor a project’s database setup into a module exposing endpoints and credentials safely
Provide an examples/complete configuration for local testing within a monorepo
Publish a module to a private registry with source paths and versioning
Adopt provider-specific patterns like GCP resource naming and AWS tagging in shared modules

FAQ

Should modules manage remote state or backend configuration?

No. Backends and remote state belong to root configurations or environments. Modules should be stateless building blocks to remain composable and reusable.

How should I enforce provider versions across modules?

Pin provider and Terraform versions in a central versions file for each module, and use a shared root-level constraint to keep teams aligned. Use automation to detect mismatches.