Merge pull request #58 from mineiros-io/kassianh/feat/terradoc

Add terradoc
mineiros-io · Dec 27, 2021 · 692c9a2 · 692c9a2
2 parents 477e870 + 80567ea
commit 692c9a2
Show file tree

Hide file tree

Showing 4 changed files with 665 additions and 96 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -10,4 +10,3 @@ repos:
       - id: goimports
       - id: golangci-lint
       - id: phony-targets
-      - id: markdown-link-check
diff --git a/Makefile b/Makefile
@@ -112,6 +112,11 @@ help:
 	} \
 	{ lastLine = $$0 }' $(MAKEFILE_LIST)
 
+## Generate README.md with Terradoc
+.PHONY: terradoc
+terradoc:
+	$(call quiet-command,terradoc -o README.md README.tfdoc.hcl)
+
 # Define helper functions
 DOCKER_FLAGS   += ${DOCKER_RUN_FLAGS}
 DOCKER_RUN_CMD  = docker run ${DOCKER_FLAGS} ${BUILD_TOOLS_DOCKER_IMAGE}

diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
-[<img src="https://raw.githubusercontent.com/mineiros-io/brand/3bffd30e8bdbbde32c143e2650b2faa55f1df3ea/mineiros-primary-logo.svg" width="400"/>][homepage]
+[<img src="https://raw.githubusercontent.com/mineiros-io/brand/3bffd30e8bdbbde32c143e2650b2faa55f1df3ea/mineiros-primary-logo.svg" width="400"/>](https://mineiros.io/?ref=terraform-aws-route53)
 
-[![Build Status][badge-build]][build-status]
-[![GitHub tag (latest SemVer)][badge-semver]][releases-github]
-[![Terraform Version][badge-terraform]][releases-terraform]
-[![AWS Provider Version][badge-tf-aws]][releases-aws-provider]
-[![Join Slack][badge-slack]][slack]
+[![Build Status](https://github.com/mineiros-io/terraform-aws-route53/actions/workflows/main.yml/badge.svg)](https://github.com/mineiros-io/terraform-aws-route53/actions)
+[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/mineiros-io/terraform-aws-route53.svg?label=latest&sort=semver)](https://github.com/mineiros-io/terraform-aws-route53/releases)
+[![Terraform Version](https://img.shields.io/badge/terraform-1.x%20|%200.15%200.14%20|%200.13%20|%200.12.20+-623CE4.svg?logo=terraform)](https://github.com/hashicorp/terraform/releases)
+[![AWS Provider Version](https://img.shields.io/badge/AWS-3%20and%202.45+-F8991D.svg?logo=terraform)](https://github.com/terraform-providers/terraform-provider-aws/releases)
+[![Join Slack](https://img.shields.io/badge/[email protected]?logo=slack)](https://mineiros.io/slack)
 
 # terraform-aws-route53
 
@@ -15,18 +15,19 @@ A [Terraform](https://www.terraform.io) module to create a scalable and highly a
 ***This module supports Terraform v1.x, v0.15, v0.14, v0.13 as well as v0.12.20 and above
 and is compatible with the terraform AWS provider v3 as well as v2.45 and above.***
 
+
 - [Module Features](#module-features)
 - [Getting Started](#getting-started)
 - [Examples](#examples)
 - [Module Argument Reference](#module-argument-reference)
   - [Top-level Arguments](#top-level-arguments)
     - [Module Configuration](#module-configuration)
     - [Route53 Zone](#route53-zone)
-    - [Route53 Zone Records](#route53-zone-records)
-      - [`records` Object Attributes](#records-object-attributes)
     - [Route53 Delegation Set](#route53-delegation-set)
-- [Module Attributes Reference](#module-attributes-reference)
+- [Module Outputs](#module-outputs)
 - [External Documentation](#external-documentation)
+  - [AWS Documentation Route53](#aws-documentation-route53)
+  - [Terraform AWS Provider Documentation](#terraform-aws-provider-documentation)
 - [Module Versioning](#module-versioning)
   - [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version)
 - [About Mineiros](#about-mineiros)
@@ -102,134 +103,157 @@ See [variables.tf] and [examples/] for details and use-cases.
 
 #### Module Configuration
 
-- **`module_enabled`**: *(Optional `bool`)*
+- [**`module_enabled`**](#var-module_enabled): *(Optional `bool`)*<a name="var-module_enabled"></a>
 
   Specifies whether resources in the module will be created.
+
   Default is `true`.
 
-- **`module_depends_on`**: *(Optional `list(any)`)*
+- [**`module_depends_on`**](#var-module_depends_on): *(Optional `list(any)`)*<a name="var-module_depends_on"></a>
 
   A list of dependencies. Any object can be _assigned_ to this list to define a
-  hidden external dependency. Default is `[]`.
+  hidden external dependency.
+
+  Default is `[]`.
 
 #### Route53 Zone
 
-- **`name`**: *(Required `any`, Forces new resource)*
+- [**`name`**](#var-name): *(**Required** `any`)*<a name="var-name"></a>
 
   The name of the Hosted Zone. To create multiple Hosted Zones at once,
-  pass a list of names `["zone1", "zone2"]`.
+  pass a list of names `["zone1", "zone2"]`. Forces new resource.
+
+  Example:
+
+  ```hcl
+  Single:   name = "example.com"
+  Multiple: name = ["example.com", "example.io"]
+  ```
 
-- **[`records`](#route53-zone-records)**: *(Optional `any`)*
+- [**`records`**](#var-records): *(Optional `any`)*<a name="var-records"></a>
 
   A list of records to create in the Hosted Zone.
+
   Default is `[]`.
 
-- **`tags`**: *(Optional `map(string)`)*
+  The object accepts the following attributes:
 
-  A map of tags to apply to all created resources that support tags.
-  Default is `{}`.
+  - [**`name`**](#attr-name-records): *(**Required** `string`)*<a name="attr-name-records"></a>
 
-- **`allow_overwrite`**: *(Optional `bool`)*
+    The name of the record.
 
-  Default allow_overwrite value valid for all record sets.
-  Default is `false`.
+  - [**`type`**](#attr-type-records): *(**Required** `string`)*<a name="attr-type-records"></a>
 
-- **`default_ttl`**: *(Optional `number`)*
+    The record type. Valid values are `A`, `AAAA`, `CAA`, `CNAME`, `MX`, `NAPTR`, `NS`, `PTR`, `SOA`, `SPF`, `SRV` and `TXT`.
 
-  The default TTL ( Time to Live ) in seconds that will be used for all records
-  that support the ttl parameter. Will be overwritten by the records ttl
-  parameter if set. Default is `3600`.
+  - [**`ttl`**](#attr-ttl-records): *(Optional `number`)*<a name="attr-ttl-records"></a>
 
-- **`vpc_ids`**: *(Optional `list(string)`)*
+    The TTL of the record.
 
-  A list of IDs of VPCs to associate with a private hosted zone.
-  Conflicts with the delegation_set_id. Default is `[]`.
+    Default is `3600`.
 
-- **`delegation_set_id`**: *(Optional `string`)*
+  - [**`alias`**](#attr-alias-records): *(Optional `object(alias)`)*<a name="attr-alias-records"></a>
 
-  The ID of the reusable delegation set whose NS records you want to assign to
-  the hosted zone. Default is `null`.
+    An alias block. Expects `name`, `zone_id` and `evaluate_target_health` to be defined. Conflicts with `ttl` & `records`.
 
-- **`zone_id`**: *(Optional `string`)*
+    The object accepts the following attributes:
 
-  A zone ID to create the records in. Default is `null`.
+    - [**`name`**](#attr-name-alias-records): *(**Required** `string`)*<a name="attr-name-alias-records"></a>
 
-- **`comment`**: *(Optional `string`)*
+      DNS domain name for a CloudFront distribution, S3 bucket, ELB, or another resource record set in this hosted zone.
 
-  A comment for the hosted zone. Default is `"Managed by Terraform"`.
+    - [**`zone_id`**](#attr-zone_id-alias-records): *(**Required** `string`)*<a name="attr-zone_id-alias-records"></a>
 
-- **`force_destroy`**: *(Optional `bool`)*
+      Hosted zone ID for a CloudFront distribution, S3 bucket, ELB, or Route 53 hosted zone.
 
-  Whether to force destroy all records (possibly managed outside of Terraform)
-  in the zone when destroying the zone. Default is `false`.
+    - [**`evaluate_target_health`**](#attr-evaluate_target_health-alias-records): *(Optional `bool`)*<a name="attr-evaluate_target_health-alias-records"></a>
 
-#### Route53 Zone Records
+      Set to true if you want Route 53 to determine whether to respond to DNS queries using this resource record set by checking the health of the resource record set.
 
-##### [`records`](#route53-zone) Object Attributes
+  - [**`allow_overwrite`**](#attr-allow_overwrite-records): *(Optional `bool`)*<a name="attr-allow_overwrite-records"></a>
 
-- **`name`**: *(Required `string`)*
+    Allow creation of this record in Terraform to overwrite an existing record, if any. This does not affect the ability to update the record in Terraform and does not prevent other resources within Terraform or manual Route 53 changes outside Terraform from overwriting this record.
+    This configuration is not recommended for most environments.
 
-  The name of the record.
+    Default is `false`.
 
-- **`type`**: *(Required `string`)*
+  - [**`health_check_id`**](#attr-health_check_id-records): *(Optional `string`)*<a name="attr-health_check_id-records"></a>
 
-  The record type. Valid values are `A`, `AAAA`, `CAA`, `CNAME`, `MX`, `NAPTR`,
-  `NS`, `PTR`, `SOA`, `SPF`, `SRV` and `TXT`.
+    The health check the record should be associated with.
 
-- **`ttl`**: *(Optional `number`)*
+  - [**`set_identifier`**](#attr-set_identifier-records): *(Optional `string`)*<a name="attr-set_identifier-records"></a>
 
-  The TTL of the record.
-  Default is `3600`.
+    Unique identifier to differentiate records with routing policies from one another. Required if using `failover`, `geolocation`, `latency`, or `weighted routing` policies documented below.
+
+  - [**`weight`**](#attr-weight-records): *(Optional `number`)*<a name="attr-weight-records"></a>
+
+    A numeric value indicating the relative weight of the record. Will turn the record into a weighted record.
+    For details see http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-weighted
+
+  - [**`failover`**](#attr-failover-records): *(Optional `number`)*<a name="attr-failover-records"></a>
+
+    The failover type of the record. Will turn the record into a failover record.
+    Possible values are `PRIMARY` and `SECONDARY`. A `PRIMARY` record will be served if its healthcheck is passing, otherwise the `SECONDARY` will be served.
+    For details see http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover-configuring-options.html#dns-failover-failover-rrsets
+
+- [**`tags`**](#var-tags): *(Optional `map(string)`)*<a name="var-tags"></a>
 
-- **`alias`**: *(Optional `object({name = string, zone_id = string, evaluate_target_health = bool})`)*
+  A map of tags to apply to all created resources that support tags.
+
+  Default is `{}`.
 
-  An alias block. Expects `name`, `zone_id` and `evaluate_target_health`
-  to be defined. Conflicts with `ttl` & `records`.
-  Default is `null`.
+- [**`allow_overwrite`**](#var-allow_overwrite): *(Optional `bool`)*<a name="var-allow_overwrite"></a>
 
-- **`allow_overwrite`**: *(Optional `bool`)*
+  Default allow_overwrite value valid for all record sets.
 
-  Allow creation of this record in Terraform to overwrite an existing record,
-  if any. This does not affect the ability to update the record in Terraform
-  and does not prevent other resources within Terraform or manual Route 53
-  changes outside Terraform from overwriting this record.
-  This configuration is not recommended for most environments.
   Default is `false`.
 
-- **`health_check_id`**: *(Optional `string`)*
+- [**`default_ttl`**](#var-default_ttl): *(Optional `number`)*<a name="var-default_ttl"></a>
 
-  The health check the record should be associated with.
-  Default is `null`.
+  The default TTL ( Time to Live ) in seconds that will be used for all records that support the ttl parameter. Will be overwritten by the records ttl parameter if set.
 
-- **`set_identifier`**: *(Optional `string`)*
+  Default is `3600`.
 
-  Unique identifier to differentiate records with routing policies from one
-  another. Required if using `failover`, `geolocation`, `latency`, or `weighted routing`
-  policies documented below.
+- [**`vpc_ids`**](#var-vpc_ids): *(Optional `list(string)`)*<a name="var-vpc_ids"></a>
 
-- **`weight`**: *(Optional `number`)*
+  A list of IDs of VPCs to associate with a private hosted zone.
+Conflicts with the delegation_set_id.
 
-  A numeric value indicating the relative weight of the record. Will turn the
-  record into a weighted record.
-  For details see http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-weighted
+  Default is `[]`.
+
+- [**`delegation_set_id`**](#var-delegation_set_id): *(Optional `string`)*<a name="var-delegation_set_id"></a>
+
+  The ID of the reusable delegation set whose NS records you want to assign to the hosted zone.
+
+- [**`zone_id`**](#var-zone_id): *(Optional `string`)*<a name="var-zone_id"></a>
+
+  A zone ID to create the records in.
+
+- [**`comment`**](#var-comment): *(Optional `string`)*<a name="var-comment"></a>
 
-- **`failover`**: *(Optional `number`)*
-  The failover type of the record. Will turn the record into a failover record.
-  Possible values are `PRIMARY` and `SECONDARY`. A `PRIMARY` record will be
-  served if its healthcheck is passing, otherwise the `SECONDARY` will be served.
-  For details see http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover-configuring-options.html#dns-failover-failover-rrsets
+  A comment for the hosted zone.
+
+  Default is `"Managed by Terraform"`.
+
+- [**`force_destroy`**](#var-force_destroy): *(Optional `bool`)*<a name="var-force_destroy"></a>
+
+  Whether to force destroy all records (possibly managed outside of Terraform) in the zone when destroying the zone.
+
+  Default is `false`.
 
 #### Route53 Delegation Set
 
-- **`reference_name`**: *(Optional `string`)*
-  The reference name used in Caller Reference (helpful for identifying single
-  delegation set amongst others). Default is `null`.
+- [**`reference_name`**](#var-reference_name): *(Optional `string`)*<a name="var-reference_name"></a>
+
+  The reference name used in Caller Reference (helpful for identifying single delegation set amongst others).
+
+- [**`skip_delegation_set_creation`**](#var-skip_delegation_set_creation): *(Optional `bool`)*<a name="var-skip_delegation_set_creation"></a>
 
-- **`skip_delegation_set_creation`**: *(Optional `bool`)*
   Whether or not to create a delegation set and associate with the created zone.
+
   Default is `false`.
 
-## Module Attributes Reference
+## Module Outputs
 
 The following attributes are exported by the module:
 
@@ -240,16 +264,18 @@ The following attributes are exported by the module:
 
 ## External Documentation
 
-- AWS Documentation Route53:
-  - Zones: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html
-  - Records: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/rrsets-working-with.html
+### AWS Documentation Route53
+
+- Zones: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html
+- Records: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/rrsets-working-with.html
 
-- Terraform AWS Provider Documentation:
-  - https://www.terraform.io/docs/providers/aws/r/route53_zone.html
-  - https://www.terraform.io/docs/providers/aws/r/route53_record.html
-  - https://www.terraform.io/docs/providers/aws/r/route53_delegation_set.html
-  - https://www.terraform.io/docs/providers/aws/r/route53_zone_association.html
-  - https://www.terraform.io/docs/providers/aws/r/route53_health_check.html
+### Terraform AWS Provider Documentation
+
+- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_zone
+- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_record
+- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_delegation_set
+- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_zone_association
+- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_health_check
 
 ## Module Versioning
 
@@ -298,36 +324,31 @@ Run `make help` to see details on each available target.
 This module is licensed under the Apache License Version 2.0, January 2004.
 Please see [LICENSE] for full details.
 
-Copyright &copy; 2020 [Mineiros GmbH][homepage]
+Copyright &copy; 2020-2022 [Mineiros GmbH][homepage]
+
 
 <!-- References -->
 
 [homepage]: https://mineiros.io/?ref=terraform-aws-route53
 [[email protected]]: mailto:[email protected]
-
 [badge-build]: https://github.com/mineiros-io/terraform-aws-route53/actions/workflows/main.yml/badge.svg
 [badge-semver]: https://img.shields.io/github/v/tag/mineiros-io/terraform-aws-route53.svg?label=latest&sort=semver
 [badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg
 [badge-terraform]: https://img.shields.io/badge/terraform-1.x%20|%200.15%200.14%20|%200.13%20|%200.12.20+-623CE4.svg?logo=terraform
 [badge-slack]: https://img.shields.io/badge/[email protected]?logo=slack
-
 [badge-tf-aws]: https://img.shields.io/badge/AWS-3%20and%202.45+-F8991D.svg?logo=terraform
 [releases-aws-provider]: https://github.com/terraform-providers/terraform-provider-aws/releases
-
 [build-status]: https://github.com/mineiros-io/terraform-aws-route53/actions
 [releases-github]: https://github.com/mineiros-io/terraform-aws-route53/releases
 [releases-terraform]: https://github.com/hashicorp/terraform/releases
 [apache20]: https://opensource.org/licenses/Apache-2.0
 [slack]: https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg
-
 [Terraform]: https://www.terraform.io
 [AWS]: https://aws.amazon.com/
 [Semantic Versioning (SemVer)]: https://semver.org/
-
 [alias]: https://aws.amazon.com/premiumsupport/knowledge-center/route-53-create-alias-records/
 [weighted]: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-weighted
 [failover]: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover-configuring.html
-
 [examples/example/main.tf]: https://github.com/mineiros-io/terraform-aws-route53/blob/master/examples/example/main.tf
 [variables.tf]: https://github.com/mineiros-io/terraform-aws-route53/blob/master/variables.tf
 [examples/]: https://github.com/mineiros-io/terraform-aws-route53/tree/master/examples