upgraded documentation in preparation for module community release

apolloakora · apolloakora · commit 22ba0e3d111a · 2019-09-19T12:50:11.000+01:00
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 
-# PostgreSQL RDS | Enterprise Grade | Terraform Module
+# PostgreSQL RDS | Create from Snapshot or Create New
 
-Provision either a new **enterprise grade** PostgreSQL RDS database or **create a clone of another database from its snapshot**. In this context enterprise grade means
+Provision _either_ a new **enterprise grade** PostgreSQL RDS database _or_ **create a clone of another database from its snapshot**. In this context enterprise grade means
 - a 48 long password chosen from a set of 70 characters
 - a non predictable master database username string
 - a high redundancy multi-availability zone database
@@ -10,118 +10,88 @@ Provision either a new **enterprise grade** PostgreSQL RDS database or **create
 - robust options for backup (maintenance) windows and retention period
 - sensible descriptive resource tags
 
-## From Snapshot or New
 
-This module will conditionally **instantiate from a snapshot** depending on a boolean variable that you provide.
-
-## integration test | Jenkinsfile
-
-This module comes with an **[integraion test](integration/postgres.test-main.tf)** and a Jenkinsfile so you know that it has been validated day in, day out. It doesn't grow stale and stop working like many other Terraform modules.
-
-## Test Drive | Create Two Databases
-
-Why not test drive this PostgreSQL terraform module.
+---
 
-```
-git clone https://github.com/devops4me/terraform-aws-postgres-rds
-cd terraform-aws-postgres-rds/integration
-# Export your AWS Credentials and Region
-terraform init
-terraform deploy
-```
 
-## Usage | Creating New and Cloned Databases
+## Module Usage | Create New and/or Cloned RDS DBs
 
-This is a small insight 
+This module will conditionally **instantiate from a snapshot** depending on whether **`var.in_clone_snapshot`** is true or false. If true the RDS ID of the database to clone must be provided. This last available snapshot is chosen as the baseline for creating the cloned database.
 
 ```
-    locals {
-        ecosystem_name = "canary"
-        fresh_db_name  = "freshdb"
-        clone_db_name  = "clonedb"
-    }
-
     module fresh_db {
 
-        source = "github.com/devops4me/terraform-aws-postgres-rds"
+        source                 = "devops4me/postgres-rds/aws"
+        version                = "1.0.1"
 
         in_security_group_id = module.security-group.out_security_group_id
         in_db_subnet_ids     = module.vpc-network.out_private_subnet_ids
-        in_database_name     = local.fresh_db_name
-
-        in_ecosystem_name  = local.ecosystem_name
-        in_tag_timestamp   = module.resource-tags.out_tag_timestamp
-        in_tag_description = module.resource-tags.out_tag_description
+        in_database_name     = "fresh_db"
     }
 
     module clone_db {
 
-        source = "github.com/devops4me/terraform-aws-postgres-rds"
+        source                 = "devops4me/postgres-rds/aws"
+        version                = "1.0.1"
 
-        in_security_group_id = module.security-group.out_security_group_id
-        in_db_subnet_ids     = module.vpc-network.out_private_subnet_ids
+        in_clone_snapshot    = true
         in_id_of_db_to_clone = var.in_id_of_db_to_clone
-        in_clone_snapshot = true
 
-        in_database_name = local.clone_db_name
-
-        in_ecosystem_name  = local.ecosystem_name
-        in_tag_timestamp   = module.resource-tags.out_tag_timestamp
-        in_tag_description = module.resource-tags.out_tag_description
+        in_security_group_id = module.security-group.out_security_group_id
+        in_db_subnet_ids     = module.vpc-network.out_private_subnet_ids
+        in_database_name     = "cloned_db"
     }
 ```
 
 The important outputs are the **out_database_hostname**, **out_database_username** and the **out_database_password**.
 
 Look at the integration test for the bells and whistles that terraform demands.
 
+
 ---
 
+
 ## Inputs
 
 This AWS PostgreSQL database terraform module requires these input variables.
 **Important - the database name must start with a letter (not a digit) and can only contain alphanumerics.**
 
-| Imported | Type | Comment |
+| Input Variable | Type | Comment |
 |:-------- |:---- |:------- |
-**in_security_group_id** | String | security group constraining database traffic flows
-**in_db_subnet_ids** | List | private subnet IDs in which to create the database
-**in_database_name** | String | alphanumeric only name to give the new database
-
+**in_database_name** | String | **alphanumeric only name** to give the new database and it must start with a letter - note that providing a different name causes terraform to create a different database
+**in_clone_snapshot** | Boolean | if true the in_id_of_db_to_clone must be provided and will cause the database to be created from the last available snapshot of the specified database
+**in_id_of_db_to_clone** | String | this ID must be provided if **`in_clone_snapshot`** is true causing the database to be created from the last available snapshot
+**in_security_group_id** | String | the security group that will constrain traffic to and from the  database
+**in_db_subnet_ids** | List | list of private subnet IDs in at least two availability zones (see example) for housing database instances
 
-## Outputs
 
-| Exported                 | Type   | Comment |
-|:------------------------ |:------ |:------- |
-**out_database_hostname**  | String | The addressable hostname of the database
-**out_database_password**  | String | password protecting the database account
+### Resource Tag Inputs
 
+Most organisations have a mandatory set of tags that must be placed on AWS resources for cost and billing reports. Typically they denote owners and specify whether environments are prod or non-prod.
 
-### Contributing
 
-Bug reports and pull requests are welcome on GitHub at the https://github.com/devops4me/terraform-aws-postgres-rds page. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Additionally you can denote 
 
-License
--------
+| Input Variable    | Variable Description | Input Example
+|:----------------- |:-------------------- |:----- |
+**`in_ecosystem`** | the ecosystem (environment) name these resources belong to | **`my-app-test`** or **`kubernetes-cluster`**
+**`in_timestamp`** | the timestamp in resource names helps you identify which environment instance resources belong to | **`1911021435`** as **`$(date +%y%m%d%H%M%S)`**
+**`in_description`** | a human readable description usually stating who is creating the resource and when and where | "was created by $USER@$HOSTNAME on $(date)."
 
-MIT License
-Copyright (c) 2006 - 2014
+Try **`echo $(date +%y%m%d%H%M%S)`** to check your timestamp and **`echo "was created by $USER@$HOSTNAME on $(date)."`** to check your description. Here is how you can send these values to terraform.
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+```
+$ export TF_VAR_in_timestamp=$(date +%y%m%d%H%M%S)
+$ export TF_VAR_in_description="was created by $USER@$HOSTNAME on $(date)."
+```
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+## Outputs
 
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+| Output Variable          | Type   | Comment |
+|:------------------------ |:------ |:------- |
+**out_database_username**  | String | The first database username prefixed with user_rw_ followed by randomized characters.
+**out_database_password**  | String | Robust terraform created 48 character password that includes the allowed special characters
+**out_clone_db_hostname**  | String | The addressable hostname of the database that has been cloned from a snapshot
+**out_clone_db_endpoint**  | String | The database endpoint with protool suffix of the database that has been cloned from a snapshot
+**out_fresh_db_hostname**  | String | The addressable hostname of the newly created (fresh) database
+**out_fresh_db_endpoint**  | String | The database endpoint with protool suffix of the newly created (fresh) database
diff --git a/example/postgres.example-main.tf b/example/postgres.example-main.tf
@@ -52,9 +52,9 @@ module fresh_db {
     in_db_subnet_ids     = module.vpc-network.out_private_subnet_ids
     in_database_name     = local.fresh_db_name
 
-    in_ecosystem_name  = local.ecosystem_name
-    in_tag_timestamp   = module.resource-tags.out_tag_timestamp
-    in_tag_description = module.resource-tags.out_tag_description
+    in_ecosystem  = local.ecosystem_name
+    in_timestamp   = module.resource-tags.out_tag_timestamp
+    in_description = module.resource-tags.out_tag_description
 }
 
 
@@ -69,9 +69,9 @@ module clone_db {
 
     in_database_name = local.clone_db_name
 
-    in_ecosystem_name  = local.ecosystem_name
-    in_tag_timestamp   = module.resource-tags.out_tag_timestamp
-    in_tag_description = module.resource-tags.out_tag_description
+    in_ecosystem  = local.ecosystem_name
+    in_timestamp   = module.resource-tags.out_tag_timestamp
+    in_description = module.resource-tags.out_tag_description
 }
 
 
@@ -82,9 +82,9 @@ module vpc-network {
     in_num_public_subnets  = 3
     in_num_private_subnets = 3
 
-    in_ecosystem_name  = local.ecosystem_name
-    in_tag_timestamp   = module.resource-tags.out_tag_timestamp
-    in_tag_description = module.resource-tags.out_tag_description
+    in_ecosystem  = local.ecosystem_name
+    in_timestamp   = module.resource-tags.out_tag_timestamp
+    in_description = module.resource-tags.out_tag_description
 }
 
 
@@ -94,9 +94,9 @@ module security-group {
     in_ingress     = [ "postgres" ]
     in_vpc_id      = module.vpc-network.out_vpc_id
 
-    in_ecosystem_name  = local.ecosystem_name
-    in_tag_timestamp   = module.resource-tags.out_tag_timestamp
-    in_tag_description = module.resource-tags.out_tag_description
+    in_ecosystem  = local.ecosystem_name
+    in_timestamp   = module.resource-tags.out_tag_timestamp
+    in_description = module.resource-tags.out_tag_description
 }
 
 
diff --git a/rds.postgres-main.tf b/rds.postgres-main.tf
@@ -25,7 +25,7 @@ locals {
 resource aws_db_instance fresh {
 
     count = var.in_clone_snapshot ? 0 : 1
-    identifier = "${ var.in_database_name }-fresh-${ var.in_ecosystem_name }-${ var.in_tag_timestamp }"
+    identifier = "${ var.in_database_name }-fresh-${ var.in_ecosystem }-${ var.in_timestamp }"
 
     name     = var.in_database_name
     username = local.db_username
@@ -72,7 +72,7 @@ resource aws_db_instance clone {
     count = var.in_clone_snapshot ? 1 : 0
 
     snapshot_identifier = data.aws_db_snapshot.from[0].id
-    identifier = "${ var.in_database_name }-clone-${ var.in_ecosystem_name }-${ var.in_tag_timestamp }"
+    identifier = "${ var.in_database_name }-clone-${ var.in_ecosystem }-${ var.in_timestamp }"
 
     name     = var.in_database_name
     port     = 5432
@@ -119,8 +119,8 @@ data aws_db_snapshot from {
 */
 resource aws_db_subnet_group me {
 
-    name_prefix = "db-${ var.in_ecosystem_name }"
-    description = "RDS postgres subnet group for the ${ var.in_ecosystem_name } database."
+    name_prefix = "db-${ var.in_ecosystem }"
+    description = "RDS postgres subnet group for the ${ var.in_ecosystem } database."
     subnet_ids  = var.in_db_subnet_ids
     tags        = merge( local.subnet_group_tags, var.in_mandated_tags )
 }
@@ -169,21 +169,21 @@ resource random_string username_suffix {
 locals {
 
     subnet_group_tags = {
-        Name   = "db-subnet-group-${ var.in_ecosystem_name }-${ var.in_tag_timestamp }"
-        Desc   = "This RDS postgres database subnet group for ${ var.in_ecosystem_name } ${ var.in_tag_description }"
+        Name   = "db-subnet-group-${ var.in_ecosystem }-${ var.in_timestamp }"
+        Desc   = "This RDS postgres database subnet group for ${ var.in_ecosystem } ${ var.in_description }"
     }
 
     database_tags = {
         Name  = var.in_database_name
-        Id    = "${ var.in_database_name }-${ var.in_ecosystem_name }-${ var.in_tag_timestamp }"
+        Id    = "${ var.in_database_name }-${ var.in_ecosystem }-${ var.in_timestamp }"
     }
 
     cloned_database_tags = {
-        Desc   = "This PostgreSQL database named ${ var.in_database_name } was cloned from snapshot ${ data.aws_db_snapshot.from[0].id } and ${ var.in_tag_description }"
+        Desc   = "This PostgreSQL database named ${ var.in_database_name } was cloned from snapshot ${ data.aws_db_snapshot.from[0].id } and ${ var.in_description }"
     }
 
     fresh_database_tags = {
-        Desc  = "This brand new PostgreSQL database named ${ var.in_database_name } ${ var.in_tag_description }"
+        Desc  = "This brand new PostgreSQL database named ${ var.in_database_name } ${ var.in_description }"
     }
 
 }
diff --git a/rds.postgres-outputs.tf b/rds.postgres-outputs.tf
@@ -1,20 +1,25 @@
 
-/*
- | --
- | -- ---------------------------------- --
- | -- Created or Cloned Database Outputs --
- | -- ---------------------------------- --
- | --
- | -- These are the postgres database output variables.
- | -- The database username and password are not involved here
- | -- because they are consumed ( as opposed to produced ).
- | --
-*/
-output out_fresh_db_hostname { value = length( aws_db_instance.fresh ) == 0 ? "n/a" : aws_db_instance.fresh[0].address  }
-output out_fresh_db_endpoint { value = length( aws_db_instance.fresh ) == 0 ? "n/a" : aws_db_instance.fresh[0].endpoint }
+output out_database_username {
+    value = local.db_username
+}
 
-output out_clone_db_hostname { value = length( aws_db_instance.clone ) == 0 ? "n/a" : aws_db_instance.clone[0].address  }
-output out_clone_db_endpoint { value = length( aws_db_instance.clone ) == 0 ? "n/a" : aws_db_instance.clone[0].endpoint }
+output out_database_password {
+    value = random_string.dbpassword.result
+}
+
+output out_fresh_db_hostname {
+    value = length( aws_db_instance.fresh ) == 0 ? "n/a" : aws_db_instance.fresh[0].address
+}
+
+output out_fresh_db_endpoint {
+    value = length( aws_db_instance.fresh ) == 0 ? "n/a" : aws_db_instance.fresh[0].endpoint
+}
+
+output out_clone_db_hostname {
+    value = length( aws_db_instance.clone ) == 0 ? "n/a" : aws_db_instance.clone[0].address
+}
+
+output out_clone_db_endpoint {
+    value = length( aws_db_instance.clone ) == 0 ? "n/a" : aws_db_instance.clone[0].endpoint
+}
 
-output out_database_username { value = local.db_username }
-output out_database_password { value = random_string.dbpassword.result }
diff --git a/rds.postgres-variables.tf b/rds.postgres-variables.tf
@@ -3,15 +3,18 @@ variable in_security_group_id {
     description = "The ID of the security group protecting the database."
 }
 
+
 variable in_db_subnet_ids {
     type = "list"
     description = "The subnet ids in which the multi-availability zone db resides."
 }
 
+
 variable in_database_name {
-    description = "The database name remembering that a different name creates another database."
+    description = "Alphanumeric only database name starting with a letter and a max length of 32."
 }
 
+
 variable in_clone_snapshot {
     description = "The newly Created database will be a clone from a snapshot if set to true."
     default = false
@@ -35,30 +38,30 @@ variable in_mandated_tags {
 
 
 ### ################# ###
-### in_ecosystem_name ###
+### in_ecosystem ###
 ### ################# ###
 
-variable in_ecosystem_name {
+variable in_ecosystem {
 
     description = "Creational stamp binding all infrastructure components created on behalf of this ecosystem instance."
 }
 
 
 ### ################ ###
-### in_tag_timestamp ###
+### in_timestamp ###
 ### ################ ###
 
-variable in_tag_timestamp {
+variable in_timestamp {
 
     description = "A timestamp for resource tags in the format ymmdd-hhmm like 80911-1435"
 }
 
 
 ### ################## ###
-### in_tag_description ###
+### in_description ###
 ### ################## ###
 
-variable in_tag_description {
+variable in_description {
 
     description = "Ubiquitous note detailing who, when, where and why for every infrastructure component."
 }
