Merge pull request #165 from domain-protect/doc-updates

Documentation updates

docs/ci-cd.md

@@ -3,8 +3,9 @@
 ### Python and Terraform tests
 
 * GitHub Actions pipeline in this repository
-* see details in [manual tests](manual-tests.md)
+* see details in [Integration Tests](integration-tests.md)
 
 ### Deployment
 
-* GitHub Actions pipeline in separate [Domain Protect Deploy](https://github.com/domain-protect/terraform-aws-domain-protect-deploy) repository
+* Use the GitHub Actions pipelines [dev.yml](https://github.com/domain-protect/terraform-aws-domain-protect/blob/main/.github/workflows/dev.yml) and [prd.yml](https://github.com/domain-protect/terraform-aws-domain-protect/blob/main/.github/workflows/prd.yml) as examples
+* These deploy the [dev](https://github.com/domain-protect/terraform-aws-domain-protect/tree/main/examples/dev) and [prd](https://github.com/domain-protect/terraform-aws-domain-protect/tree/main/examples/prd) module examples respectively

docs/integration-tests.md

@@ -24,7 +24,9 @@ Deployment integration tests are set up without using Mocks, as follows:
 
 ## Running tests locally
 
-See [Automated Tests](automated-tests.md) for details on how to set up the tests locally.
+See [Automated Tests](automated-tests.md) for details on how to set up manual scan tests locally.
+
+See the Integration Tests Deployment [README](https://github.com/domain-protect/terraform-aws-domain-protect/tree/main/integration_tests/deployment) for instructions on testing and developing end-to-end tests locally.
 
 ## Creating new integration tests
 

docs/migration.md

@@ -21,7 +21,7 @@ Phased option preserving databases and avoiding downtime:
 
 * Upgrade Domain Protect using your existing deployment methodology from the [original Domain Protect repository](https://github.com/domain-protect/domain-protect) to version `0.5.1` and your current variables
 * This is pinned to use version `0.5.1` of the Terraform module
-* Create a new repository for your deployment(s), calling the Terraform module directly, which should result in no changes other than the usual Lambda rebuild
+* Create a new repository for your deployment(s), calling the Terraform module directly, which should result in no changes other than the usual Lambda rebuilds
 * See the [examples folder](https://github.com/domain-protect/terraform-aws-domain-protect/tree/main/examples) in this repository for example Terraform
 * Update the Terraform module version to the latest version, this will require some adjustment of Terraform variables:
 

examples/dev/main.tf

@@ -1,7 +1,7 @@
 module "domain_protect" {
   source = "../../"
   # source  = "domain-protect/domain-protect/aws"
-  # version = "0.5.1"
+  # version = "1.0.0"
 
   allowed_regions     = "['eu-west-1', 'eu-west-2', 'us-east-1']"
   cf_api_key          = var.cf_api_key

examples/prd/main.tf

@@ -1,7 +1,7 @@
 module "domain_protect" {
   source = "../../"
   # source  = "domain-protect/domain-protect/aws"
-  # version = "0.5.1"
+  # version = "1.0.0"
 
   allowed_regions     = "['eu-west-1', 'eu-west-2', 'us-east-1']"
   cf_api_key          = var.cf_api_key

integration_tests/deployment/README.md

@@ -0,0 +1,67 @@
+# Integration Tests - Deployment
+
+[Integration Tests](../docs/integration-tests.md) have been implemented to provide comprehensive end-to-end pipeline tests to ensure we can be confident as to whether an update has affected the system functionality.
+
+This page details the process for developing and testing deployment integration tests.
+
+## Create integration test role in Route53 test account
+
+* Create an IAM role in the Route53 test account
+* Add a trust policy for the Security Audit account, optionally with an External ID
+* Add this policy,replacing the example with your Hosted Zone ID
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "Route53write",
+            "Effect": "Allow",
+            "Action": [
+                "route53:ChangeResourceRecordSets"
+            ],
+            "Resource": "arn:aws:route53:::hostedzone/ZZZZ12345678ZZ"
+        },
+        {
+            "Sid": "Route53Read",
+            "Effect": "Allow",
+            "Action": [
+                "route53:ListHostedZonesByName"
+            ],
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+## Configure development environment
+
+* create virtual environment
+```bash
+python -m venv .venv
+```
+* activate virtual environment
+```bash
+source .venv/bin/activate
+```
+* install dependencies
+```powershell
+pip install -r requirements-tests.txt
+```
+* set environment variables for dev environment, e.g.
+```bash
+export PROJECT=domain-protect
+export ENVIRONMENT=dev
+export ROUTE53_ACCOUNT="12345678901"
+export TEST_ROLE_NAME="domain-protect-integration-test"
+export ZONE_NAME="example.com"
+export ZONE_ID="ZZZZ12345678ZZ"
+export TEST_ROLE_EXTERNAL_ID="xxxxxxxxxxxxxxxxxx"
+export AWS_REGION="eu-west-1"
+export CLOUDFLARE_ZONE_NAME="example.net"
+```
+* copy and paste AWS macOS / Linux CLI variables for the security audit account to terminal
+
+* test integration locally
+```python
+pytest -v integration_tests/deployment
+```