Updated readme to reflect use of remote state and removal of shared T…

…F templates.

README.rst

@@ -22,76 +22,69 @@ Requirements
          aws_access_key_id = ACCESS_KEY
          aws_secret_access_key = SECRET_KEY
 
-Layout
-======
-
-Resources which are shared across environments such as top-level DNS entries are managed via terraform templates in the ``shared/`` directory. Terraform templates in the root level create and manage per-environment resources.
-
 Usage
 =====
 
 Variables
 ---------
 
-Variables that are not environment-specific are stored in ``terraform.tfvars`` and ``shared/terraform.tfvars``.
+Variables that are not environment-specific are stored in ``terraform.tfvars``.
 
 Secrets
 -------
 
-Files containing secrets (currently ``terraform.tfvars`` and ``shared/terraform.tfvars``) are encrypted with GPG and managed with `BlackBox`_. Ask an admin to add your GPG key so you can decrypt.
-
-Creating/updating Shared resources
-----------------------------------
-
-Decrypt secrets::
+Secrets are stored in ``terraform.tfvars``, encrypted with GPG and managed with `BlackBox`_. Ask an admin to add your GPG key so you can decrypt.
 
-  $ blackbox_edit_start terraform.tfvars
+Shared environment state
+------------------------
 
-or::
+Env-specific state files are used to keep environments separate. Terraform's
+remote state storage is used to store Terraform state in Amazon S3, keeping environments in sync between different uses and users.
 
-  $ blackbox_decrypt_all_files
 
-To see changes to be made (if any)::
+Managing environments
+---------------------
+Decrypt secrets::
 
-  $ cd shared/
-  $ terraform plan
+  $ blackbox_edit_start terraform.tfvars
 
-To apply changes::
+or to decrypt all BlackBox-managed files::
 
-  $ cd shared/
-  $ terraform apply
+  $ blackbox_postdeploy
 
-Terraform will apply changes and output a zone ID for the main parent subdomain (``r53_notes_zone_id``), which is required input for an environment's terraform template.
+Define env::
 
-Creating/updating environment resources
----------------------------------------
-Decrypt secrets::
+  $ export ENV=dev  # or ENV=test, ENV=production, etc.
 
-  $ blackbox_edit_start terraform.tfvars
+Configure remote storage::
 
-or::
+  $ terraform remote config
+      -backend=s3 -backend-config="bucket=csd-notes-terraform" \
+      -backend-config="key=${ENV}.tfstate" -backend-config="region=eu-west-1"
 
-  $ blackbox_decrypt_all_files
+Sync local state with remote::
+  $ terraform remote pull
 
 To see changes to be made (if any)::
 
-  $ export ENV=dev  # or ENV=test, ENV=production, etc.
-  $ terraform plan -state=$ENV.tfstate -var 'environment=$ENV' \
-      -var 'rds_username=$DB_USERNAME' -var 'rds_password=$DB_PASSWORD' \
-      -var 'r53_notes_zone_id=$NOTES_ZONEID'  # from output of shared template
+  $ terraform plan -var "rds_username=${DB_USER}"
+      -var "rds_password=${DB_PASSWORD}" \
+      -var "environment=${ENV}" -var "domain_prefix=${ENV}"
 
-To apply changes::
+To create or update an environment::
 
-  $ export ENV=dev  # or ENV=test, ENV=production, etc.
-  $ terraform apply -state=$ENV.tfstate -var 'environment=$ENV' \
-      -var 'rds_username=$DB_USERNAME' -var 'rds_password=$DB_PASSWORD' \
-      -var 'r53_notes_zone_id=$NOTES_ZONEID'  # from output of shared template
+  $ terraform apply -var "rds_username=${DB_USER}"
+      -var "rds_password=${DB_PASSWORD}" \
+      -var "environment=${ENV}" -var "domain_prefix=${ENV}"
+
+To delete an environment::
 
-Variables above are required. Other optional variables are detailed in ``outputs.tf``.
+  $ terraform destroy -var "rds_username=${DB_USER}"
+      -var "rds_password=${DB_PASSWORD}" \
+      -var "environment=${ENV}" -var "domain_prefix=${ENV}"
 
-Environment state
------------------
+Variables above are required, and will generally taken from the relevant ``.env`` file in the `CSD Notes Config`_ repo.
 
-An env-specific state is specified above (``-state=$ENV.tfstate``) to keep environments separate and avoid accidentally updating the wrong environment. Terraform will generate ``.tfstate`` files on each ``plan``, ``apply`` or ``refresh`` run. These files MUST NOT be checked into source control as they will contain secrets.
 
 .. _BlackBox: https://github.com/StackExchange/blackbox
+.. _CSD Notes Config: https://github.com/crossgovernmentservices/csd-notes-config