add initial docs

README.md

@@ -0,0 +1,75 @@
+# aws-dynamic-route53
+
+## About
+
+This module will construct all the resources to allow for automated C2 DNS registration in Route53.  This is largely sourced from the
+AWS blog on [DNS in a Multiaccount Environment with Route53][^blog].  We have added to it to also do PTR registration, as well as
+making it IPv6 ready.
+
+The code from that blog is linked in as a submodule under [aws-lambda-ddns-function](aws-lambda-ddns-function).
+
+This code is intended to be deployed per region, and will handle all of the DNS registration for EC2
+instances deployed, assumign specific tags exist.
+
+It will create:
+
+- DynamoDB Table (inf-dynamic-route53-{region})
+- IAM Roles
+- Lambda
+- CloudWatch Events
+- CloudWatch Log
+
+## Operation
+
+See the the blog[^blog] for full details on how it works.  The short version is:
+
+- Cloudwatch event on instance (starting, started, terminated)
+- Run lambda
+- On startup
+  - Get instance details (id, region, ipv4, ipv6)
+  - Determine zone from tag(s)
+  - Find zone
+  - Add records if found
+  - Log action
+  - Record in DDB name and details
+- On terminate
+  - Get instance detail (id)
+  - search DDB table for id
+  - Remove records, if in table
+  - Log action
+
+
+## Tags
+
+A number of tags will be used to affect behavior of the DNS entries.
+
+### Tag: Name
+
+The `Name` tag is the primary tag that will be used to determine the DNS name to create.  It is expected to be a unique FQDN.  If no Name
+tag is provided, the hostname portion of the name will be constructed from the IP address:
+
+* IPv4
+  * ip address: A.B.C.D
+  * hostname: ip-A-B-C-D
+* IPv6 (TBD)
+
+The domain portion of the `Name` tag must exist within Route53 in order for any records to be created.
+
+### Tag: boc:dns:zone
+
+The `boc:dns:zone` tag will be used in case we need to force a specific domain name on a host, either because it cannot obtain
+the proper zone (domain) from the `Name` tag, of that a custom per-instance `Name` tag cannot be created.  This latter condition
+occurs for systems which work from a launch template, such as EMR or EKS.
+
+### Tag: boc:dns:alias
+
+The `boc:dns:alias` tag is used to create an alternate DNS name (CNAME), pointed to the primary name.  It is an FQDN, and the same conditions
+apply as with [Name](#tag--name).
+
+# Links
+
+* github aws-lambda-ddns-funciton
+  * [^github]: https://github.com/aws-samples/aws-lambda-ddns-function
+* Blog
+  * [^blog]: https://aws.amazon.com/blogs/security/simplify-dns-management-in-a-multiaccount-environment-with-route-53-resolver/
+