Terraform AWS ACM Module

The wrappers directory provides a module wrapper pattern designed for scenarios where native Terraform for_each is not feasible, such as when using Terragrunt. This pattern allows you to manage multiple instances of the ACM module within a single configuration block or Terragrunt file by defining a map of items.

This wrapper does not add new functionality; it simply iterates over the provided items map to create multiple resources using the configuration provided in defaults and the specific overrides in each item.

To use the wrapper pattern directly in Terraform, call the module and provide defaults and items arguments. Each entry in the items map will result in a separate ACM resource being managed.

module "wrapper" {
  source = "terraform-aws-modules/acm/aws//wrappers"

  defaults = {
    create = true
    tags = {
      Terraform   = "true"
      Environment = "dev"
    }
  }

  items = {
    my-item = {
      # arguments supported by the root module
    }
    my-second-item = {
      # arguments supported by the root module
    }
  }
}

CloudFront requires ACM certificates to be located in the us-east-1 (N. Virginia) region. To achieve this, define an AWS provider with an alias for us-east-1 and pass it to the module using the providers map.

# CloudFront supports US East (N. Virginia) Region only.
provider "aws" {
  alias  = "us-east-1"
  region = "us-east-1"
}

module "acm" {
  source = "terraform-aws-modules/acm/aws"

  providers = {
    aws = aws.us-east-1
  }

  domain_name = "my-domain.com"
  zone_id     = "Z266PL4W4W6MSG"

  validation_method = "DNS"

  wait_for_validation = true

  tags = {
    Name = "my-domain.com"
  }
}

To manage multiple ACM resources in a single Terragrunt layer, use the tfr:/// source (or the git source) and define defaults and items within the inputs block.

• defaults: A map of configuration arguments applied to all items.
• items: A map where each key represents a unique resource instance, and the value is a map of arguments specific to that instance (which can override or supplement defaults).

terraform {
  source = "tfr:///terraform-aws-modules/acm/aws//wrappers"
}

inputs = {
  defaults = {
    create = true
    tags = {
      Terraform   = "true"
      Environment = "dev"
    }
  }

  items = {
    my-item = {
      # arguments supported by the root module
    }
    my-second-item = {
      # arguments supported by the root module
    }
  }
}

To use this example, ensure your environment meets the following version requirements:

• Terraform: >= 1.5.7
• AWS Provider: >= 6.28

Since Terraform does not allow the use of count within a module block, use the following arguments to control lifecycle behavior:

• create_certificate: Set to false to prevent the creation of the ACM certificate.
• validate_certificate: Set to false to prevent the module from attempting to validate the certificate (e.g., by creating DNS records).

module "acm" {
  source = "terraform-aws-modules/acm/aws"

  create_certificate = false
  # ... omitted
}

To create an ACM certificate and automatically manage the required Route53 DNS validation records, set validation_method to "DNS" and provide the zone_id of your hosted zone. Setting wait_for_validation = true ensures Terraform waits for the certificate to be issued before completing.

module "acm" {
  source  = "terraform-aws-modules/acm/aws"
  version = "~> 4.0"

  domain_name  = "my-domain.com"
  zone_id      = "Z2ES7B9AZ6SHAE"

  validation_method = "DNS"

  subject_alternative_names = [
    "*.my-domain.com",
    "app.sub.my-domain.com",
  ]

  wait_for_validation = true

  tags = {
    Name = "my-domain.com"
  }
}

This example demonstrates how to create a new Route53 zone and an ACM certificate (covering both the domain name and a wildcard) using DNS validation. It supports using one or two AWS provider instances: one for managing ACM resources and another for managing Route53 records.

Warning: This example creates resources that may incur costs. Run terraform destroy to clean up.

$ terraform init
$ terraform plan
$ terraform apply

To use this specific example, ensure your environment meets the following version requirements:

• Terraform: >= 1.5.7
• AWS Provider: >= 6.28
• Cloudflare Provider: >= 3.4, <= 3.32

The following versions are required to run the complete email validation example:

• Terraform: >= 1.5.7
• AWS Provider: >= 6.28

If you are using an external DNS provider, set validation_method = "DNS" and create_route53_records = false. You must manually provide the FQDNs of the validation records using the validation_record_fqdns argument.

module "acm" {
  source  = "terraform-aws-modules/acm/aws"
  version = "~> 4.0"

  domain_name = "weekly.tf"
  zone_id     = "b7d259641bf30b89887c943ffc9d2138"

  validation_method = "DNS"

  subject_alternative_names = [
    "*.weekly.tf",
  ]

  create_route53_records  = false
  validation_record_fqdns = [
    "_689571ee9a5f9ec307c512c5d851e25a.weekly.tf",
  ]

  tags = {
    Name = "weekly.tf"
  }
}