add varible for override, add main.tf for docs

CHANGELOG.md

@@ -62,3 +62,8 @@
 
 * 0.2.1 -- 2022-03-08
   - use Sns* Lamba variables based on enable_sns
+
+* 0.2.2 -- 2022-03-24
+  - add documenation (main.tf)
+  - add variable lambda_environment_variables_override
+  - update example/test/test.tf

README.md

@@ -1,4 +1,90 @@
 <!-- BEGIN_TF_DOCS -->
+# About :: aws-dynamic-route53
+
+This module sets up all the things one needs to enable the dynamic creation and removal of Route53 records.  It requires
+the VPC to have the following:
+
+* DHCP option for DNS enabled
+* DHCP option for DNS domain name
+* Route53 zone for the DNS domain name in the DHCP option
+* Route53 zone for all of the PTR subnets for the VPC (x.y.z.in-addr.arpa)
+
+This module creates these resources:
+
+* DyanmoDB Table for tracking the instances
+* CloudWatch Log
+* Lambda Function
+* IAM role and policy for Lambda
+* SNS topic (if `enable_sns=true`)
+
+# Deployment
+
+This should be deployed per account in each region where the automated Route53 is desired. DNS entries are created on EC2 instance
+startup (when running) and removed on shutdown or termination.   The instance IDs are tracked in the DynamoDB Table.  Here's how
+DNS entries are handled:
+
+1. If the `Name` tags exists, it will take the host part of the name (up to the first dot) and create an A and PTR records for the
+hostname with the DHCP options domain.
+1. If there is no `Name` tag, it will use the _IP Address Format_ (ip-x-x-x-x where the private IP is x.x.x.) with the domain from the DHCP options.
+1. If the tag `boc:dns:name` exists on the EC2 instance, it will use this name to enter into DNS. This assumes the domain part of the name exists and is
+associated to the VPC.  Using this tag, you can create a completely different name from the `Name` tag.
+1. If the tag `boc:dns:zone` exits on the EC2 instance, it will take the hostname part of the `Name` tag, and add the zone, and use this name
+in DNS. This assumes the domain part of the name exists and is associated to the VPC.  If there is no `Name` tag, it will use the _IP Address Format_ (ip-x-x-x-x where the private IP is x.x.x.).
+Using this tag, you can create the host in a completely different zone from that of the DHCP options.
+1. If the tag `boc:dns:cname` exists, that name will be entered in DNS in the zone indicated by the tag as a CNAME to the main name (as determined above),
+assuming the domain part of the name exists and is associated to the VPC.
+
+We also add what is called a _heritage_ TXT record, associated with the instance.  It looks like this:
+
+```script
+"heritage=dynr53,dynr53/version=0.2.1,dynr53/account_id=252999262699,dynr53/region=us-gov-west-1,dynr53/instance_id=i-0e836a68e01f8b1c3,dynr53/create_time=1648143761"
+```
+
+This is createed as a TXT record on
+
+* the hostname, however it is determined from the above rules
+* on the associated PTR resource record (RR), that is, `x.x.x.x.in-addr.arpa IN TXT ...`
+* and with a default prefix of \_txt with the CNAME if using the `boc:dns:cname` tag, because, you cannot have more than one RR when using a CNAME
+
+If SNS is enabled, any errors will cause a message to be published to the SNS topic.
+
+# Usage
+
+This is a simmple call.  With no arguments, it will setup everything besides the SNS topic.
+
+```hcl
+module "dynamic-route53" {
+  source = "git@github.e.it.census.gov:terraform-modules/aws-dynamic-route53.git"
+
+  enable_sns = true
+  lambda_environment_variables_override = {
+    "DebugLevel" = "DEBUG"
+  }
+}
+```
+
+# Defaults
+
+The folowing defualts are applied to the Lambda function.  There is ordinarily no need to change
+these.
+
+```hcl
+  {
+    DebugLevel              = "INFO"
+    SleepTime               = 60
+    DynamoDBName            = null
+    TagKeyCname             = "boc:dns:cname"
+    TagKeyZone              = "boc:dns:zone"
+    TagKeyHostName          = "boc:dns:name"
+    DNS_RR_TimeToLive       = 60
+    MaxApiRetry             = 10
+    SnsTopicArn             = ""
+    SnsEnable               = false
+    HeritageTXTRecordPrefix = "_txt"
+    HeritageIdentifier      = "dynr53"
+  }
+```
+
 ## Requirements
 
 | Name | Version |
@@ -50,6 +136,7 @@ No modules.
 | <a name="input_enable_sns"></a> [enable\_sns](#input\_enable\_sns) | Enable use of SNS for reporting errors | `bool` | `false` | no |
 | <a name="input_enable_sqs"></a> [enable\_sqs](#input\_enable\_sqs) | Enable use of SQS for SNS to send errors | `bool` | `false` | no |
 | <a name="input_lambda_environment_variables"></a> [lambda\_environment\_variables](#input\_lambda\_environment\_variables) | Map of lambda environment variables and values | `map(string)` | <pre>{<br>  "DNS_RR_TimeToLive": 60,<br>  "DynamoDBName": null,<br>  "HeritageIdentifier": "dynr53",<br>  "HeritageTXTRecordPrefix": "_txt",<br>  "MaxApiRetry": 10,<br>  "SleepTime": 60,<br>  "SnsEnable": false,<br>  "SnsTopicArn": "",<br>  "TagKeyCname": "boc:dns:cname",<br>  "TagKeyHostName": "boc:dns:name",<br>  "TagKeyZone": "boc:dns:zone"<br>}</pre> | no |
+| <a name="input_lambda_environment_variables_override"></a> [lambda\_environment\_variables\_override](#input\_lambda\_environment\_variables\_override) | Map of lambda environment variables and values to override from the defaults | `map(string)` | `{}` | no |
 | <a name="input_lambda_name"></a> [lambda\_name](#input\_lambda\_name) | Different Lambda name to override default of var.name | `string` | `null` | no |
 | <a name="input_name"></a> [name](#input\_name) | Name to use within all the created resources (default: inf-dynamic-route53) | `string` | `"inf-dynamic-route53"` | no |
 | <a name="input_override_prefixes"></a> [override\_prefixes](#input\_override\_prefixes) | Override built-in prefixes by component. This should be used primarily for common infrastructure things | `map(string)` | `{}` | no |

examples/test/test.tf

@@ -1,4 +1,8 @@
 module "dynamic-route53" {
-  source = "git@github.e.it.census.gov:terraform-modules/aws-dynamic-route53.git?ref=initial"
+  source = "git@github.e.it.census.gov:terraform-modules/aws-dynamic-route53.git"
 
+  enable_sns = true
+  lambda_environment_variables_override = {
+    "DebugLevel" = "DEBUG"
+  }
 }

main.tf

@@ -0,0 +1,87 @@
+/*
+* # About :: aws-dynamic-route53
+* 
+* This module sets up all the things one needs to enable the dynamic creation and removal of Route53 records.  It requires
+* the VPC to have the following:
+* 
+* * DHCP option for DNS enabled
+* * DHCP option for DNS domain name
+* * Route53 zone for the DNS domain name in the DHCP option
+* * Route53 zone for all of the PTR subnets for the VPC (x.y.z.in-addr.arpa)
+* 
+* This module creates these resources:
+* 
+* * DyanmoDB Table for tracking the instances
+* * CloudWatch Log
+* * Lambda Function
+* * IAM role and policy for Lambda
+* * SNS topic (if `enable_sns=true`)
+* 
+* # Deployment 
+* 
+* This should be deployed per account in each region where the automated Route53 is desired. DNS entries are created on EC2 instance
+* startup (when running) and removed on shutdown or termination.   The instance IDs are tracked in the DynamoDB Table.  Here's how
+* DNS entries are handled:
+* 
+* 1. If the `Name` tags exists, it will take the host part of the name (up to the first dot) and create an A and PTR records for the
+* hostname with the DHCP options domain.
+* 1. If there is no `Name` tag, it will use the _IP Address Format_ (ip-x-x-x-x where the private IP is x.x.x.) with the domain from the DHCP options.
+* 1. If the tag `boc:dns:name` exists on the EC2 instance, it will use this name to enter into DNS. This assumes the domain part of the name exists and is
+* associated to the VPC.  Using this tag, you can create a completely different name from the `Name` tag.
+* 1. If the tag `boc:dns:zone` exits on the EC2 instance, it will take the hostname part of the `Name` tag, and add the zone, and use this name
+* in DNS. This assumes the domain part of the name exists and is associated to the VPC.  If there is no `Name` tag, it will use the _IP Address Format_ (ip-x-x-x-x where the private IP is x.x.x.).
+* Using this tag, you can create the host in a completely different zone from that of the DHCP options.
+* 1. If the tag `boc:dns:cname` exists, that name will be entered in DNS in the zone indicated by the tag as a CNAME to the main name (as determined above),
+* assuming the domain part of the name exists and is associated to the VPC.
+* 
+* We also add what is called a _heritage_ TXT record, associated with the instance.  It looks like this:
+* 
+* ```script
+* "heritage=dynr53,dynr53/version=0.2.1,dynr53/account_id=252999262699,dynr53/region=us-gov-west-1,dynr53/instance_id=i-0e836a68e01f8b1c3,dynr53/create_time=1648143761"
+* ```
+* 
+* This is createed as a TXT record on
+* 
+* * the hostname, however it is determined from the above rules
+* * on the associated PTR resource record (RR), that is, `x.x.x.x.in-addr.arpa IN TXT ...`
+* * and with a default prefix of _txt with the CNAME if using the `boc:dns:cname` tag, because, you cannot have more than one RR when using a CNAME
+* 
+* If SNS is enabled, any errors will cause a message to be published to the SNS topic.
+* 
+* # Usage
+* 
+* This is a simmple call.  With no arguments, it will setup everything besides the SNS topic.
+* 
+* ```hcl
+* module "dynamic-route53" {
+*   source = "git@github.e.it.census.gov:terraform-modules/aws-dynamic-route53.git"
+* 
+*   enable_sns = true
+*   lambda_environment_variables_override = {
+*     "DebugLevel" = "DEBUG"
+*   }
+* }
+* ```
+* 
+* # Defaults
+* 
+* The folowing defualts are applied to the Lambda function.  There is ordinarily no need to change
+* these.
+* 
+* ```hcl
+*   {
+*     DebugLevel              = "INFO"
+*     SleepTime               = 60
+*     DynamoDBName            = null
+*     TagKeyCname             = "boc:dns:cname"
+*     TagKeyZone              = "boc:dns:zone"
+*     TagKeyHostName          = "boc:dns:name"
+*     DNS_RR_TimeToLive       = 60
+*     MaxApiRetry             = 10
+*     SnsTopicArn             = ""
+*     SnsEnable               = false
+*     HeritageTXTRecordPrefix = "_txt"
+*     HeritageIdentifier      = "dynr53"
+*   }
+* ```
+*/

variables.tf

@@ -46,6 +46,12 @@ variable "lambda_environment_variables" {
   }
 }
 
+variable "lambda_environment_variables_override" {
+  description = "Map of lambda environment variables and values to override from the defaults"
+  type        = map(string)
+  default     = {}
+}
+
 variable "enable_sns" {
   description = "Enable use of SNS for reporting errors"
   type        = bool

version.tf

@@ -1,3 +1,3 @@
 locals {
-  _module_version = "0.2.1"
+  _module_version = "0.2.2"
 }