From 2913cea2b856d5483037cde3f08b6e3ae8465cab Mon Sep 17 00:00:00 2001 From: Oliver Schoenborn Date: Thu, 25 Mar 2021 13:42:20 -0400 Subject: [PATCH] Clarify docs: map and destroy --- .idea/workspace.xml | 17 ++++++-- examples/simple/README.md | 81 ++++++++++++++++++++++++++++++++------- 2 files changed, 82 insertions(+), 16 deletions(-) diff --git a/.idea/workspace.xml b/.idea/workspace.xml index 8a5afd4..bde34d4 100644 --- a/.idea/workspace.xml +++ b/.idea/workspace.xml @@ -1,7 +1,11 @@ - + + + + + @@ -55,7 +59,7 @@ diff --git a/examples/simple/README.md b/examples/simple/README.md index 8e5974a..c5419d9 100644 --- a/examples/simple/README.md +++ b/examples/simple/README.md @@ -1,18 +1,44 @@ This example demonstrates a basic usage of this module. -On a system, you have a root module tfstate-s3-manager which -includes terraform-aws-multi-stack-backends, and the main.tf -defines the stacks to manage: - -- there are 2 stacks, each with 2 root modules, so a total of - 4 folders -- the structure of the folder is irrelevant, as they are - specified by path so wherever they are located on the local - system, is where terraform-aws-multi-stack-backends will - look for them - -First you `terraform apply` each root module of each stack. -The order does not matter. +On your system, + +- you have a root module tfstate-s3-manager which +includes terraform-aws-multi-stack-backends +- you have (in this example) 4 root modules, each in their own folder +- two of those root modules belong to one stack, the other two belong + to the other stack +- the `tfstate-s3-manager/main.tf` defines the stacks to manage: + ```hcl + stacks_map = { + stack-1 = { + network = { + path = "../stack1-network" + } + cluster = { + path = "../stack1-cluster" + } + }, + stack-2 = { + network = { + path = "../stack2-network" + } + cluster = { + path = "../stack2-cluster" + } + }, + } + ``` +- the names are arbitrary (stack-1, network, etc) + +See the left green box in following diagram: + +![Root modules on local filesystem (left green box)](stack-backends-setup.png) + +### Step 1 + +Assume you have already run `terraform apply` in each root +module of each stack. The order does not matter. This step +can be done after step 2 as well. Then `terraform apply` in the `tfstate-s3-manager` root module, which will create the common bucket, its replica, dynamodb @@ -22,12 +48,16 @@ in the `main.tf`). See the following diagram. ![Step 1: setup common bucket and stack backend files](stack-backends-setup.png) +### Step 2 + Then you should (although this is optional) move the `tfstate-s3-manager` tfstate to s3, by running `terraform init` for that root module. This can be done before or after step 3. ![Step 2: move manager state to s3](move-manager-to-s3.png) +### Step 3 + Finally you can go to each stack's root module's and `terraform init`. This will move each stack's root module's tfstate from local host to s3, using the `backend.tf` generated by the @@ -35,8 +65,33 @@ local host to s3, using the `backend.tf` generated by the ![Step 3: move stack states to s3](move-stacks-to-s3.png) +### Subsequently + From then on, whenever you `terraform apply` in one of the root modules associated with a stack, the *whole stack* will get locked. See the following diagram. ![Stack state locking in s3](stack-state-locking.png) + +To delete a root module from a stack, if the stack has other +root modules in main.tf + +- `terraform destroy` for the root module you no longer need +- edit the `tfstate-s3-manager/main.tf` by removing the entry; + ATTENTION: if there are no modules left for that stack in main.tf, + *leave the stack's empty map* so that the dynamodb table does not + get destroyed yet, eg + ```hcl + stacks_map = { + stack-3 = {}, // no longer needed + } + ``` +- depending on your situation: + + - just delete the module folder, OR + - `terraform apply` to remove the corresponding `backend.tf` then + `terraform init` + +Once a stack's module have all been removed, you can delete the empty +stack map from stacks_map, and `terraform apply` to remove the dynamodb +table for that stack. \ No newline at end of file