Skip to content
Documentation

QA Module Structure

When QA validates a module, it is crucial to follow a consistent structure to ensure that the module adheres to best practices and is easy to understand. Below is the structure to be followed when creating a Terraform AWS module.

  • Directory.github/
    • DirectoryISSUE_TEMPLATE/
      • 1_bug_report.yml
      • 2_feature_request.yml
      • 3_docs_request.yml
      • config.yml
    • Directoryworkflows/
      • documentation.yml
      • pr-title.yml
      • pre-commit.yml
      • release.yml
    • dependabot.yml
    • PULL_REQUEST_TEMPLATE.md
    • stale.yml
  • Directory.vscode/
    • extensions.json
    • settings.json
  • DirectoryLOGS/
    • .gitkeep
  • Directorysrc/
    • Directorymodule-example-1/
      • Directoryexamples/
        • Directorycomplete/
          • main.tf
          • outputs.tf
          • README.md
          • provider.tf
          • versions.tf
        • .gitkeep
      • Directorymodel/
        • main.tf
        • outputs.tf
        • README.md
        • variables.tf
        • versions.tf
      • main.tf
      • outputs.tf
      • README.md
      • variables.tf
      • versions.tf
    • .gitkeep
  • .editorconfig
  • .gitignore
  • .pre-commit-config.yaml
  • .releaserc.json
  • README.md

Structure Explanation

  1. .github/: Contains GitHub Actions workflows and issue templates. The documentation.yml workflow generates documentation for the module. Ensure that all directories are included in the documentation generation by checking the working-dir directory.

    .github/workflows/documentation.yml
    15 collapsed lines
    1
    name: Generate Terraform Docs
    2
    on:
    3
      - pull_request
    4
    

    5
    jobs:
    6
      docs:
    7
        runs-on: ubuntu-latest
    8
        steps:
    9
          - uses: actions/checkout@v4
    10
            with:
    11
              ref: ${{ github.event.pull_request.head.ref }}
    12
    

    13
          - name: Render Terraform docs in README.md and push changes back to PR branch
    14
            uses: terraform-docs/gh-actions@v1.1.0
    15
            with:
    16
              working-dir: ./src/module-example-1,./src/module-example-1/model,./src/module-example-1/wrapper,./src/module-example-1/examples/complete
    3 collapsed lines
    17
              output-file: README.md
    18
              output-method: inject
    19
              git-push: "true"

  2. src/: Contains the module code. Each module should have its own directory named after the module. The module directory should contain the following files:

    • /module-example-1/: Rename this directory to the module name.
      • examples/complete/: Contains an example of how to use the module, including all resources that the module creates.

        • main.tf: Main Terraform configuration file with the module’s resources.

        • outputs.tf: Outputs of the module.

        • README.md: Documentation for the example.

          ./src/module-example-1/examples/complete/README.md
          1
          # Terraform AWS Modules Example/Complete Blueprint
          2
          

          3
          ## Description
          4
          

          5
          <!-- INFO: A brief description of the example -->
          6
          

          7
          ## How to Use
          8
          

          9
          <!-- INFO: Steps to run the complete example successfully -->
          10
          

          11
          ## Notes
          12
          

          13
          > [!NOTE]
          14
          > Important information for users.
          15
          

          16
          > [!TIP]
          17
          > Tips for successful usage.
          18
          

          19
          > [!IMPORTANT]
          20
          > Crucial information for users.
          21
          

          22
          > [!WARNING]
          23
          > Critical information for immediate attention.
          24
          

          25
          > [!CAUTION]
          26
          > Potential negative consequences.
          27
          

          28
          <!-- BEGIN_TF_DOCS -->
          26 collapsed lines
          29
          ## Requirements
          30
          

          31
          | Name | Version |
          32
          |------|---------|
          33
          | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.5.0 |
          34
          | <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 5.24.0 |
          35
          

          36
          ## Providers
          37
          

          38
          No providers.
          39
          

          40
          ## Modules
          41
          

          42
          No modules.
          43
          

          44
          ## Resources
          45
          

          46
          No resources.
          47
          

          48
          ## Inputs
          49
          

          50
          No inputs.
          51
          

          52
          ## Outputs
          53
          

          54
          No outputs.
          55
          <!-- END_TF_DOCS -->

        • provider.tf: Provider configuration.

          ./src/module-example-1/examples/complete/provider.tf
          1
          provider "aws" {
          2
            region                   = "eu-west-1"
          3
            shared_credentials_files = [pathexpand("~/.aws/credentials")]
          4
            profile                  = "TF_TEST_PROFILE"
          5
          }

        • versions.tf: Terraform provider versions.

          ./src/module-example-1/examples/complete/versions.tf
          1
          terraform {
          2
            required_providers {
          3
              aws = {
          4
                source  = "hashicorp/aws"
          5
                version = ">= 5.24.0"
          6
              }
          7
            }
          8
          }
      • model/: Contains the module code.
        • main.tf: Main Terraform configuration file with the module’s resources.
        • outputs.tf: Outputs of the module.
        • README.md: Documentation for the module, generated by the documentation.yml workflow.
        • variables.tf: Input variables for the module.
        • versions.tf: Terraform provider versions.
      • main.tf: Will be deleted and replaced with specific resources like codeartifact_repository.tf, codeartifact_domain.tf, etc.
      • outputs.tf: Contains all outputs of the module.
      • variables.tf: Contains all input variables of the module.
      • README.md: Documentation for the module, generated by the documentation.yml workflow.

  3. README.md: Main documentation for the module. This file should contain the following sections:

    README.md
    1
    # Terraform AWS Modules Blueprint
    2
    

    3
    ## Description
    4
    

    5
    <!-- INFO: A brief description of the blueprint -->
    6
    

    7
    This repository serves as a blueprint for creating new Terraform modules tailored for AWS. It is designed to provide a structured and consistent foundation for developing modular infrastructure stacks.
    8
    

    9
    ## Modules List
    10
    

    11
    <!-- INFO: A list of available modules -->
    12
    

    13
    - **`module-example-1`:**
    14
      - [Module Example 1](src/module-example-1/)
    15
      - [Module Example 1 Model](src/module-example-1/model)
    16
      - [Module Example 1 Wrapper](src/module-example-1/wrapper)
    17
    

    18
    ## Examples
    19
    

    20
    ### Examples List
    21
    

    22
    <!-- INFO: A list of available examples -->
    23
    

    24
    - **`module-example-1`:**
    25
      - [Module Example 1 Complete](src/module-example-1/examples/complete/)
    26
    

    27
    ## Documentation
    28
    

    29
    <!-- INFO: Additional information about the blueprint -->
    30
    

    31
    Explore detailed documentation to enhance your understanding:
    32
    

    33
    - [Documentation](https://www.tf-docs.cirrusgo.com/docs/)
    34
    

    35
    ## Terraform Registry Version
    36
    

    37
    <!-- INFO: The Terraform Registry version of the blueprint -->
    38
    

    39
    - [Terraform Registry](https://registry.terraform.io/providers/hashicorp/aws/5.49.0/docs)
    • Title: Rename the title Terraform AWS Modules Blueprint to the module name.
    • Description: Add a brief description of the module.
    • Modules List: List all available modules in the repository.
    • Examples List: List all available examples in the repository.
    • Documentation: Add any additional information about the module.
    • Terraform Registry Version: Add the Terraform Registry version of the module.

Conclusion

By following this structure, you can ensure that the module is consistent, easy to understand, and follows best practices. This will help QA validate the module more efficiently and effectively.