Terraform Modules - Define, Enforce, Report

Terraform modules are reusable packages of Terraform code that group a set of resources meant to be deployed together. Writing one and calling it is straightforward. Doing it in a way that holds up across a whole organization is the harder part. There are three phases to module usage:

• Defining
• Enforcing
• Reporting

First, you need to define what modules can be used by your organization. Defining a module involves writing Terraform configuration files that specify the resources to be created and their configuration parameters. Your organization might decide to copy code directly from the public Terraform registry, use some pieces of the public modules, or start a module from scratch. There is no right or wrong way when it comes to this, but you do want to define the modules in a module registry. A module registry will help your end users know which modules have been approved and how to use them, which reduces the amount of snowflake modules you have within your organization. All TACOs support module registries.

Next, you'll want to enforce the modules. Just because you have a module registry doesn't necessarily mean that your users will use those modules. Enforcement can be done through Open Policy Agent and Scalr. The main policy that comes to mind is to enforce the source of the module. In the example below you'll see that if an AWS DB or S3 resource is created, it must use the module that is defined in the policy:

#This policy will forbid resources from getting created unless done so through a module and a specific source.
package terraform
 
import input.tfplan as tfplan
 
# Map of resource types which must be created only using module with corresponding module source
resource_modules = {
    "aws_db_instance": "terraform-aws-modules/rds/aws",
    "aws_s3_bucket": "scalr-demo.scalr.io/acc-sscctbisjkl35b8/s3-bucket/aws"
}
 
contains(arr, elem) {
  arr[_] = elem
}
 
deny[reason] {
    resource := tfplan.resource_changes[_]
    action := resource.change.actions[count(resource.change.actions) - 1]
    contains(["create", "update"], action)
    module_source = resource_modules[resource.type]
    not resource.module_address
    reason := sprintf(
        "%s cannot be created directly. Module '%s' must be used instead",
        [resource.address, module_source]
    )
}
 
deny[reason] {
    resource := tfplan.resource_changes[_]
    action := resource.change.actions[count(resource.change.actions) - 1]
    contains(["create", "update"], action)
    module_source = resource_modules[resource.type]
    parts = split(resource.module_address, ".")
    module_name := parts[1]
    actual_source := tfplan.configuration.root_module.module_calls[module_name].source
    not actual_source == module_source
    reason := sprintf(
        "%s must be created with '%s' module, but '%s' is used",
        [resource.address, module_source, actual_source]
    )
}

Lastly, you'll want to report on module usage. Reporting will catch anything that the defining and enforcing phases were not able to catch:

• Understanding which modules are used the most and which ones can be deprecated.
• Ensure compliance by knowing if users are working around your controls in some way.
• Knowing if workspaces are on older versions and getting them upgraded.

Reporting ties the other two phases together and tells you how your module management is actually doing.

Together, these three phases let you scale module usage as your Terraform footprint grows. You probably won't need all of them on day one. Picking a tool that can grow into them pays off later, once the number of workspaces and modules gets past what you can track by hand.

Get started using modules to define, enforce and report on Terraform using Scalr today.