Merge pull request #45 from Crown-Commercial-Service/GMBP-320-general…

…-documentation

Gmbp 320 general documentation

README.md

@@ -12,13 +12,44 @@ It's intended to be used as a Git submodule within consuming projects. For examp
 git submodule add [email protected]:Crown-Commercial-Service/ccs-migration-alpha-tools.git infrastructure/core
 ```
 
+## Purpose
+
+There are two primary purposes for collecting these elements together in a shared repository:
+
+1. To provide a unified toolset across CCS deployments, and to reap the rewards that brings:
+    * Predictable behaviours
+    * Familiarity for engineers
+2. Enforce an implementation-led architecture rather than a resource-led architecture
+
+That second point is crucial in managing complex infrastructure through the use of code. Consider the following two ways of approaching this:
+
+### 1. Resource-led architecture
+
+* Characterised by decisions such as "we need CloudWatch logs. Let's create a `cloudwatch-logs.tf` file and declare all our Log Groups in there for the whole system"
+* Individual `.tf` files become change bottlenecks and merge conflict hotspots as the codebase evolves or the team grows in size
+* It becomes necessary to pass down a large number of references / variables into business-function-related modules, effective reversing the authority and creating interlocked dependencies between layers of the Terraform
+
+### 2. Implementation-led architecture
+
+* Top-level blocks describing a composed system (e.g. `compositions/full-application/`)
+* Files within the above folder declaring the need for business-purpose components using common modules which declare (for example):
+    * Multi-layer VPCs
+    * ECS Tasks
+    * S3 Buckets
+* These common modules declare their own usual sub-resources, for example:
+    * CloudWatch Log Groups
+    * JSON documents describing IAM policies to allow common operations on the resources
+
+By composing the architecture is such a top-down fashion, the declaration for many resources (for example, the Log Groups in the case of [the previous "Resource-led" example](#1-resource-led-architecture)) are declared "for free" and do not clutter up the IAC codebase for the project which imported this submodule.
+
 ## Structure
 
 The following folders are in this repo:
 
 * [validation](validation/README.md) - TF files to exercise the resource definitions held within. Even though this is an alpha, some degree of syntax / correctness checking would seem prudent.
 * [resource-groups](resource-groups/README.md) - Common groupings of AWS resources, presented to reduce repetition during normal usage (e.g. a Fargate task will likely want access to some Cloudwatch logs)
 * [modules](modules/README.md) - These are collections of resources (and resource groups) which together represent composed pieces of functionality with a specific architectural purpose
+* [scripts](scripts/README.md) - A collection of command line scripts designed to present a vaguely homogenous API for CI and Deployment tasks
 
 ## Testing
 

modules/four-tier-vpc/README.md

@@ -2,11 +2,24 @@
 
 ## Overview
 
-This module provides a standardised four-tier subnet VPC which complies with the guidelines set out in [the standards doc](https://crowncommercialservice.atlassian.net/wiki/spaces/GPaaS/pages/3561685032/AWS+3+Tier+Reference+Architecture).
+The architecture models in the original (GPaaS-migrated) services' projects were based around a classic persistent-compute model, with various Load Balancers and Service Instances waiting for requests to process.
+
+This style of structure necessitates a multi-tier network architecture. The purpose of _this_ module is to provide a standardised four-tier subnet VPC which complies with the guidelines set out in [the standards doc](https://crowncommercialservice.atlassian.net/wiki/spaces/GPaaS/pages/3561685032/AWS+3+Tier+Reference+Architecture).
+
+## General structure
+
+Each service which consumes this core IAC repo is at liberty to choose its own network topology or to adopt this module's topology (and optionally [alter the ACL rules](#network-acls-and-customisation-of)).
+
+By default this module provides four tiers of VPC:
+
+1. _public_ - Intended to hold resources which face the public internet, most likely Load Balancers of some kind
+2. _web_ - Holds resources which immediately process incoming requests shared out by the Load Balancer in the preceding tier
+3. _application_ - Compute resources which "do work" and / or service requests from the _web_ components
+4. _database_ - Data persisting components would go in this layer
 
 ## Network ACLs, and customisation of
 
-The module enforces a basic Network ACL to each subnet as per recommendations outlined in the above doc. In general these will be compatible with many apps' requirements but there will of course be a need to customise the rules for specific cases. The need to customise may be triggered by such requirements as (for example):
+The module enforces a basic Network ACL to each subnet as per recommendations outlined in [the standards doc](https://crowncommercialservice.atlassian.net/wiki/spaces/GPaaS/pages/3561685032/AWS+3+Tier+Reference+Architecture). In general these will be compatible with many apps' requirements but there will of course be a need to customise the rules for specific cases. The need to customise may be triggered by such requirements as (for example):
 
 * A service in a web subnet requires direct database access, thus needing to "leap-frog" the application subnets
 * An app adds an EFS volume and needs to allow cross-subnet traffic on the NFS port