ADR-0003

Terraform public modules vs custom modules

Status	Date (Last modified)	Deciders
Accepted 👍🏼	07/22/2023	Brett Curtis

If superseded by another ADR, include the link here:

Technical Issue(s):

• https://github.com/osinfra-io/terraform-google-project/issues/1

Context and Problem Statement

A Terraform module is a great resource for describing the architecture and keeping infrastructure as code DRY. Open-source modules are published to registry.terraform.io. Should we consume Terraform public modules or develop custom modules?

Decision Drivers

• Developers at all skill levels should be able to contribute and maintain over time.

• The interfaces provided to the consumer should be simple and focused.

• Security and other policies should align with organizational requirements.

• Good balance between DRY and Keep it simple, stupid (KISS).

• Align with Hashicorp documentation.

• Single testing framework.

Considered Options

Use Terraform public modules.

Development of custom Terraform modules.

Combination of both.

Decision Outcome

Option 2: Development of custom Terraform modules to fit the needs of the organization and the skills of the employees

Pros and Cons of the Options

Use Terraform public modules

Positive Consequences

• If the module meets all our requirements right now, we do not have to write or maintain any code.

• We can adhere to the DRY principle.

• Initially, they will speed up delivery.

Negative Consequences

• If the public module does not meet our requirements now or in the future, we will need to fork and maintain the module or have developers who are comfortable submitting PRs publicly.

• The user base is too large, and the KISS design principle has been lost.

• The rate of change across such a large user base is likely to be higher than most organizations tolerate.

• Testing public modules locally and understanding the backend requirements can be confusing.

• Testing frameworks vary across modules.

Development of custom Terraform modules

Positive Consequences

• We can balance DRY and KISS.

• New developers are more comfortable submitting PRs and learning git within the organization's context.

• We have control over the interfaces.

• We can align with organizational security policies.

Negative Consequences

• This will slow down the initial time to delivery.

Combination of both

Positive Consequences

• Initially, public modules will speed up delivery.

Negative Consequences

• Another decision process would need to be developed around when to use each.

Links

The Terraform documentation seems a bit outdated in reference to when to write a module. For example, "If you have trouble finding a name for your module that isn't the same as the main resource type inside it, that may be a sign that your module is not creating any new abstraction, so the module is adding unnecessary complexity." This is not what you see in their module registry, and it is very common to see a module with the same name as the main resource type. Even tho the words "may be" are used we feel this gives an incorrect initial first impression and should focus more on the drivers for when to write a module. See ADR-0004 for more information.

Creating Modules | Terraform | HashiCorp DeveloperCreating Modules | Terraform | HashiCorp Developer