This module can be used to issue and validate free, auto-renewing TLS certificates using AWS Certificate
Manager (ACM). It supports issuing and validating multiple ACM certificates.
The module will create the TLS certificates, as well as
the DNS records to validate them, and output the certificates' ARNs so you can use them with other resources, such as ALBs, CloudFront, and API Gateway.
How do you use this module?
See the root README for instructions on using Terraform modules.
See vars.tf for all the variables you can set on this module.
Special handling for use with API Gateway
If you are using this module to create a TLS certificate that will be used with API Gateway, along with a custom
domain name, then you need to set a tag named exactly run_destroy_check with a value of true. Do this for every certificate you configure that will be used in this way:
Without this, terraform destroy will fail. This is because you can't delete an ACM cert while it's in use,
deleting a custom domain name mapping for API Gateway takes 10 - 30 minutes, and Terraform only waits a max of 10
minutes to delete the cert, so it times out and exits with an error every time. The run_destroy_check tells this
module to run a script that waits until the cert is no longer in use.
The script is written in Bash, so it will not work on Windows versions earlier than Windows 10, which supports a Linux Bash shell.
A note on the dependency_getter pattern implementing module_depends
This module uses a null_resource named dependency_getter to effectively implement depends_on at the module level. This is a temporary workaround as Terraform does not yet natively support depends_on at the module level. You can also see this Terraform issue on GitHub for more discussion.
Here's how this works. First, we create this optional dependencies variable for the current module, which accepts a list of strings, but defaults to an empty list. The null_resource linked above does a simple join on the dependencies list, if present. Every resource within this module also depends_on this null_resource.dependency_getter(even though it's creating no resources).
This has the desirable effect of causing the dependency graph that Terraform builds to look as you'd expect if there were in fact native support for depends_on at the module level. Let's say you had a separate Terraform module that needed to consume this current module in order to generate certificates, but you wanted this certificates module to wait to do any of its work until some of the outputs from the resources in your parent module were ready. In that case, you could pass those outputs into this module's dependencies variable, like so:
# ---------------------------------------------------------------------------------------------------------------------# CREATE PUBLIC HOSTED ZONE(S)# ---------------------------------------------------------------------------------------------------------------------module"acm-tls-certificates" {
# When using these modules in your own repos, you will need to use a Git URL with a ref attribute that pins you# to a specific version of the modules, such as the following example:# source = "git::git@github.com:gruntwork-io/module-load-balancer.git//modules/acm-tls-certificate?ref=v0.19.0"
source = "git::git@github.com:gruntwork-io/module-load-balancer.git//modules/acm-tls-certificate?ref=v0.20.0"
acm_tls_certificates = local.acm_tls_certificates
# Workaround Terraform limitation where there is no module depends_on.# See https://github.com/hashicorp/terraform/issues/1178 for more details.# This effectively draws an explicit dependency between the public # and private zones managed here and the ACM certificates that will be optionally # provisioned for them
dependencies = flatten([values(aws_route53_zone.public_zones).*.name_servers])
}
In this example, the acm-tls-certificates module will "wait" until your aws_route53_zone.public_zones resources have been successfully provisioned.
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"3033855c6543b81b6e112178567a2b127cc5144c"}]},{"name":".gitignore","path":".gitignore","sha":"be548d345e99887d4ccc3163bf552ee9c337b48d"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"8c24c86ef8447a19436b38826f458c71b4da4f45"},{"name":"LICENSE.txt","path":"LICENSE.txt","sha":"154ea4429924fda533b20544c7a19d8949fc82cf"},{"name":"README.md","path":"README.md","sha":"a6cd1fd34946991704dd8b4478bdb28db5069fa8"},{"name":"_docs","children":[{"name":"migration_guides","children":[{"name":"nlb_to_0.15.0","children":[{"name":"README.md","path":"_docs/migration_guides/nlb_to_0.15.0/README.md","sha":"2a86c02a985b27782134cc30539455ecbd81046d"},{"name":"after_migration","children":[{"name":"main.tf","path":"_docs/migration_guides/nlb_to_0.15.0/after_migration/main.tf","sha":"9afc43a772b630798ab7d0b7a58fdbff9b0379b8"},{"name":"outputs.tf","path":"_docs/migration_guides/nlb_to_0.15.0/after_migration/outputs.tf","sha":"d967d0daa27477b626b7b28911d10b2f18fe6f76"},{"name":"vars.tf","path":"_docs/migration_guides/nlb_to_0.15.0/after_migration/vars.tf","sha":"b8c8af94a7ed9e5db9bd522bf69e0fe304efddee"}]},{"name":"before_migration","children":[{"name":"main.tf","path":"_docs/migration_guides/nlb_to_0.15.0/before_migration/main.tf","sha":"69345f63220752b9d3c83418ea9e31b1c91530a4"},{"name":"outputs.tf","path":"_docs/migration_guides/nlb_to_0.15.0/before_migration/outputs.tf","sha":"dc162b85fc673c12a9d166a1f58021eb142ac447"},{"name":"vars.tf","path":"_docs/migration_guides/nlb_to_0.15.0/before_migration/vars.tf","sha":"b8c8af94a7ed9e5db9bd522bf69e0fe304efddee"}]}]}]}]},{"name":"examples","children":[{"name":"acm-tls-certificate","children":[{"name":"README.md","path":"examples/acm-tls-certificate/README.md","sha":"0a7892a8b5d327254c91a96276273fcc975821ca"},{"name":"dependencies.tf","path":"examples/acm-tls-certificate/dependencies.tf","sha":"237767e8323ffdf0d76a976946fa24c4f12708ce"},{"name":"main.tf","path":"examples/acm-tls-certificate/main.tf","sha":"d349ec37274ee2e9ec78e0ea35a20f08492664b2"},{"name":"outputs.tf","path":"examples/acm-tls-certificate/outputs.tf","sha":"083ef125b3be1f465c66f8b1e8b0ede0c782f10e"},{"name":"vars.tf","path":"examples/acm-tls-certificate/vars.tf","sha":"3b96d4f8aa3d1620494d05538069dbc5d9d4de14"}]},{"name":"alb-with-logs","children":[{"name":"README.md","path":"examples/alb-with-logs/README.md","sha":"b46a1aef114340b80c6742b9344c52f1a952a7a4"},{"name":"main.tf","path":"examples/alb-with-logs/main.tf","sha":"690a7aff11110eab33b17ce18358b945c6c48f51"},{"name":"outputs.tf","path":"examples/alb-with-logs/outputs.tf","sha":"518914d6b608ea2d2996cbaa9361c370bd9c9fa1"},{"name":"vars.tf","path":"examples/alb-with-logs/vars.tf","sha":"029a4cf53d07f1e6e5c04c6173df8a29b0bed98f"}]},{"name":"alb","children":[{"name":"README.md","path":"examples/alb/README.md","sha":"202d51dd9238a27061a6277a4632dce37706a3f9"},{"name":"main.tf","path":"examples/alb/main.tf","sha":"c075a2d24a3e0554f43ac60f96942bda3e6cbb9b"},{"name":"outputs.tf","path":"examples/alb/outputs.tf","sha":"3ab937d31bc4423aa1e17150a40e966fc6cd81da"},{"name":"vars.tf","path":"examples/alb/vars.tf","sha":"3306c4227949373dc9fed5a83dc19f7d6904e007"}]},{"name":"lb-listener-rules","children":[{"name":"README.md","path":"examples/lb-listener-rules/README.md","sha":"3d2205b57641d6e97bc28f2a8a59093c4bfc7f61"},{"name":"main.tf","path":"examples/lb-listener-rules/main.tf","sha":"b3f6723c71308e1b00482a233ffc727b51b1a2be"},{"name":"outputs.tf","path":"examples/lb-listener-rules/outputs.tf","sha":"2f227fe908f34ad51a837a85fa6a064f993fa897"},{"name":"user_data.sh","path":"examples/lb-listener-rules/user_data.sh","sha":"5b667c100463a2ce64a5827e4e9dc357509e1a4c"},{"name":"variables.tf","path":"examples/lb-listener-rules/variables.tf","sha":"6fd908ad8227c3e2b1058a3b752d245aef0c1b5f"}]},{"name":"multiple-acm-tls-certificates","children":[{"name":"main.tf","path":"examples/multiple-acm-tls-certificates/main.tf","sha":"4a55d2e698aa814bb75b5d6ebf3a6890d5bad99c"},{"name":"outputs.tf","path":"examples/multiple-acm-tls-certificates/outputs.tf","sha":"20ec52f607e69887ce2a0b54e68415cf36f034e6"},{"name":"vars.tf","path":"examples/multiple-acm-tls-certificates/vars.tf","sha":"55bb61a54afca24f007dfdf2aed50fb86355d56a"}]}]},{"name":"modules","children":[{"name":"acm-tls-certificate","children":[{"name":"README.md","path":"modules/acm-tls-certificate/README.md","sha":"783321db908f41eb3a1ac97fe84c6203065615e9","toggled":true},{"name":"main.tf","path":"modules/acm-tls-certificate/main.tf","sha":"9ee9cf149dd5b5386a18f1ebf59607ecdd20d9a3"},{"name":"outputs.tf","path":"modules/acm-tls-certificate/outputs.tf","sha":"f075daac320e191ca2849aebab95403a0c5b0776"},{"name":"vars.tf","path":"modules/acm-tls-certificate/vars.tf","sha":"ca6385fbb1865ee150851f3ee165021a6712b45d"},{"name":"wait-until-tls-cert-not-in-use.sh","path":"modules/acm-tls-certificate/wait-until-tls-cert-not-in-use.sh","sha":"68296e34cc4e86fbefcae3820e6de88f2aa6f911"}],"toggled":true},{"name":"alb","children":[{"name":"README.md","path":"modules/alb/README.md","sha":"42e135fca494192c57aaafecdf5e256c353513d7"},{"name":"main.tf","path":"modules/alb/main.tf","sha":"a43476486f08a3c1d4e2165d37fb0d99ed446572"},{"name":"outputs.tf","path":"modules/alb/outputs.tf","sha":"e1de70ae961208480de17161a71e1ff86d96f612"},{"name":"vars.tf","path":"modules/alb/vars.tf","sha":"891a546aaea776ae9191e2396576572696ffa780"}]},{"name":"lb-listener-rules","children":[{"name":"README.md","path":"modules/lb-listener-rules/README.md","sha":"7e5c888dfb9664a5e56f1b1ff64c7541e39b27b5"},{"name":"main.tf","path":"modules/lb-listener-rules/main.tf","sha":"6d78dc11d068461da0f73775f267a066ec60485d"},{"name":"outputs.tf","path":"modules/lb-listener-rules/outputs.tf","sha":"9d3efd16064ff8defdb7e8c95634f875d10832b1"},{"name":"variables.tf","path":"modules/lb-listener-rules/variables.tf","sha":"250d19a12cbe299bbac851d4e3f8db8d4c26c065"}]},{"name":"nlb","children":[{"name":"README.md","path":"modules/nlb/README.md","sha":"20dd5397807d3a10acd5a61d077baeb8cbac81d9"}]}],"toggled":true},{"name":"test","children":[{"name":"README.md","path":"test/README.md","sha":"ded6aae1d95e6fca858a0ef196d3ecf30d4bf5f2"},{"name":"acm_tls_certificate_test.go","path":"test/acm_tls_certificate_test.go","sha":"5f91328bd014ce3b7261fa4ac030497d9542fafd"},{"name":"go.mod","path":"test/go.mod","sha":"ecf9ffde697ff3a0fd2e2d62eba9ce0cf9ed421a"},{"name":"go.sum","path":"test/go.sum","sha":"a21625cae29a42bd8e1738788cda1753994ab4cb"},{"name":"lb_listener_rules_test.go","path":"test/lb_listener_rules_test.go","sha":"31a9c8a5e5d954f45b1da06fd8d87989be480360"},{"name":"lb_test.go","path":"test/lb_test.go","sha":"b10ff812830f07660c86e9d4e793f1817449cd54"}]}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"acm-tls-certificate\">ACM TLS Certificate</h1><div class=\"preview__body--border\"></div><p>This module can be used to issue and validate free, auto-renewing TLS certificates using <a href=\"https://aws.amazon.com/certificate-manager/\" class=\"preview__body--description--blue\" target=\"_blank\">AWS Certificate\nManager (ACM)</a>. It supports issuing and validating multiple ACM certificates.</p>\n<p>The module will create the TLS certificates, as well as\nthe DNS records to validate them, and output the certificates' ARNs so you can use them with other resources, such as ALBs, CloudFront, and API Gateway.</p>\n<h2 class=\"preview__body--subtitle\" id=\"how-do-you-use-this-module\">How do you use this module?</h2>\n<ul>\n<li>See the <a href=\"/repos/v0.21.0/module-load-balancer/README.md\" class=\"preview__body--description--blue\">root README</a> for instructions on using Terraform modules.</li>\n<li>See the <a href=\"/repos/v0.21.0/module-load-balancer/examples\" class=\"preview__body--description--blue\">examples</a> folder for example usage.</li>\n<li>See <a href=\"/repos/v0.21.0/module-load-balancer/modules/acm-tls-certificate/vars.tf\" class=\"preview__body--description--blue\">vars.tf</a> for all the variables you can set on this module.</li>\n</ul>\n<h2 class=\"preview__body--subtitle\" id=\"special-handling-for-use-with-api-gateway\">Special handling for use with API Gateway</h2>\n<p>If you are using this module to create a TLS certificate that will be used with API Gateway, along with a custom\ndomain name, then you need to set a tag named exactly <code>run_destroy_check</code> with a value of <code>true</code>. Do this for every certificate you configure that will be used in this way:</p>\n<pre>module <span class=\"hljs-string\">\"cert\"</span> {\n <span class=\"hljs-attr\">source</span> = <span class=\"hljs-string\">\"git::git@github.com:gruntwork-io/module-load-balancer.git//modules/acm-tls-certificate?ref=v0.13.2\"</span>\n \n <span class=\"hljs-comment\"># ... other params ommitted ...</span>\n \n <span class=\"hljs-attr\">acm_tls_certificates</span> = {\n <span class=\"hljs-string\">\"mail.example.com\"</span> = {\n <span class=\"hljs-attr\">subject_alternative_names</span> = [<span class=\"hljs-string\">\"mailme.example.com\"</span>]\n <span class=\"hljs-attr\">tags</span> = {\n <span class=\"hljs-attr\">Environment</span> = <span class=\"hljs-string\">\"stage\"</span>\n <span class=\"hljs-attr\">run_destroy_check</span> = <span class=\"hljs-literal\">true</span>\n }\n <span class=\"hljs-attr\">create_verification_record</span> = <span class=\"hljs-literal\">true</span>\n <span class=\"hljs-attr\">verify_certificate</span> = <span class=\"hljs-literal\">true</span>\n }\n <span class=\"hljs-string\">\"admin.example.com\"</span> = {\n <span class=\"hljs-attr\">subject_alternative_names</span> = [<span class=\"hljs-string\">\"restricted.example.com\"</span>]\n <span class=\"hljs-attr\">tags</span> = {\n <span class=\"hljs-attr\">Something</span> = <span class=\"hljs-string\">\"else\"</span>\n <span class=\"hljs-attr\">run_destroy_check</span> = <span class=\"hljs-literal\">true</span>\n }\n <span class=\"hljs-attr\">create_verification_record</span> = <span class=\"hljs-literal\">true</span>\n <span class=\"hljs-attr\">verify_certificate</span> = <span class=\"hljs-literal\">true</span>\n }\n }\n \n <span class=\"hljs-comment\"># ... other params ommitted ...</span>\n}\n</pre>\n<p>Without this, <code>terraform destroy</code> will fail. This is because you can't delete an ACM cert while it's in use,\ndeleting a custom domain name mapping for API Gateway takes 10 - 30 minutes, and Terraform only waits a max of 10\nminutes to delete the cert, so it times out and exits with an error every time. The <code>run_destroy_check</code> tells this\nmodule to run a script that waits until the cert is no longer in use.</p>\n<p>Two notes about this script:</p>\n<ol>\n<li>You must install the <a href=\"https://aws.amazon.com/cli/\" class=\"preview__body--description--blue\" target=\"_blank\">AWS CLI</a> to use it.</li>\n<li>The script is written in Bash, so it will not work on Windows versions earlier than Windows 10, which supports a Linux Bash shell.</li>\n</ol>\n<h2 class=\"preview__body--subtitle\" id=\"a-note-on-the-dependency-getter-pattern-implementing-module-depends\">A note on the dependency_getter pattern implementing module_depends</h2>\n<p>This module uses a <a href=\"/repos/v0.21.0/module-load-balancer/modules/acm-tls-certificate/main.tf#L15\" class=\"preview__body--description--blue\">null_resource</a> named <code>dependency_getter</code> to effectively implement <code>depends_on</code> at the module level. This is a temporary workaround as Terraform does not yet natively support <code>depends_on</code> at the module level. You can also see <a href=\"https://github.com/hashicorp/terraform/issues/1178\" class=\"preview__body--description--blue\" target=\"_blank\">this Terraform issue on GitHub</a> for more discussion.</p>\n<p>Here's how this works. First, we create <a href=\"/repos/v0.21.0/module-load-balancer/modules/acm-tls-certificate/vars.tf#L124\" class=\"preview__body--description--blue\">this optional dependencies variable</a> for the current module, which accepts a list of strings, but defaults to an empty list. The <code>null_resource</code> linked above does a simple join on the dependencies list, if present. Every resource within this module also <code>depends_on</code> this <code>null_resource.dependency_getter</code>(even though it's creating no resources).</p>\n<p>This has the desirable effect of causing the dependency graph that Terraform builds to look as you'd expect if there were in fact native support for <code>depends_on</code> at the module level. Let's say you had a separate Terraform module that needed to consume this current module in order to generate certificates, but you wanted this certificates module to wait to do any of its work until some of the outputs from the resources in your parent module were ready. In that case, you could pass those outputs into this module's <code>dependencies</code> variable, like so:</p>\n<pre><span class=\"hljs-comment\"># ---------------------------------------------------------------------------------------------------------------------</span>\n<span class=\"hljs-comment\"># CREATE PUBLIC HOSTED ZONE(S)</span>\n<span class=\"hljs-comment\"># ---------------------------------------------------------------------------------------------------------------------</span>\n\n<span class=\"hljs-keyword\">module</span> <span class=\"hljs-string\">\"acm-tls-certificates\"</span> {\n <span class=\"hljs-comment\"># When using these modules in your own repos, you will need to use a Git URL with a ref attribute that pins you</span>\n <span class=\"hljs-comment\"># to a specific version of the modules, such as the following example:</span>\n <span class=\"hljs-comment\"># source = \"git::git@github.com:gruntwork-io/module-load-balancer.git//modules/acm-tls-certificate?ref=v0.19.0\"</span>\n\n source = <span class=\"hljs-string\">\"git::git@github.com:gruntwork-io/module-load-balancer.git//modules/acm-tls-certificate?ref=v0.20.0\"</span>\n acm_tls_certificates = local.acm_tls_certificates\n\n <span class=\"hljs-comment\"># Workaround Terraform limitation where there is no module depends_on.</span>\n <span class=\"hljs-comment\"># See https://github.com/hashicorp/terraform/issues/1178 for more details.</span>\n <span class=\"hljs-comment\"># This effectively draws an explicit dependency between the public </span>\n <span class=\"hljs-comment\"># and private zones managed here and the ACM certificates that will be optionally </span>\n <span class=\"hljs-comment\"># provisioned for them </span>\n dependencies = flatten([values(aws_route53_zone.public_zones).*.name_servers])\n}\n</pre>\n<p>In this example, the <code>acm-tls-certificates</code> module will "wait" until your <code>aws_route53_zone.public_zones</code> resources have been successfully provisioned.</p>\n","repoName":"module-load-balancer","repoRef":"v0.20.4","serviceDescriptor":{"serviceName":"Elastic Load Balancer (ELB)","serviceRepoName":"module-load-balancer","serviceRepoOrg":"gruntwork-io","cloudProviders":["aws"],"description":"Deploy the Application Load Balancer (ALB) for load balancing HTTP and HTTPS, with support for routing rules and WebSockets.","imageUrl":"elastic.png","licenseType":"subscriber","technologies":["Terraform"],"compliance":[],"tags":[""]},"serviceCategoryName":"Networking","fileName":"README.md","filePath":"/modules/acm-tls-certificate","title":"Repo Browser: Elastic Load Balancer (ELB)","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
main.tf
