/terraform-aws-acm

Terraform module which creates and validates ACM certificate 🇺🇦

Primary LanguageHCLApache License 2.0Apache-2.0

AWS Certificate Manager (ACM) Terraform module

Terraform module which creates ACM certificates and validates them using Route53 DNS (recommended) or e-mail.

SWUbanner

Usage with Route53 DNS validation (recommended)

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

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

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

  wait_for_validation = true

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

Usage with external DNS validation (e.g. CloudFlare)

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

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

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

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

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

Usage with CloudFront

# 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"

  wait_for_validation = true

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

Usage with Route53 DNS validation and separate AWS providers

provider "aws" {
  alias = "acm"
}

provider "aws" {
  alias = "route53"
}

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

  providers = {
    aws = aws.acm
  }

  domain_name  = "my-domain.com"

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

  create_route53_records  = false
  validation_record_fqdns = module.route53_records.validation_route53_record_fqdns
}

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

  providers = {
    aws = aws.route53
  }

  create_certificate          = false
  create_route53_records_only = true

  distinct_domain_names = module.acm.distinct_domain_names
  zone_id               = "Z266PL4W4W6MSG"

  acm_certificate_domain_validation_options = module.acm.acm_certificate_domain_validation_options
}

Examples

Conditional creation and validation

Sometimes you need to have a way to create ACM certificate conditionally but Terraform does not allow to use count inside module block, so the solution is to specify argument create_certificate.

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

  create_certificate = false
  # ... omitted
}

Similarly, to disable DNS validation of ACM certificate:

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

  validate_certificate = false
  # ... omitted
}

Notes

  • For use in an automated pipeline consider setting the wait_for_validation = false to avoid waiting for validation to complete or error after a 45 minute timeout.
  • If you're upgrading to v2.13.0 or above, you might be subject to off-by-one validation record issue. You can solve this without compromising existing validation records by issuing terraform state rm <your_module_name>.validation[1] where [1] can be a different index # depending on the number of validation records your module creates (you can check this with terraform state list module.<your_module_name>.validation).

Requirements

Name Version
terraform >= 1.0
aws >= 4.40

Providers

Name Version
aws >= 4.40

Modules

No modules.

Resources

Name Type
aws_acm_certificate.this resource
aws_acm_certificate_validation.this resource
aws_route53_record.validation resource

Inputs

Name Description Type Default Required
acm_certificate_domain_validation_options A list of domain_validation_options created by the ACM certificate to create required Route53 records from it (used when create_route53_records_only is set to true) any {} no
certificate_transparency_logging_preference Specifies whether certificate details should be added to a certificate transparency log bool true no
create_certificate Whether to create ACM certificate bool true no
create_route53_records When validation is set to DNS, define whether to create the DNS records internally via Route53 or externally using any DNS provider bool true no
create_route53_records_only Whether to create only Route53 records (e.g. using separate AWS provider) bool false no
distinct_domain_names List of distinct domains and SANs (used when create_route53_records_only is set to true) list(string) [] no
dns_ttl The TTL of DNS recursive resolvers to cache information about this record. number 60 no
domain_name A domain name for which the certificate should be issued string "" no
key_algorithm Specifies the algorithm of the public and private key pair that your Amazon issued certificate uses to encrypt data string null no
putin_khuylo Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Putin_khuylo! bool true no
subject_alternative_names A list of domains that should be SANs in the issued certificate list(string) [] no
tags A mapping of tags to assign to the resource map(string) {} no
validate_certificate Whether to validate certificate by creating Route53 record bool true no
validation_allow_overwrite_records Whether to allow overwrite of Route53 records bool true no
validation_method Which method to use for validation. DNS or EMAIL are valid, NONE can be used for certificates that were imported into ACM and then into Terraform. string "DNS" no
validation_option The domain name that you want ACM to use to send you validation emails. This domain name is the suffix of the email addresses that you want ACM to use. any {} no
validation_record_fqdns When validation is set to DNS and the DNS validation records are set externally, provide the fqdns for the validation list(string) [] no
validation_timeout Define maximum timeout to wait for the validation to complete string null no
wait_for_validation Whether to wait for the validation to complete bool true no
zone_id The ID of the hosted zone to contain this record. Required when validating via Route53 string "" no

Outputs

Name Description
acm_certificate_arn The ARN of the certificate
acm_certificate_domain_validation_options A list of attributes to feed into other resources to complete certificate validation. Can have more than one element, e.g. if SANs are defined. Only set if DNS-validation was used.
acm_certificate_status Status of the certificate.
acm_certificate_validation_emails A list of addresses that received a validation E-Mail. Only set if EMAIL-validation was used.
distinct_domain_names List of distinct domains names used for the validation.
validation_domains List of distinct domain validation options. This is useful if subject alternative names contain wildcards.
validation_route53_record_fqdns List of FQDNs built using the zone domain and name.

Authors

Module is maintained by Anton Babenko with help from these awesome contributors.

License

Apache 2 Licensed. See LICENSE for full details.

Additional information for users from Russia and Belarus