Add multiple usage examples

Author: ringanta

README.md

@@ -1,6 +1,102 @@
 # Terraform AWS Certificate Manager (ACM) with Multi Zone Module
 
 Terraform module to create an ACM resource that contains domains from multiple Route53 hosted zone.
-ACM validation is using Route53 domain.
+ACM validation is using Route53 only.
 This module supports terraform version 0.12 only.
 
+## Usage
+
+The `domains` variable consist of list of map (object). Each object must consist **zone** and **domain** keys.
+
+- The **zone** key must contains hosted zone name that must be hosted on Route53 in the same AWS account with the requested certificate.
+- The **domain** key contains domain name that will be used in the certificate in the domain name or subject alternative names section.
+
+```terraform
+module "acm" {
+    source = "../"
+
+    domains = [
+        {
+            zone = "example.com"
+            domain = "example.com"
+        },
+        {
+            zone = "example.com"
+            domain = "*.example.com"
+        },
+        {
+            zone = "example.org"
+            domain = "example.org"
+        },
+        {
+            zone =  "example.org"
+            domain = "*.example.org"
+        }
+    ]
+
+    tags = {
+        Name = "Test ACM multiple zone"
+    }
+}
+```
+
+## Examples
+
+- [Basic usage example](./examples/basic/)
+- [Use existing domain validations records](./examples/without-domain-validation)
+
+## Conditional domain validation creation
+
+Let's say we want to create a new ACM certificate and there is exiting ACM certificate with overlapping domain name.
+Most likely domain validation has been setup on Route53 and it makes the existing domain validation will be overwritten.
+Overwritting existing domain validation records might not be a desired behaviour.
+To change this behaviour, exclude setting domain validation records on Route53 by configuring the `validation_set_records` variable to **false**.
+
+```terraform
+module "acm" {
+    source = "../"
+
+    domains = [
+        {
+            zone = "example.com"
+            domain = "example.com"
+        },
+        {
+            zone = "example.com"
+            domain = "*.example.com"
+        },
+        {
+            zone = "example.org"
+            domain = "example.org"
+        },
+        {
+            zone =  "example.org"
+            domain = "*.example.org"
+        }
+    ]
+
+    validation_set_records = false
+
+    tags = {
+        Name = "Test ACM multiple zone"
+    }
+}
+```
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| domains | List of map of string containing domain name for the certificate and its corresponding hosted zone name | `list(map(string))` | n/a | yes |
+| tags | Key and value pair that will be added as tag | `map(string)` | `{}` | no |
+| validate\_certificate | Whether to validate certificate | `bool` | `true` | no |
+| validation\_allow\_overwrite\_records | Whether to allow overwrite of Route53 records | `bool` | `true` | no |
+| validation\_set\_records | Whether to configure Route53 records for validation | `bool` | `true` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| certificate\_arn | The ARN of the certificate |
+| certificate\_domain\_validation\_options | A list of attributes to feed into other resources to complete certificate validation |
+| certificate\_domains | List of domain names covered by the certificate |

examples/.gitignore

@@ -0,0 +1 @@
+test

examples/basic/README.md

@@ -0,0 +1,38 @@
+# Terraform AWS ACM Multiple Hosted Zone Example
+
+This provides example on how to use terraform-aws-acm-multiple-hosted-zone module.
+
+## Usage 
+
+To run this example you need to execute:
+
+```terraform
+terraform init
+terraform plan -out=tfplan.out
+terraform apply tfplan.out
+```
+
+Note that this example may create resources that cost money.
+Run `terraform destroy` when you don't need the resources anymore.
+
+## Requirements
+
+| Name | Version |
+|------|---------|
+| aws | ~> 2.61 |
+
+## Providers
+
+No provider.
+
+## Inputs
+
+No input.
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| certificate\_arn | n/a |
+| certificate\_domains | n/a |
+

examples/basic/main.tf

@@ -0,0 +1,26 @@
+module "acm" {
+    source = "../../"
+
+    domains = [
+        {
+            zone = "example.com"
+            domain = "example.com"
+        },
+        {
+            zone = "example.com"
+            domain = "*.example.com"
+        },
+        {
+            zone = "example.org"
+            domain = "example.org"
+        },
+        {
+            zone =  "example.org"
+            domain = "*.example.org"
+        }
+    ]
+
+    tags = {
+        Name = "Test ACM request with multiple hosted zones"
+    }
+}

examples/basic/outputs.tf

@@ -0,0 +1,7 @@
+output "certificate_arn" {
+    value = module.acm.certificate_arn
+}
+
+output "certificate_domains" {
+    value = module.acm.certificate_domains
+}

examples/basic/providers.tf

@@ -0,0 +1,4 @@
+ provider "aws" {
+     version = "~> 2.61"
+     region = "us-west-2"
+ }

examples/without-domain-validation/README.md

@@ -0,0 +1,38 @@
+# Terraform AWS ACM Multiple Hosted Zone Example
+
+This provides example on how to use terraform-aws-acm-multiple-hosted-zone module without creating or overwriting existing domain validation records on Route53.
+
+## Usage 
+
+To run this example you need to execute:
+
+```terraform
+terraform init
+terraform plan -out=tfplan.out
+terraform apply tfplan.out
+```
+
+Note that this example may create resources that cost money.
+Run `terraform destroy` when you don't need the resources anymore.
+
+## Requirements
+
+| Name | Version |
+|------|---------|
+| aws | ~> 2.61 |
+
+## Providers
+
+No provider.
+
+## Inputs
+
+No input.
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| certificate\_arn | n/a |
+| certificate\_domains | n/a |
+

examples/without-domain-validation/main.tf

@@ -0,0 +1,28 @@
+module "acm" {
+    source = "../../"
+
+    domains = [
+        {
+            zone = "example.com"
+            domain = "example.com"
+        },
+        {
+            zone = "example.com"
+            domain = "*.example.com"
+        },
+        {
+            zone = "example.org"
+            domain = "example.org"
+        },
+        {
+            zone =  "example.org"
+            domain = "*.example.org"
+        }
+    ]
+
+    validation_set_records = false
+
+    tags = {
+        Name = "Test ACM request with multiple hosted zones"
+    }
+}

examples/without-domain-validation/outputs.tf

@@ -0,0 +1,7 @@
+output "certificate_arn" {
+    value = module.acm.certificate_arn
+}
+
+output "certificate_domains" {
+    value = module.acm.certificate_domains
+}

examples/without-domain-validation/providers.tf

@@ -0,0 +1,4 @@
+ provider "aws" {
+     version = "~> 2.61"
+     region = "us-west-2"
+ }