WIP docs

Author: kurtismash

docs/architecture.md

@@ -1,6 +1,6 @@
 # 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)
 

docs/usage-backing-up-your-resources.md

@@ -0,0 +1,76 @@
+# Backing up your resources
+
+This document provides guidance on how to back up resources using this Terraform module. It will not repeat the [documentation provided by AWS Backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/creating-a-backup.html), but will instead focus on the specific requirements and configurations needed for this module to work effectively.
+
+## DynamoDB
+
+[AWS Backup advanced features for DynamoDB](https://docs.aws.amazon.com/aws-backup/latest/devguide/advanced-ddb-backup.html) must be enabled within the workload account.
+
+## KMS Encryption of resources
+
+### AWS Managed KMS Keys
+
+Backups of resource types that are not "fully managed" by AWS Backup within the workload accounts will retain the encryption configuration of the source resource. Backups of resources that are encrypted with an AWS managed KMS Key - a key with an alias starting `aws/` - [cannot be copied cross-account](https://docs.aws.amazon.com/aws-backup/latest/devguide/encryption.html#copy-encryption).
+
+### Customer Managed KMS Keys
+
+Backups of resource types that are not "fully managed" by AWS Backup within the workload accounts will retain the encryption configuration of the source resource. Where the source resource is encrypted with a customer managed KMS Key, the Key Policy needs to allow the principals used by AWS Backup to use the key for cross-account copying; this still applies when the default KMS Key Policy is used.
+
+Ensure that the statements below are included within the Key Policy of the customer managed KMS Key used to encrypt the source resources, these have been derived from [AWS Guidelines](https://repost.aws/knowledge-center/backup-troubleshoot-cross-account-copy).
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        ...
+        {
+      "Sid": "Allow AWS Backup to use the key for backup and cross-account copy",
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": [
+          "arn:aws:iam::${WorkloadAccountID}:role/${DeploymentBackupServiceRoleName}",
+          "arn:aws:iam::${CentralAccountID}:role/aws-service-role/backup.amazonaws.com/AWSServiceRoleForBackup"
+        ]
+      },
+      "Action": [
+        "kms:DescribeKey",
+        "kms:Encrypt",
+        "kms:Decrypt",
+        "kms:ReEncrypt*",
+        "kms:GenerateDataKey",
+        "kms:GenerateDataKeyWithoutPlaintext"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "Allow AWS Backup to manage grants for backup and cross-account copy",
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": [
+          "arn:aws:iam::${WorkloadAccountID}:role/${DeploymentBackupServiceRoleName}",
+          "arn:aws:iam::${CentralAccountID}:role/aws-service-role/backup.amazonaws.com/AWSServiceRoleForBackup"
+        ]
+      },
+      "Action": [
+        "kms:CreateGrant",
+        "kms:ListGrants",
+        "kms:RevokeGrant"
+      ],
+      "Resource": "*",
+      "Condition": {
+        "Bool": {
+          "kms:GrantIsForAWSResource": "true"
+        }
+      }
+    }
+    ]
+}
+```
+
+## S3
+
+S3 is "fully managed" by AWS Backup, so the source encryption does not matter as long as the Backup Service Role can access the objects.
+
+When `create_continuous_backups` or `snapshot_from_continuous_backups` is enabled on a plan targetting the bucket, a continuous backup will be created in the workload account Backup Vault. Snapshots will then be taken from the continuous backup and copied to the central account Backup Vault, in line with [AWS best practice](https://docs.aws.amazon.com/aws-backup/latest/devguide/s3-backups.html#bestpractices-costoptimization).
+
+To ensure your objects are backed up, see the [prerequisites from AWS](https://docs.aws.amazon.com/aws-backup/latest/devguide/s3-backups.html#s3-backup-prerequisites).

docs/usage.md renamed to docs/usage-configuration.md

@@ -1,31 +1,22 @@
-# Using the module
+# Configuration
 
-## Prerequisites
+The module is designed to be deployed only once per Organization, it can be deployed multiple times as long as [`central_account_resource_name_prefix`](#inputs_central_account_resource_name_prefix) is unique to each module call. Within the configuration of the module you can define multiple deployments to target areas of your organization with tailored backup plans.
 
-**It is strongly recommended that this module is deployed into a dedicated AWS Backup account within your AWS Organization.**
+## Inputs
 
-The module is designed to be deployed into a delegated administrator account within an AWS Organization, it assumes that these requirements are met when deploying:
-
-- [All features are enabled](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_support-all-features.html) for your AWS Organization.
-- [Trusted access with AWS Backup](https://docs.aws.amazon.com/organizations/latest/userguide/services-that-can-integrate-backup.html#integrate-enable-ta-backup) is enabled on your Organization.
-- [Backup Policies](https://docs.aws.amazon.com/organizations/latest/userguide/enable-policy-type.html) within your Organization.
-- [Enable cross-account backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/create-cross-account-backup.html#prereq-cab) is turned on within your Organization.
-- [AWS Backup cross-account monitoring](https://docs.aws.amazon.com/aws-backup/latest/devguide/manage-cross-account.html#enable-cross-account) is enabled within your Organization.
-- Resource Access Manager (RAM) sharing with AWS Organizations enabled in management account at Resource Access Manager, Settings
-- The account you are deploying to has been [delegated to manage AWS Backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/manage-cross-account.html#backup-delegatedadmin).
-- The account you are deploying to has been [delegated to manage CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-delegated-admin.html).
-- The account you are deploying to has permission to [manage Backup Policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html) as detailed in [our example delegation policy](./org-policy.md).
-
-## Deployment & Configuration
-
-The module is to be deployed only once per Organization, within the configuration for the module you can define multiple deployments with unique settings.
+<!-- prettier-ignore-start -->
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|----------|
+| <a name="inputs_central_account_resource_name_prefix"></a> [central\_account\_resource\_name\_prefix](#inputs\_central\_account\_resource\_name\_prefix) | Prefix to be used for resource names in the central account. | `string` |  | yes |
+| <a name="inputs_deployments"></a> [deployments](#inputs\_deployments) | A map of deployments, see [Deployments](#deployments) | `map(object)` |  | you |
+| <a name="inputs_member_account_resource_name_prefix"></a> [member\_account\_resource\_name\_prefix](#inputs\_member\_account\_resource\_name\_prefix) | Prefix to be used for resource names in member accounts. | `string` |  | yes |
+| <a name="inputs_terraform_state_bucket_name"></a> [terraform\_state\_bucket\_name](#inputs\_terraform\_state\_bucket\_name) | Name of the S3 bucket used for storing Terraform state files for resources within workload accounts. | `string` |  | yes |
+<!-- prettier-ignore-end -->
 
 ### Deployments
 
 A deployment is an instance of the backup solution. Within the deployment account it creates a single set of resources (Backup Vaults, KMS Key, CloudFormation StackSet, etc.) that can then be used by multiple workload accounts. Deployments create a **security boundary** for your backups. The key value for each deployment is used to generate unique resource names within the deployment account and workload accounts.
 
-### Variables
-
 <!-- prettier-ignore-start -->
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|----------|

docs/org-policy.md renamed to docs/usage-prerequisites.md

@@ -1,8 +1,24 @@
-# Organization Delegation Policy
+# Prerequisites
 
-The account to which you are deploying this module requires permission to [manage Backup Policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html) through your Organization's delegation policy.
+**It is strongly recommended that this module is deployed into a dedicated AWS Backup account within your AWS Organization.**
 
-An example delegation policy is provided below, derived from [AWS guidelines](https://aws.amazon.com/blogs/storage/delegated-administrator-support-for-aws-backup). 
+The module is designed to be deployed into a delegated administrator account within an AWS Organization, it assumes that these requirements are met when deploying:
+
+- [All features are enabled](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_support-all-features.html) for your AWS Organization.
+- [Trusted access with AWS Backup](https://docs.aws.amazon.com/organizations/latest/userguide/services-that-can-integrate-backup.html#integrate-enable-ta-backup) is enabled on your Organization.
+- [Backup Policies](https://docs.aws.amazon.com/organizations/latest/userguide/enable-policy-type.html) are enabled within your Organization.
+- [Enable cross-account backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/create-cross-account-backup.html#prereq-cab) is turned on within your Organization.
+- [AWS Backup cross-account monitoring](https://docs.aws.amazon.com/aws-backup/latest/devguide/manage-cross-account.html#enable-cross-account) is enabled within your Organization.
+- Resource Access Manager (RAM) sharing with AWS Organizations enabled in management account at Resource Access Manager, Settings
+- The account you are deploying to has been [delegated to manage AWS Backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/manage-cross-account.html#backup-delegatedadmin).
+- The account you are deploying to has been [delegated to manage CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-delegated-admin.html).
+- The account you are deploying to has permission to [manage Backup Policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html) as detailed in [our example resource-based delegation policy](#Example-organization-resource-based-delegation-policy).
+
+## Example organization resource-based delegation policy
+
+The account to which you are deploying this module requires permission to [manage Backup Policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html) through your Organization's resource-based delegation policy.
+
+An example resource-based delegation policy is provided below, derived from [AWS guidelines](https://aws.amazon.com/blogs/storage/delegated-administrator-support-for-aws-backup).
 
 - In the console for your AWS management account, navigate to AWS Organizations -> Settings -> Delegated administrator for AWS Organizations -> Delegate
 
@@ -18,6 +34,7 @@ An example delegation policy is provided below, derived from [AWS guidelines](ht
 
 - replace `${root_id}` with your Organization Root ID
 
+<!-- prettier-ignore-start -->
 ```json
 {
   "Version": "2012-10-17",
@@ -93,4 +110,5 @@ An example delegation policy is provided below, derived from [AWS guidelines](ht
     }
   ]
 }
-```
+```
+<!-- prettier-ignore-end -->

mkdocs.yml

@@ -46,9 +46,10 @@ nav:
   - Home: index.md
   - Why use this module?: why-use-this-module.md
   - Architecture: architecture.md
-  - Usage:
-      - Using the module: usage.md
-      - Organizations policy: org-policy.md
+  - Using the module:
+      - Prerequisites: usage-prerequisites.md
+      - Configuration: usage-configuration.md
+      - Backing up your resources: usage-backing-up-your-resources.md
 
 plugins:
   - social

variables.tf

@@ -46,6 +46,6 @@ variable "member_account_resource_name_prefix" {
 
 variable "terraform_state_bucket_name" {
   type        = string
-  description = "Name of S3 bucket for custom Terraform deployments, if left at default, S3 bucket will be created"
+  description = "Name of the S3 bucket used for storing Terraform state files for resources in workload accounts. If not specified, an S3 bucket will be created in the central account."
   default     = ""
 }