docs: Add example for email validation with validation domain option

README.md

@@ -86,6 +86,7 @@ module "acm" {
 - [Complete example with DNS validation (recommended)](https://github.com/terraform-aws-modules/terraform-aws-acm/tree/master/examples/complete-dns-validation)
 - [Complete example with DNS validation via external DNS provider (CloudFlare)](https://github.com/terraform-aws-modules/terraform-aws-acm/tree/master/examples/complete-dns-validation-with-cloudflare)
 - [Complete example with EMAIL validation](https://github.com/terraform-aws-modules/terraform-aws-acm/tree/master/examples/complete-email-validation)
+- [Complete example with EMAIL validation and validation domain override](https://github.com/terraform-aws-modules/terraform-aws-acm/tree/master/examples/complete-email-validation-with-validation-domain)
 
 ## Conditional creation and validation
 

examples/complete-email-validation-with-validation-domain/README.md

@@ -0,0 +1,69 @@
+# Complete ACM example with EMAIL validation with validation_domain configured
+
+Configuration in this directory creates new Route53 zone and ACM certificate (valid for the domain name and wildcard).
+
+ACM certificate will be created with EMAIL validation method, which means that emails will be send to domain owners and it is not possible to automate using Terraform!
+The validation domain option is set, which overrides the domain to which validation emails will be sent.
+
+If you want to use EMAIL validation method make sure that you have access to at least one of these emails in your domain:
+
+```
+hostmaster@VALIDATION_DOMAIN
+postmaster@VALIDATION_DOMAIN
+admin@VALIDATION_DOMAIN
+administrator@VALIDATION_DOMAIN
+webmaster@VALIDATION_DOMAIN
+```
+
+## Usage
+
+To run this example you need to execute:
+
+```bash
+$ terraform init
+$ terraform plan
+$ terraform apply
+```
+
+Note that this example may create resources which cost money. Run `terraform destroy` when you don't need these resources.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 0.13.1 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.12.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.12.0 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_acm"></a> [acm](#module\_acm) | ../../ | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_route53_zone.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_zone) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_domain_name"></a> [domain\_name](#input\_domain\_name) | Domain name to use as Route53 zone and ACM certificate | `string` | `"foo.bar.com"` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_acm_certificate_arn"></a> [acm\_certificate\_arn](#output\_acm\_certificate\_arn) | The ARN of the certificate |
+| <a name="output_acm_certificate_domain_validation_options"></a> [acm\_certificate\_domain\_validation\_options](#output\_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. |
+| <a name="output_acm_certificate_validation_emails"></a> [acm\_certificate\_validation\_emails](#output\_acm\_certificate\_validation\_emails) | A list of addresses that received a validation E-Mail. Only set if EMAIL-validation was used. |
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/complete-email-validation-with-validation-domain/main.tf

@@ -0,0 +1,26 @@
+resource "aws_route53_zone" "this" {
+  name = var.domain_name
+}
+
+module "acm" {
+  source = "../../"
+
+  domain_name = var.domain_name
+  zone_id     = aws_route53_zone.this.zone_id
+
+  # the key is the domain name which you want to change the validation domain for. validation emails will be send to a fixed list of recipients:
+  # admin@VALIDATION_DOMAIN, administrator@VALIDATION_DOMAIN, hostmaster@VALIDATION_DOMAIN, postmaster@VALIDATION_DOMAIN, webmaster@VALIDATION_DOMAIN
+  # validation_domain has to be a top-level domain of the actual domain
+  validation_option = {
+    "foo.bar.com" = {
+      validation_domain = "bar.com"
+    }
+  }
+
+  validation_method   = "EMAIL"
+  wait_for_validation = false
+
+  tags = {
+    Name = var.domain_name
+  }
+}

examples/complete-email-validation-with-validation-domain/outputs.tf

@@ -0,0 +1,14 @@
+output "acm_certificate_arn" {
+  description = "The ARN of the certificate"
+  value       = module.acm.acm_certificate_arn
+}
+
+output "acm_certificate_domain_validation_options" {
+  description = "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."
+  value       = module.acm.acm_certificate_domain_validation_options
+}
+
+output "acm_certificate_validation_emails" {
+  description = "A list of addresses that received a validation E-Mail. Only set if EMAIL-validation was used."
+  value       = module.acm.acm_certificate_validation_emails
+}

examples/complete-email-validation-with-validation-domain/variables.tf

@@ -0,0 +1,5 @@
+variable "domain_name" {
+  description = "Domain name to use as Route53 zone and ACM certificate"
+  type        = string
+  default     = "foo.bar.com"
+}

examples/complete-email-validation-with-validation-domain/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 0.13.1"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 4.12.0"
+    }
+  }
+}