streamlining the module documentation and upgrading the example

Author: apolloakora

README.md

@@ -30,15 +30,12 @@ The subnets are dished out across availability zones in a round robin fashion. Y
 The most common use case is to specify the VPC Cidr, the number of public and private subnets.
 
 
-## Run the Examples | VPC Network
-
-You can test-drive this VPC and su
-
+---
 
-## [Examples and Tests](test-vpc.network)
 
-**[This terraform module has runnable example integration tests](test-vpc.network)**. Read the instructions on how to clone the project and run the integration tests.
+## [Run the Example](https://github.com/devops4me/terraform-aws-vpc-network/tree/master/example)
 
+You can run the example to see this module create a number of VPCs with varying attributes such as the number of private/public subnets.
 
 ## Module Inputs
 
@@ -48,9 +45,13 @@ You can test-drive this VPC and su
 | **in_num_private_subnets** | Integer | Number of private subnets to create across availability zones | 3              |
 | **in_num_public_subnets**  | Integer | Number of public subnets to create across availability zones. If one or more an internet gateway and route to the internet will be created regardless of the value of the in_create_gateway boolean variable. | 3 |
 | **in_create_gateway**      | Boolean | If set to true an internet gateway and route will be created even when no public subnets are requested. | false |
-| **in_subnets_max**         | Integer | 2 to the power of this is the max number of carvable subnets  | 4 (16 subnets) |
+| **[in_subnets_max](https://www.devopswiki.co.uk/vpc/network-cidr)**         | Integer | 2 to the power of this is the max number of carvable subnets  | 4 (16 subnets) |
 | **in_ecosystem**           | String  | the class name of the ecosystem being built here              | eco-system     |
 
+
+---
+
+
 ## subnets into availability zones | round robin
 
 You can create **more or less subnets** than there are availability zones in the VPC's region. You can ask for **6 private subnets** in a **3 availability zone region**. The subnets are distributed into the availability zones like dealing a deck of cards.
@@ -62,51 +63,9 @@ Every permutation of subnets and availability zones is catered for so you can de
 - that **no subnets** (public and/or private) get created
 - nothing - and each availability zone will get one public and one private subnet
 
----
-
-## in_subnets_max | variable
-
-This variable defines the maximum number of subnets that can be carved out of your VPC (you do not need to use them all). It then combines with the VPC Cidr to define the number of **addresses available in each subnet's** pool.
-
-### 2<sup>32 - (in_vpc_cidr + in_subnets_max)</sup> = number of subnet addresses
-
-A **vpc_cidr of 21 (eg 10.42.0.0/21)** and **subnets_max of 5** gives a pool of **2<sup>32-(21+5)</sup> = 64 addresses** in each subnet. (Note it is actually 2 less). We can carve out **2<sup>5</sup> = 32 subnets** as in_subnets_max is 5.
-
-### Dividing VPC Addresses into Subnet Blocks
-
-| vpc cidr  | subnets max | number of addresses per subnet                          | max subnets                 | vpc addresses total                  |
-|:---------:|:-----------:|:------------------------------------------------------- |:--------------------------- |:------------------------------------ |
-|  /16      |   6         | 2<sup>32-(16+6)</sup> = 2<sup>10</sup> = 1024 addresses | 2<sup>6</sup> = 64 subnets  | 2<sup>32-16</sup> = 65,536 addresses |
-|  /16      |   4         | 2<sup>32-(16+4)</sup> = 2<sup>12</sup> = 4096 addresses | 2<sup>4</sup> = 16 subnets  | 2<sup>32-16</sup> = 65,536 addresses |
-|  /20      |   8         | 2<sup>32-(20+8)</sup> = 2<sup>4</sup>  = 16 addresses   | 2<sup>8</sup> = 256 subnets | 2<sup>32-20</sup> = 4,096 addresses  |
-|  /20      |   2         | 2<sup>32-(20+2)</sup> = 2<sup>10</sup> = 1024 addresses | 2<sup>2</sup> = 4 subnets   | 2<sup>32-20</sup> = 4,096 addresses  |
-
-Check the below formula holds true for every row in the above table.
-
-<pre><code>addresses per subnet * number of subnets = total available VPC addresses</code></pre>
 
 ---
 
-## in_subnets_max | in_vpc_cidr
-
-**How many addresses will each subnet contain** and **how many subnets can be carved out of the VPC's IP address pool**? These questions are answered by the vpc_cidr and the subnets_max variable.
-
-The VPC Cidr default is 16 giving 65,536 total addresses and the subnets max default is 4 so **16 subnets** can be carved out with each subnet ready to issue 4,096 addresses.
-
-Clearly the addresses per subnet multiplied by the number of subnets cannot exceed the available VPC address pool. To keep your powder dry, ensure **in_vpc_cidr plus in_subnets_max does not exceed 31**.
-
-## number of subnets constraint
-
-It is unlikely **in_num_private_subnets + in_num_public_subnets** will exceed the maximum number of subnets that can be carved out of the VPC. Usually it is a lot less but be prudent and ensure that **in_num_private_subnets + in_num_public_subnets < 2<sup>in_subnets_max</sup>**
-
-
-## subnet cidr blocks | cidrsubnet function
-
-You do not need to specify each subnet's CIDR block because they are calculated by passing the VPC Cidr (in_vpc_cidr), the Subnets Max (in_subnets_max) and the present subnet's index (count.index) into Terraform's **cidrsubnet function**.
-
-The behaviour of Terraform's **cidrsubnet function** is involved but slightly outside the scope of this VPC/Subnet module document. Read **[Understanding the Terraform Cidr Subnet Function](http://www.devopswiki.co.uk/wiki/devops/terraform/terraform-cidrsubnet-function)** for a fuller coverage of cidrsubnet's behaviour.
-
----
 
 ## internet gateway and route
 
@@ -115,6 +74,9 @@ This module **senses** whether you wish to **create an internet gateway** (in) a
 If **in_num_public_subnets is greater than zero** it automatically creates an internet gateway and a route along with the public subnets. This behaviour can be switched off by setting **in_ignore_public** to true.
 
 
+---
+
+
 ## output variables
 
 Here are the most popular **output variables** exported from this VPC and subnet creating module.
@@ -126,81 +88,3 @@ Here are the most popular **output variables** exported from this VPC and subnet
 **out_subnet_ids** | List of Strings | [ "subnet-545123498798345", "subnet-83507325124987" ] | list of **all private and public** subnet ids
 **out_private_subnet_ids** | List of Strings | [ "subnet-545123498798345", "subnet-83507325124987" ] | list of **private** subnet ids
 **out_public_subnet_ids** | List of Strings |  [ "subnet-945873408204034", "subnet-8940202943031" ] | list of **public** subnet ids
-
-## vpc subnets | module tests
-
-**[This terraform module has runnable example integration tests](test-vpc.network)**. Read the instructions on how to clone the project and run the unit tests.
-
-## vpc subnets | version | v0.1.0002
-
-**v0.1.0002** is the current stable version of this Terraform module. To avoid say **testing with one version and going into production with another** you can employ the ref tag as shown below.
-
-    module vpc-network
-    {
-        source                 = "github.com/devops4me/terraform-aws-vpc-network?ref=v0.1.0002"
-        in_vpc_cidr            = "10.245.0.0/16"
-        in_num_private_subnets = 6
-        in_num_public_subnets  = 3
-        in_ecosystem           = "kubernetes-cluster"
-    }
-
-Or you can use the version parameter that is more explicit and affords you the opportunity to detail a **[range of versions that are acceptable](https://www.terraform.io/docs/modules/usage.html)** by employing **version constraint syntax**.
-
-    module vpc-network
-    {
-        source       = "github.com/devops4me/terraform-aws-vpc-network"
-        version      =  "~> v0.1.0"
-        in_vpc_cidr  = "10.123.0.0/16"
-        in_ecosystem = "kubernetes-cluster"
-    }
-
-
-## Infrastructure Tests | Dockerfile
-
-The quality and viability of this Terraform module is assured via a continuous integration process.
-
-### See 4 Yourself | docker run
-
-Why not see 4 yourself by building and running the test. You simply pass in **[[IAM user credentials]](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html)** as **environment variables** to the docker container and Terraform will use these credentials to create the infrastructure.
-
-```bash
-git clone https://github.com/devops4me/terraform-aws-vpc-network
-cd terraform-aws-vpc-network
-docker build -t vpc.network.image .
-```
-
-### The AWS 5 VPC's Limit
-
-The default VPC limit is just 5 and this test needs at least 10 so take yourself to the support section and request extension to say 25 - it will be done automatically in less than 5 minutes.
-
-## Test Automation | Jenkinsfile
-
-
-### Contributing
-
-Bug reports and pull requests are welcome on GitHub at the https://github.com/devops4me/terraform-aws-vpc-network 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.
-
-License
--------
-
-MIT License
-Copyright (c) 2006 - 2014
-
-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:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-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.

example/Dockerfile

@@ -1,37 +1,4 @@
-
-# --->
-# ---> Going with Ubuntu's Long Term Support (lts)
-# ---> version which is currently 18.04.
-# --->
-
-FROM ubuntu:18.04
-
-
-# --->
-# ---> Assume the root user and install git, terraform,
-# ---> a time zone manipulator and pythonic tools for
-# ---> testing the AWS based infrastructure.
-# --->
-
-USER root
-
-RUN apt-get update && apt-get --assume-yes install -qq -o=Dpkg::Use-Pty=0 \
-      curl  \
-      git   \
-      unzip
-
-
-# --->
-# ---> Install the Terraform binary.
-# --->
-
-RUN \
-    curl -o /tmp/terraform.zip https://releases.hashicorp.com/terraform/0.12.8/terraform_0.12.8_linux_amd64.zip && \
-    unzip /tmp/terraform.zip -d /usr/local/bin && \
-    chmod a+x /usr/local/bin/terraform         && \
-    rm /tmp/terraform.zip                      && \
-    terraform --version
-
-
-USER ubuntu
-WORKDIR /home/ubuntu
+FROM hashicorp/terraform:light
+RUN mkdir -p /terraform-work
+WORKDIR /terraform-work
+VOLUME /terraform-work

example/README.md

@@ -1,19 +1,42 @@
 
-# Example | Creating a VPC Network
+# Example | Create an AWS VPC Network
 
 This example creates a VPC, subnets and the networking backbone to allow traffic to be routed in and also routed out to service endpoints on the internet. Let's first use docker then do the same thing with terraform installed on your machine.
 
 
 ## Docker | Create VPC Networks
 
-With docker, you need not worry about which Terraform version is installed on your machine. All you need is docker and your AWS access credentials.
+With docker, you need not worry about which Terraform version is installed on your machine. All you need are your AWS access credentials.
+
 
 ```
-```
+docker build --rm --no-cache --tag devops4me/vpc-network .
+
+### This Actually Works (But the next problem is - CAN WE DESTROY)
+### ALSO this prompts  - we need to add -auto-approve to the docker file
+docker run -i -e AWS_DEFAULT_REGION=eu-west-1 -e AWS_ACCESS_KEY_ID=XXXXXXXXXXXXX -e AWS_SECRET_ACCESS_KEY=XXXXXXX -e TF_VAR_in_role_arn=ZZZZZZZZZZZZ  -t devops4me/vpc-network apply
+
+
+
+
+
+
+docker run -i -t devops4me/vpc-network \
+    --env AWS_DEFAULT_REGION=eu-west-1 apply
+
 
-This **[Jenkinsfile](example/Jenkinsfile)** is used to continuously integrate this module thus guaranteeing correctness and reusability. Ensure you pin the (semantic) version of this module to avoid breaking change failures as it evolves both its functionality and keeps up with Terraform's rapid developmental pace.
 
-For even more peace of mind you can clone this project and use your own continuous integration facilities. Send a pull request for any changes that will benefit the Terraform community.
+git clone github.com/devops4me/terraform-aws-vpc-network
+cd terraform-aws-vpc-network/example
+docker build --rm --no-cache --tag devops4me/vpc-network .
+docker images
+docker run         \
+    --detach       \
+    --name vm.vpc  \
+    --network host \
+    --volume ${PWD}:/home/ubuntu \
+    devops4me/vpc-network;
+```
 
 
 ## How to Run the Example
@@ -50,15 +73,7 @@ If you are using an IAM role as the AWS access mechanism then pass it as in_role
 Individuals and small businesses who don't have hundreds of AWS accounts can omit the variable and thanks to dynamic assignment the assume_role block will cease to exist.
 
 
-docker run \
-    --detach \
-    --name vm.vpc-network \
-    --network host \
-    --volume ${PWD}:/home/ubuntu \
-    postgres:11.2;
-
-
-
+### The AWS 5 VPC's Limit
 
-## Related Modules
+The default VPC limit is just 5 and this test needs at least 10 so take yourself to the support section and request extension to say 25 - it will be done automatically in less than 5 minutes.
 

example/vpc.network-example.tf

@@ -120,5 +120,5 @@ locals {
     ecosystem_name = "virtual-net"
     timestamp = formatdate( "YYMMDDhhmmss", timestamp() )
     date_time = formatdate( "EEEE, DD-MMM-YY hh:mm:ss ZZZ", timestamp() )
-    description = "was created by jenkins on ${ local.date_time }."
+    description = "was created by me on ${ local.date_time }."
 }

vpc.network-variables.tf

@@ -74,6 +74,7 @@ variable in_create_private_gateway {
 
 variable in_ecosystem {
     description = "Creational stamp binding all infrastructure components created on behalf of this ecosystem instance."
+    default = "vpc-network"
 }
 
 
@@ -83,6 +84,7 @@ variable in_ecosystem {
 
 variable in_timestamp {
     description = "A timestamp for resource tags in the format ymmdd-hhmm like 80911-1435"
+    default = local.timestamp
 }
 
 
@@ -92,6 +94,7 @@ variable in_timestamp {
 
 variable in_description {
     description = "Ubiquitous note detailing who, when, where and why for every infrastructure component."
+    default = "This VPC network was created on ${ local.date_time }."
 }