diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ea703b..5951840 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index ab76264..93e1627 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,90 @@ +# 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. | [enable\_sns](#input\_enable\_sns) | Enable use of SNS for reporting errors | `bool` | `false` | no | | [enable\_sqs](#input\_enable\_sqs) | Enable use of SQS for SNS to send errors | `bool` | `false` | no | | [lambda\_environment\_variables](#input\_lambda\_environment\_variables) | Map of lambda environment variables and values | `map(string)` |
{
"DNS_RR_TimeToLive": 60,
"DynamoDBName": null,
"HeritageIdentifier": "dynr53",
"HeritageTXTRecordPrefix": "_txt",
"MaxApiRetry": 10,
"SleepTime": 60,
"SnsEnable": false,
"SnsTopicArn": "",
"TagKeyCname": "boc:dns:cname",
"TagKeyHostName": "boc:dns:name",
"TagKeyZone": "boc:dns:zone"
}
| no | +| [lambda\_environment\_variables\_override](#input\_lambda\_environment\_variables\_override) | Map of lambda environment variables and values to override from the defaults | `map(string)` | `{}` | no | | [lambda\_name](#input\_lambda\_name) | Different Lambda name to override default of var.name | `string` | `null` | no | | [name](#input\_name) | Name to use within all the created resources (default: inf-dynamic-route53) | `string` | `"inf-dynamic-route53"` | no | | [override\_prefixes](#input\_override\_prefixes) | Override built-in prefixes by component. This should be used primarily for common infrastructure things | `map(string)` | `{}` | no | diff --git a/examples/test/test.tf b/examples/test/test.tf index 7e809d5..1689305 100644 --- a/examples/test/test.tf +++ b/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" + } } diff --git a/main.tf b/main.tf new file mode 100644 index 0000000..a866d27 --- /dev/null +++ b/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" +* } +* ``` +*/ diff --git a/variables.tf b/variables.tf index b011b4f..4177326 100644 --- a/variables.tf +++ b/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 diff --git a/version.tf b/version.tf index 852c942..898cbc5 100644 --- a/version.tf +++ b/version.tf @@ -1,3 +1,3 @@ locals { - _module_version = "0.2.1" + _module_version = "0.2.2" }