Create AWS Backup Vault Terraform module for cross-account backup

README.md

@@ -1,93 +1,91 @@
-# Repository Template
+# AWS Backup Vault Terraform module for cross-account backup
 
-[![CI/CD Pull Request](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=repository-template&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=repository-template)
+[![CI/CD Pull Request](https://github.com/nhs-england-tools/terraform-aws-backup-vault/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/terraform-aws-backup-vault/actions/workflows/cicd-1-pull-request.yaml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=terraform-aws-backup-vault&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=terraform-aws-backup-vault)
 
-Start with an overview or a brief description of what the project is about and what it does. For example -
-
-Welcome to our repository template designed to streamline your project setup! This robust template provides a reliable starting point for your new projects, covering an essential tech stack and encouraging best practices in documenting.
-
-This repository template aims to foster a user-friendly development environment by ensuring that every included file is concise and adequately self-documented. By adhering to this standard, we can promote increased clarity and maintainability throughout your project's lifecycle. Bundled within this template are resources that pave the way for seamless repository creation. Currently supported technologies are:
-
-- Terraform
-- Docker
-
-Make use of this repository template to expedite your project setup and enhance your productivity right from the get-go. Enjoy the advantage of having a well-structured, self-documented project that reduces overhead and increases focus on what truly matters - coding!
+This solution demonstrates how you can save time using Terraform to automate the deployment of your AWS Backup resources across accounts in your organization. Using this solution, you can centrally manage the deployment of AWS Backup resources, such as vaults, as well as backup policies, for all of your AWS Organizations accounts.
 
 ## Table of Contents
 
-- [Repository Template](#repository-template)
+- [AWS Backup Vault Terraform module for cross-account backup](#aws-backup-vault-terraform-module-for-cross-account-backup)
   - [Table of Contents](#table-of-contents)
-  - [Setup](#setup)
-    - [Prerequisites](#prerequisites)
-    - [Configuration](#configuration)
-  - [Usage](#usage)
-    - [Testing](#testing)
+  - [Prerequisites](#prerequisites)
+  - [Getting started](#getting-started)
+    - [Terraform init](#terraform-init)
+    - [Deploy resources](#deploy-resources)
+    - [Define backup policies](#define-backup-policies)
+  - [Considerations](#considerations)
   - [Design](#design)
     - [Diagrams](#diagrams)
-    - [Modularity](#modularity)
   - [Contributing](#contributing)
   - [Contacts](#contacts)
   - [Licence](#licence)
 
-## Setup
+## Prerequisites
 
-By including preferably a one-liner or if necessary a set of clear CLI instructions we improve user experience. This should be a frictionless installation process that works on various operating systems (macOS, Linux, Windows WSL) and handles all the dependencies.
+- [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started.html) enabled and access to the _Management account_.
+- [AWS Backup features enabled for your organization](https://docs.aws.amazon.com/organizations/latest/userguide/services-that-can-integrate-backup.html).
+- An AWS account that will be used as your _Central Backup account_. This account should be [registered as a delegated administrator](https://aws.amazon.com/blogs/storage/delegated-administrator-support-for-aws-backup/) for AWS Organizations.
+- [Terraform v1.3.6](https://developer.hashicorp.com/terraform/downloads) or later installed.
 
-Clone the repository
+## Getting started
 
-```shell
-git clone https://github.com/nhs-england-tools/repository-template.git
-cd nhs-england-tools/repository-template
-```
+### Terraform init
 
-### Prerequisites
+1. To manage the Terraform state, Amazon S3 is used to store our `.tfstate` file and a Amazon DynamoDB table to maintain the _lock state_ of our environment. Create these resources and update the `backend.tf` file with the appropriate values. You can learn more about protecting sensitive data in the Terraform state file using [the AWS Prescriptive Guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/secure-sensitive-data-secrets-manager-terraform/terraform-state-file.html).
 
-The following software packages, or their equivalents, are expected to be installed and configured:
+2. If you plan to use the _OrganizationAccountAccessRole_ for cross-acount operations, then you do not need to create any additional roles for managing these resources. However, you will need to update the trust relationships with the `Principal` of the IAM role or user you will be using to run the Terraform commands from the _Management account_.
+As a best practice, you will want to create roles specifically for Terraform to assume in each account following least privilege. Update the `role_arn` within the `provider.tf` file with the roles you will use.
 
-- [Docker](https://www.docker.com/) container runtime or a compatible tool, e.g. [Podman](https://podman.io/),
-- [asdf](https://asdf-vm.com/) version manager,
-- [GNU make](https://www.gnu.org/software/make/) 3.82 or later,
-- [GNU coreutils](https://www.gnu.org/software/coreutils/) and [GNU binutils](https://www.gnu.org/software/binutils/) may be required to build dependencies like Python, which may need to be compiled during installation. For macOS users, this has been scripted and automated by the `dotfiles` project; please see this [script](https://github.com/nhs-england-tools/dotfiles/blob/main/assets/20-install-base-packages.macos.sh) for details,
-- [Python](https://www.python.org/) required to run Git hooks,
-- [`jq`](https://jqlang.github.io/jq/) a lightweight and flexible command-line JSON processor.
+3. Run the `terraform init` command to initialize the working directory and install the plugin for the AWS provider.
 
-> [!NOTE]<br>
-> The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain `make` tasks will fail. On macOS, you will need [Homebrew](https://brew.sh/) installed, then to install `make`, like so:
->
-> ```shell
-> brew install make
-> ```
->
-> You will then see instructions to fix your `$PATH` variable to make the newly installed version available. If you are using [dotfiles](https://github.com/nhs-england-tools/dotfiles), this is all done for you.
+### Deploy resources
 
-### Configuration
+1. Setup the Terraform variables required to deploy resources into the accounts. Create a `terraform.tfvars` file in the root module and populate them with the appropriate values.
+The `target_account_id` is the account number of the _Member account_ which containers resources that you wish to backup. The `backup_account_id` is the account number of the _Central Backup account_. The `org_id` is the [Organization ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html#orgs_view_org) which you can find from the AWS Organizations console in you _Management account_.
 
-Installation and configuration of the toolchain dependencies
+    ```terraform
+    target_account_id = "012345678901"
+    backup_account_id = "234567890123"
+    org_id = "o-a12b3cdefg"
+    ```
 
-```shell
-make config
-```
+2. Run the `terraform apply` command to deploy resources within your member and backup account.
 
-## Usage
+### Define backup policies
 
-After a successful installation, provide an informative example of how this project can be used. Additional code snippets, screenshots and demos work well in this space. You may also link to the other documentation resources, e.g. the [User Guide](./docs/user-guide.md) to demonstrate more use cases and to show more features.
+The _Central Backup account_ should be [registered as a delegated administrator](https://aws.amazon.com/blogs/storage/delegated-administrator-support-for-aws-backup/) from your organizations _Management account_ as part of the [prerequisites](#prerequisites). This will allow AWS Backup to assume cross-account roles and access the AWS Organizations API to manage backup policies.
 
-### Testing
+The policy management process involves creating a `.zip` archive containing two JSON files, then uploading it to your designated S3 bucket, created during the [deploy resources](#deploy-resources) stage. These two files are: a backup policy, and a list of target OUs/accounts.
 
-There are `make` tasks for you to configure to run your tests.  Run `make test` to see how they work.  You should be able to use the same entry points for local development as in your CI pipeline.
+1. The `modules/backup-account/PolicyExample/policy_definition.json` is a backup policy that is formatted using the syntax described in the [AWS Backup documentation](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html). Review or adjust this file to your requirements.
 
-## Design
+2. The `modules/backup-account/PolicyExample/target_list.json` file contains a list of targets, which can be a combination of OU IDs and account IDs. In this example it will contain the single _Member account_ we have prepared earlier. Edit the file with the `target_account_id`.
 
-### Diagrams
+    ```json
+    {
+        "targets":
+        [
+            "AccountID"
+        ]
+    }
+    ```
 
-The [C4 model](https://c4model.com/) is a simple and intuitive way to create software architecture diagrams that are clear, consistent, scalable and most importantly collaborative. This should result in documenting all the system interfaces, external dependencies and integration points.
+3. Archive these two files to a `.zip` and upload to your S3 bucket within the _Central Backup account. This will trigger two Lambda functions to unzip, parse, validate and apply the policy and attach it to the specified targets.
 
-![Repository Template](./docs/diagrams/Repository_Template_GitHub_Generic.png)
+## Considerations
 
-### Modularity
+As mentioned in the [Getting Started](#getting-started) section, this sample uses the _OrganizationAccountAccessRole_ role which is created when an account is created in your organization. If you would like to follow along with the sample you will need to update the trust relationships of the role with the `Principal` of the IAM role or user you will be using to run the Terraform commands from the _Management account_. However, it is recommended to create a new role that is present within your accounts that Terraform can assume. If you have done so update the `role_arn` within the `provider.tf` file with the role arn.
+
+This sample uses customer-managed keys (CMK) in AWS KMS, it is important that you configure these to your requirements. Key deletion windows and rotation can be set within the `variables.tf` file. It is also important [to monitor](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-overview.html) AWS KMS to control and understand the availability, state and usage of the CMKs.
+
+AWS Backup supports cross-account backup copying within your AWS Organization for centralized backup management. For cross-account copies of encrypted backups, some AWS services have their own encryption and is not independent of AWS Backup encryption. For data sources without AWS Backup encryption, source and destination backup vault must be encrypted with a shared AWS KMS customer-managed key. For more information see the storage blog on [How encryption works in AWS Backup](https://aws.amazon.com/blogs/storage/how-encryption-works-in-aws-backup/).
+
+## Design
+
+### Diagrams
 
-Most of the projects are built with customisability and extendability in mind. At a minimum, this can be achieved by implementing service level configuration options and settings. The intention of this section is to show how this can be used. If the system processes data, you could mention here for example how the input is prepared for testing - anonymised, synthetic or live data.
+![AWS Backup Vault infrastructure diagram](./docs/user-guides/AWS%20Backup%20Vault%20infrastructure%20diagram.png)
 
 ## Contributing