update docs

cname/README.md

@@ -1,6 +1,57 @@
 # About
+
+This submodule creates a CNAME (alias) of the fully qualified domain name (FQDN) selected in `name`.  The zone
+is calculcated by splitting after the first dot.  If the zone does not exist in Route 53, and the zone is not associated
+with the VPC in which this is executed, you will get an error such as this:
+
+```script
+Error: no matching Route53Zone found
+
+  with module.lakefront_cname_test.data.aws_route53_zone.zone,
+  on .terraform/modules/lakefront_cname_test/cname/zone_forward.tf line 2, in data "aws_route53_zone" "zone":
+   2: data "aws_route53_zone" "zone" {
+```
+
+You will need to either fix the domain name (zone) or request the VPC have access to the zone. Generally speaking,
+all zones where DNS entries are permitted are already associated with the appropriate VPCs.  Under normal conditions,
+you will want to use the `var.vpc_domain_name` (from the shared parent VPC), or from a `data` resource (see [example](#using-dhcp-options-data-resource)).
+
+It uses a default TTL of 900.
+
+It also creates what we call a heritage record. This is an indication of _what_ thing created the record, and when.  It is added by
+the dynamic route53 Lambdas for EC2 instances, and within this module, it uses its own details.
+
+The record looks like:
+
+```console
+% dig +short in txt _txt.lakefront.dev.edl.census.gov
+_txt.lakefront.dev.edl.census.gov. 900 IN TXT   "heritage=terraform,terraform/account_id=818199694861,terraform/region=us-gov-west-1,terraform/create_time=1679501130"
+```
+
+The fields/key-value pairs are
+
+| name | description |
+|------|-------------|
+| heritage=terraform | primary label indicating all other values will be use \_terraform\_/ as a prefix |
+| {label}/{key}={value} | label (above); key and value (below) |
+| account\_id | AWS Account ID |
+| region | AWS Region where this has been created |
+| create\_time | Unix epoch time on creation of this and the associated record |
+
+You may add additional values here, such as an ALB ID or other useful, short values which do not change, in the `heritage_tags` map:
+
+```hcl
+  heritage_tags = {
+    alb_id = aws_lb.my_lb.id
+  }
+```
+
+Be sure not to use an ARN as a value, and avoid values which change frequently.
+
+# Caveats
 A CNAME may contain only one entry, so if you pass multiple values (a list), it will only use the first one.
 # Usage
+## Simple, using vpc\_domain\_name from parent
 
 ```hcl
 module "lakefront_cname" {

cname/main.tf

@@ -1,7 +1,58 @@
 /* aws-dns :: cname 
 * # About
+*
+* This submodule creates a CNAME (alias) of the fully qualified domain name (FQDN) selected in `name`.  The zone
+* is calculcated by splitting after the first dot.  If the zone does not exist in Route 53, and the zone is not associated
+* with the VPC in which this is executed, you will get an error such as this:
+* 
+* ```script
+* Error: no matching Route53Zone found
+* 
+*   with module.lakefront_cname_test.data.aws_route53_zone.zone,
+*   on .terraform/modules/lakefront_cname_test/cname/zone_forward.tf line 2, in data "aws_route53_zone" "zone":
+*    2: data "aws_route53_zone" "zone" {
+* ```
+* 
+* You will need to either fix the domain name (zone) or request the VPC have access to the zone. Generally speaking,
+* all zones where DNS entries are permitted are already associated with the appropriate VPCs.  Under normal conditions,
+* you will want to use the `var.vpc_domain_name` (from the shared parent VPC), or from a `data` resource (see [example](#using-dhcp-options-data-resource)).
+* 
+* It uses a default TTL of 900.
+* 
+* It also creates what we call a heritage record. This is an indication of _what_ thing created the record, and when.  It is added by
+* the dynamic route53 Lambdas for EC2 instances, and within this module, it uses its own details.
+* 
+* The record looks like:
+* 
+* ```console
+* % dig +short in txt _txt.lakefront.dev.edl.census.gov
+* _txt.lakefront.dev.edl.census.gov. 900 IN TXT   "heritage=terraform,terraform/account_id=818199694861,terraform/region=us-gov-west-1,terraform/create_time=1679501130"
+* ```
+* 
+* The fields/key-value pairs are
+* 
+* | name | description |
+* |------|-------------|
+* | heritage=terraform | primary label indicating all other values will be use _terraform_/ as a prefix |
+* | {label}/{key}={value} | label (above); key and value (below) |
+* | account_id | AWS Account ID |
+* | region | AWS Region where this has been created |
+* | create_time | Unix epoch time on creation of this and the associated record |
+* 
+* You may add additional values here, such as an ALB ID or other useful, short values which do not change, in the `heritage_tags` map:
+* 
+* ```hcl
+*   heritage_tags = {
+*     alb_id = aws_lb.my_lb.id
+*   }
+* ```
+* 
+* Be sure not to use an ARN as a value, and avoid values which change frequently.
+*
+* # Caveats
 * A CNAME may contain only one entry, so if you pass multiple values (a list), it will only use the first one.
 * # Usage
+* ## Simple, using vpc_domain_name from parent
 *
 * ```hcl
 * module "lakefront_cname" {
@@ -12,6 +63,23 @@
 * }
 * ```
 *
+# ## Using DHCP options data resource
+* 
+* data "aws_vpc_dhcp_options" "options" {
+*   filter {
+*     name   = "vpc-id"
+*     values = [local.vpc_id]
+*   }
+* }
+* 
+* module "stat_cname"
+* {
+*   source  = "git@github.e.it.census.gov:terraform-modules/aws-dns//cname"
+*   name    = format("%v.%v","stat",data.aws_vpc_dhc_options.options.domain_name)
+*   values  = aws_lb.adsd_dapps_dev_stat_lb.dns_name
+* }
+* ```
+*
 */
 
 locals {