Update documentation (#70)

Author: kurtismash

README.md

@@ -3,20 +3,21 @@
 An open-source Terraform module to deploy and orchestrate AWS Backup for creating fully immutable backups within an AWS Organization.
 
 - Manages the deployment of Backup Vaults to member accounts using CloudFormation StackSets.
+- Allows for targetted deployments to specific Organizations Units (OUs) and prevents cross-talk between deployments.
 - Stores backups in a central AWS account to protect against account closure or suspension.
-- Protection against KMS Key deletion through using AWS Managed and AWS Owned keys.
-- Support for Logically Air Gapped Vaults, with logic to use them only for supported resource types.
+- Protects against KMS Key deletion through using AWS Managed and AWS Owned keys.
+- Supports Logically Air Gapped Vaults, with logic to use them only for supported resource types.
 - (Optional) Resource selection using tags.
-- Implements AWS best practices and guidance for security and cost.
-- Simplifies the process of configuring AWS Backup plans.
+- Implements AWS best practice and guidance for security and cost.
+- Simplifies the process of configuring AWS Backup.
 
-See [Why use this module?](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/why-use-this-module/) in our docs to understand the issues this module solves and how it works.
+See [Why use this module?](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/why-use-this-module/) to learn more about the issues this module solves and how it works.
 
 ## Architecture and deployment
 
-The module is designed to be deployed in a dedicated account within an AWS Organization, this account must be [delegated certain abilities for the module to function](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/usage/). Go to our [Architecture](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/architecture/) documentation for a more detailed explanation of the architecture and how the module works.
+The module is designed to be deployed in a dedicated account within an AWS Organization, this account must be [delegated certain abilities for the module to function](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/usage/). See our [Architecture](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/architecture/) documentation for a detailed explanation of the architecture and how the module works.
 
-![Architecture Diagram](https://raw.githubusercontent.com/nationalarchives/terraform-aws-immutable-aws-backup/refs/heads/main/docs/assets/images/backup-architecture.png)
+![Architecture Diagram](https://raw.githubusercontent.com/nationalarchives/terraform-aws-immutable-aws-backup/refs/heads/main/docs/assets/images/backup-deployment-architecture.png)
 
 ## Example Usage
 
@@ -27,11 +28,10 @@ module "immutable_aws_backup" {
 
   central_account_resource_name_prefix = "immutable-aws-backup-"
   member_account_resource_name_prefix  = "orgdeploy-immutable-aws-backup-"
-  terraform_state_bucket_name          = "my-terraform-state-bucket"
 
   deployments = {
     "website-service" = {
-      backup_targets     = ["ou-abcd-defghijk"]
+      targets            = ["ou-abcd-defghijk"]
       min_retention_days = 7
       max_retention_days = 90
       backup_tag_key     = "BackupPlan"
@@ -42,17 +42,17 @@ module "immutable_aws_backup" {
           rules = [
             {
               name                = "daily",
-              schedule_expression = "cron(0 3 ? * * *)"
+              schedule_expression = "cron(0 3 ? * * *)" # Every day at 3am UTC
               delete_after_days   = 7
             },
             {
               name                = "weekly",
-              schedule_expression = "cron(0 3 ? * 2 *)"
+              schedule_expression = "cron(0 3 ? * 2 *)" # Every Monday at 3am UTC
               delete_after_days   = 28
             },
             {
               name                = "monthly",
-              schedule_expression = "cron(0 3 1 * ? *)"
+              schedule_expression = "cron(0 3 1 * ? *)" # Every 1st of the month at 3am UTC
               delete_after_days   = 90
             }
           ]

docs/architecture.md

@@ -1,37 +1,40 @@
 # Module Architecture
 
-The module is designed to be deployed in a dedicated account within an AWS Organization, this account [must be delegated certain abilities for the module to function](usage.md).
+The module is designed to be deployed in a dedicated account within an AWS Organization, this account [must be delegated certain abilities for the module to function](usage-prerequisites.md).
 
-![An AWS architecture diagram showing the module architecture. There are 2 AWS accounts, the Backup delegate account and the Workload accounts (of which there could be multiple). In the Backup delegate account are 3 Backup Vaults - LAG Vault, Intermediate Standard Vault, and Standard Vault -  there is also an EventBridge Event Bus. In the Workload account are resources to be backed up, these have an arrow directing backups in a Standard Vault within this account. From the Workload account's Standard Vault an arrow goes to the LAG and Intermediate Standard Vaults in the other account. The Intermediate Standard Vault then has an arrow to the Standard Vault in the Backup delegate account with a Step Function over it. An Event Bridge rule for Backup events in the Workload account forwards these to the Event Bus in the Backup delegate account.](assets/images/backup-architecture.png)
+One call of this module can deploy multiple instances of AWS Backup, each with a different configuration and to different Organizational Units; we call each of these a "deployment". Deployments act as a **security boundary** between instances; accounts targetted by one deployment cannot influence the backups of another deployment. The diagram below shows the architecture of a single deployment.
 
-## Deployment to member accounts
+![An AWS architecture diagram showing the architecture of a deployment. There are 2 AWS accounts, the Backup delegate account and the Workload accounts (of which there could be multiple). In the Backup delegate account are 3 Backup Vaults - LAG Vault, Intermediate Standard Vault, and Standard Vault -  there is also an EventBridge Event Bus. In the Workload account are resources to be backed up, these have an arrow directing backups in a Standard Vault within this account. From the Workload account's Standard Vault an arrow goes to the LAG and Intermediate Standard Vaults in the other account. The Intermediate Standard Vault then has an arrow to the Standard Vault in the Backup delegate account with a Step Function over it. An Event Bridge rule for Backup events in the Workload account forwards these to the Event Bus in the Backup delegate account.](assets/images/backup-deployment-architecture.png)
 
-Deployment to member accounts is orchestrated through [CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html). The module uses CloudFormation as it enables deployment to many AWS accounts without the need to configure and manage a Terraform provider for each account. StackSets work natively within AWS, reacting when accounts are moved between Organizations and Organizational Units to provision and destroy resources depending on their location within an Organization.
+Each deployment orchestrates the creation of resources in both the Backup account and the Workload accounts. Resources created in the Backup account are:
 
-However, as CloudFormation is a declarative syntax for provisioning resources, even more so than Terraform, some of the member account deployment functionality has been implemented through [custom resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html) - AWS Lambda calling the AWS API or running Terraform itself. For example, creating the AWS Backup Service-linked IAM Role will only succeed if this role doesn't already exist; by using a custom Lambda function this error can be caught and ignored. Terraform is used to deploy the Backup Vaults within member accounts as it includes a `force_destroy` option that will empty a Vault before deleting it, whereas CloudFormation would fail to delete a Vault with contents.
+- 3x Backup Vaults - a Logically Air Gapped (LAG) Vault, an Intermediate Standard Vault, and a Standard Vault.
+- An IAM Service Role for AWS Backup.
+- An EventBridge Event Bus to receive AWS Backup events from the Workload accounts.
+- An EventBridge Rule to forward AWS Backup events from the default bus to the deployment's Event Bus.
+- A Step Function to copy backups from the Intermediate Standard Vault to the Standard Vault and update the lifecycle of backups that have been copied.
+- A CloudFormation StackSet to deploy resources in the workload accounts.
+- A KMS Customer Managed Key to encrypt backups in the Intermediate Vault and workload account vaults.
+- A Resource Access Manager (RAM) Share to share the Logically Air Gapped (LAG) Vault with the Workload accounts for recovery.
+- A Step Function to manage the copying of backups from the Standard Vault back to workload accounts for recovery.
 
-![An AWS architecture diagram showing how Cloudformation and Lambda are used to deploy resources, has 6 steps. 1. The Organization Management Account delegates the Backup Delegate Account CloudFormation StackSet administration abilities. 2. The Backup Delegate Account creates a StackSet. 3. The StackSet creates Stacks in Workload accounts. 4. Cloudformation within the workload accounts publishes a message to an SNS topic in the Backup Delegate Account. 5. The Deployment Helper Lambda is invoked by SNS. 6. The Deployment Helper Lambda deploys resources into the Workload account.](assets/images/deployment-helper-lambda-architecture.png)
+## Resources in workload accounts
 
-## Central account resources
+Each deployment orchestrates the creation of resources in workload accounts through [CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html). The module uses CloudFormation as it enables deployment to many AWS accounts without the need to configure and manage a Terraform provider for each account. StackSets work natively within AWS, reacting when accounts are moved between Organizations and Organizational Units to provision and destroy resources depending on their location within an Organization.
 
-- Deployment helper SNS topic
-- Deployment helper Lambda function
-- AWS Backup Service-linked IAM Role
-- S3 Terraform state bucket for deployments to workload accounts
+However, as CloudFormation is a declarative syntax for provisioning resources, even more so than Terraform, some of the workload account deployment functionality has been implemented through [custom resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html) - an AWS Lambda calling the AWS API or running Terraform itself. For example, creating the AWS Backup Service-linked IAM Role will only succeed if this role doesn't already exist; by using a custom Lambda function this error can be caught and ignored. Terraform is used to deploy the Backup Vaults within workload accounts as it includes a `force_destroy` option that will empty a Vault before deleting it, whereas CloudFormation would fail to delete a Vault with content.
 
-## Central account resources per deployment
+![An AWS architecture diagram showing how CloudFormation and Lambda are used to deploy resources, has 6 steps. 1. The Organization Management Account delegates the Backup Delegate Account CloudFormation StackSet administration abilities. 2. Terraform running in the Backup Delegate Account creates a StackSet. 3. The StackSet creates Stacks in workload accounts. 4. Cloudformation within the workload accounts publishes a message to an SNS topic in the Backup Delegate Account. 5. The Deployment Helper Lambda is invoked by SNS. 6. The Deployment Helper Lambda deploys resources into the Workload account.](assets/images/deployment-helper-lambda-architecture.png)
 
-- EventBridge Event Bus
-- Backup Ingest Step Function
-- Intermediate Backup Vault
-- Standard Backup Vault
-- LAG Backup Vault
-- AWS Backup Service Role
-- KMS Customer Managed Key
-- CloudFormation StackSet
-- Resource Access Manager (RAM) share
+The "Deployment Helper" Lambda Function is deployed once in the dedicated Backup account. It is invoked by an SNS topic in the Backup account which recieves messages from CloudFormation stacks within the workload accounts. The Lambda function then deploys resources into the workload accounts. The resources created to support this are:
+
+- An SNS topic to receive messages from CloudFormation stacks in workload accounts.
+- An S3 Terraform state bucket, if not passed in as a variable.
+- A Lambda function to deploy resources in workload accounts.
+- An execution IAM Role for the Lambda Function.
+- A CloudWatch Log Group for the Lambda Function.
 
-## Member account resources
+Within each workload account, for each deployment, the following resources are created:
 
 - Backup Vault
 - Restore Vault

docs/assets/images/backup-architecture.png renamed to docs/assets/images/backup-deployment-architecture.png

@@ -3,20 +3,21 @@
 An open-source Terraform module to deploy and orchestrate AWS Backup for creating fully immutable backups within an AWS Organization.
 
 - Manages the deployment of Backup Vaults to member accounts using CloudFormation StackSets.
+- Allows for targetted deployments to specific Organizations Units (OUs) and prevents cross-talk between deployments.
 - Stores backups in a central AWS account to protect against account closure or suspension.
-- Protection against KMS Key deletion through using AWS Managed and AWS Owned keys.
-- Support for Logically Air Gapped Vaults, with logic to use them only for supported resource types.
+- Protects against KMS Key deletion through using AWS Managed and AWS Owned keys.
+- Supports Logically Air Gapped Vaults, with logic to use them only for supported resource types.
 - (Optional) Resource selection using tags.
-- Implements AWS best practices and guidance for security and cost.
-- Simplifies the process of configuring AWS Backup plans.
+- Implements AWS best practice and guidance for security and cost.
+- Simplifies the process of configuring AWS Backup.
 
-See [Why use this module?](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/why-use-this-module/) in our docs to understand the issues this module solves and how it works.
+See [Why use this module?](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/why-use-this-module/) to learn more about the issues this module solves and how it works.
 
 ## Architecture and deployment
 
-The module is designed to be deployed in a dedicated account within an AWS Organization, this account must be [delegated certain abilities for the module to function](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/usage/). Go to our [Architecture](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/architecture/) documentation for a more detailed explanation of the architecture and how the module works.
+The module is designed to be deployed in a dedicated account within an AWS Organization, this account must be [delegated certain abilities for the module to function](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/usage/). See our [Architecture](https://nationalarchives.github.io/terraform-aws-immutable-aws-backup/architecture/) documentation for a detailed explanation of the architecture and how the module works.
 
-![Architecture Diagram](https://raw.githubusercontent.com/nationalarchives/terraform-aws-immutable-aws-backup/refs/heads/main/docs/assets/images/backup-architecture.png)
+![Architecture Diagram](https://raw.githubusercontent.com/nationalarchives/terraform-aws-immutable-aws-backup/refs/heads/main/docs/assets/images/backup-deployment-architecture.png)
 
 ## Example Usage
 
@@ -30,7 +31,7 @@ module "immutable_aws_backup" {
 
   deployments = {
     "website-service" = {
-      backup_targets     = ["ou-abcd-defghijk"]
+      targets            = ["ou-abcd-defghijk"]
       min_retention_days = 7
       max_retention_days = 90
       backup_tag_key     = "BackupPlan"
@@ -41,17 +42,17 @@ module "immutable_aws_backup" {
           rules = [
             {
               name                = "daily",
-              schedule_expression = "cron(0 3 ? * * *)"
+              schedule_expression = "cron(0 3 ? * * *)" # Every day at 3am UTC
               delete_after_days   = 7
             },
             {
               name                = "weekly",
-              schedule_expression = "cron(0 3 ? * 2 *)"
+              schedule_expression = "cron(0 3 ? * 2 *)" # Every Monday at 3am UTC
               delete_after_days   = 28
             },
             {
               name                = "monthly",
-              schedule_expression = "cron(0 3 1 * ? *)"
+              schedule_expression = "cron(0 3 1 * ? *)" # Every 1st of the month at 3am UTC
               delete_after_days   = 90
             }
           ]