1.2.8.1. Design and Practice of the examples/ Folder

In Terraform module development, the examples/ folder plays a crucial role. It not only helps users understand the real-world application scenarios of the module but also provides runnable configuration examples, thereby lowering the learning curve. This chapter will delve into the purpose, structural design, documentation, and best practices for team collaboration regarding the examples/ folder.

1.2.8.1.1. The Role of the examples/ Folder

The examples/ folder is primarily used to store usage examples of the module, helping users to:

• Understand real-world application scenarios of the module.
• Quickly get started with and test the module's functionality.
• Reference best practice configurations to avoid common errors.

Each example should be self-contained; it must include the necessary Terraform configuration files and documentation to ensure that users can directly run terraform apply and understand the example's purpose (this means that all prerequisite resources required to demonstrate the module's functionality must be created within the example code).

Examples should embody best practices as much as possible, or at the very least, should not employ known anti-patterns, such as using hard-coded weak passwords or creating databases without backup policies.

1.2.8.1.2. Designing the Example Structure

To improve readability and maintainability, it is recommended to organize the examples/ folder with a structure similar to the following:

examples/
├── default/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── README.md
├── advanced/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── README.md
└── ...

Each subdirectory represents an independent usage scenario (e.g., with Private Endpoint, using a private container registry with configured credentials, etc.) and contains complete Terraform configuration files along with corresponding documentation. This not only facilitates user reference and testing but also aids in the continuous maintenance and updates of the module.

1.2.8.1.3. Guidelines for Writing Example Documentation

The README.md file in each example subdirectory should include the following contents:

• Example Overview: A brief description of the purpose and application scenario of the example.
• Usage: Steps to run the example, including necessary prerequisites and commands.
• Configuration: Explanations of the main input variables and outputs to help users understand the meaning of the configuration.
• Notes: Alerts regarding issues users need to be aware of when using the example, such as resource dependencies or permission requirements.

Just like the module documentation, example documentation should also be generated using terraform-docs.

1.2.8.1.4. Automated Testing of Examples

To ensure the validity and usability of the examples, it is recommended to incorporate automated testing of examples into the Continuous Integration (CI) process. Tools such as Terratest or Kitchen-Terraform can be used to implement automated tests, verifying the correctness and stability of the examples.

To enable users to quickly experience the module's functionality, we strongly recommend that all examples be designed to require no user input. Once the necessary credentials (e.g., Azure credential information) are configured, deployment should be possible directly via the terraform apply command. We must configure corresponding automated tests to promptly detect and fix issues within the examples, maintaining consistency between the examples and the module code, thus elevating the overall quality of the module.

We will discuss testing-related topics in detail in subsequent chapters.