# Deploy the solution
This solution uses AWS CloudFormation templates and stacks to automate its deployment. The CloudFormation template specifies the AWS resources included in this solution and their properties. The CloudFormation stack provisions the resources described in the template.
## Deployment process overview
Before you launch the solution, review the [cost](cost.md), [architecture](architecture-details.md), [network security](security.md), and other considerations discussed earlier in this guide.
**Time to deploy:** Approximately eight minutes for the `AWSAccelerator-Installer` CloudFormation stack and 45 minutes for the initial run of the `AWSAccelerator-Pipeline` pipeline.
**Note**
If you have previously deployed this solution, refer to [Update the solution](update-the-solution.md) for update instructions.
Use the following steps to deploy this solution on AWS. For detailed instructions, follow the links for each step.
[Step 1. Launch the stack](step-1.-launch-the-stack.md)
+ Launch the AWS CloudFormation template into your AWS account.
+ Review the templates parameters and enter or adjust the default values as needed.
[Step 2. Await initial environment deployment](step-2.-await-initial-environment-deployment.md)
+ Await successful completion of `AWSAccelerator-Pipeline` pipeline.
[Step 3. Update the configuration files](step-3.-update-the-configuration-files.md)
+ Navigate to the stored Landing Zone Accelerator on AWS configuration files.
+ Update the configuration files to match the desired state of your environment.
+ Release a change manually to the `AWSAccelerator-Pipeline` pipeline.
**Important**
This solution includes an option to send anonymized operational metrics to AWS. We use this data to better understand how customers use this solution and related services and products. AWS owns the data gathered though this survey. Data collection is subject to the [AWS Privacy Notice](https://aws.amazon.com/privacy/).
To opt out of this feature, download the template, modify the AWS CloudFormation mapping section, and then use the AWS CloudFormation console to upload your updated template and deploy the solution. For more information, refer to the [Anonymized data collection](reference.md#collection-of-operational-metrics) section of this guide.
# Prerequisites
You must meet the following prerequisites before launching the stack.
## Activate a multi-account management solution
Landing Zone Accelerator on AWS solution can create, update, or reset an AWS Control Tower Landing Zone. When enabled, the solution will deploy AWS Control Tower in the home Region.
## For AWS Control Tower based installation
### Auto-deploy AWS Control Tower by the solution (recommended)
Using the Landing Zone Accelerator on AWS solution, you can create, update, or reset an AWS Control Tower Landing Zone. It is possible to maintain the AWS Control Tower Landing Zone using the Landing Zone Accelerator solution. When the installer stack of the solution is deployed with the `ControlTowerEnabled` parameter set to `Yes`, then the Landing Zone Accelerator solution will deploy the AWS Control Tower Landing Zone with the most recent version available.
The Landing Zone Accelerator solution can deploy AWS Control Tower Landing Zone when the following prerequisites are met.
+ Configured AWS Organizations with all feature enabled in management account.
Create AWS Organization and verify that your own the email address is provided for the management account in the organization. In order to learn more about setting up an AWS organization, you may refer to this [Creating an organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_create.html) in the *AWS Organizations\$1\$1User Guide*.
**Note**
In the event that AWS Organizations has been configured, but not all features have been enabled, the solution will enable all features for your organization.
+ There are no AWS services enabled for AWS Organizations.
+ There are no organization units created in the AWS Organizations.
+ The only AWS account in the AWS Organization is the management account.
+ The management account does not have AWS IAM Identity Center configured.
+ The following AWS Control Tower service roles are not preset in the management account.
+ [AWSControlTowerAdmin](https://docs.aws.amazon.com/controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerAdmin)
+ [AWSControlTowerCloudTrailRole](https://docs.aws.amazon.com/controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerCloudTrailRole)
+ [AWSControlTowerStackSetRole](https://docs.aws.amazon.com/controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerStackSetRole)
+ [AWSControlTowerConfigAggregatorRoleForOrganizations](https://docs.aws.amazon.com/controltower/latest/userguide/roles-how.html#config-role-for-organizations)
Landing Zone Accelerator performs the following prerequisites before deploying AWS Control Tower Landing Zone. This [document](https://docs.aws.amazon.com/controltower/latest/userguide/lz-api-prereques.html) provides more information about AWS Control Tower prerequisites. The solution will not perform any of the prerequisites if there is an existing AWS Control Tower Landing Zone.
+ Deploy following AWS Control Tower service roles in the management account:
+ [AWSControlTowerAdmin](https://docs.aws.amazon.com/controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerAdmin)
+ [AWSControlTowerCloudTrailRole](https://docs.aws.amazon.com/controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerCloudTrailRole)
+ [AWSControlTowerStackSetRole](https://docs.aws.amazon.com/controltower/latest/userguide/access-control-managing-permissions.html#AWSControlTowerStackSetRole)
+ [AWSControlTowerConfigAggregatorRoleForOrganizations](https://docs.aws.amazon.com/controltower/latest/userguide/roles-how.html#config-role-for-organizations)
+ Deploy AWS KMS CMK with alias `alias/aws-controltower/key` in the management account home Region.
+ Create shared accounts (`LogArchive` and `Audit`) and invite to AWS Organizations.
+ Deploy AWS Control Tower Landing Zone in the management account home Region.
**Note**
Landing Zone Accelerator on AWS uses the [AWS Control Tower API](https://docs.aws.amazon.com/controltower/latest/userguide/getting-started-apis.html) to create and manage the AWS Control Tower Landing Zone.
**Important**
The AWS Console should be used to enable or disable the Region deny property for your AWS Control Tower Landing Zone. Currently, the Landing Zone Accelerator solution does not support the modification of the Region deny feature. Due to the fact that the Landing Zone Accelerator may deploy certain global AWS services, such as AWS IAM and AWS Organizations, the solution will add the global Region to the list of governed Regions in the AWS Control Tower if the home Region of the Landing Zone Accelerator is not the same as the global Region.
### Manually deploy AWS Control Tower
To set up AWS Control Tower, refer to [Getting started with AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/userguide/getting-started-with-control-tower.html) in the *AWS Control Tower User Guide*.
**Note**
If you’re using AWS Control Tower, we strongly recommended creating an AWS KMS customer managed key before deploying your landing zone. This AWS KMS key is used by services that AWS Control Tower manages to apply encryption at rest to sensitive log files. For more information on activating encryption for AWS Control Tower, see [Configure your shared accounts and encryption](https://docs.aws.amazon.com/controltower/latest/userguide/getting-started-with-control-tower.html#configure-shared-accounts).
If you’re deploying a new AWS Control Tower landing zone, you can add the prerequisite **Infrastructure** OU during the initial setup wizard. By default, the landing zone deploys with an additional **Sandbox** OU. You can rename this OU to **Infrastructure** if desired. Alternatively, you can create the **InfrastructureOU** after the landing zone is provisioned.
For more information about customizing the additional OU created during Control Tower setup, see [Step 2b. Configure your organizational units (OUs)](https://docs.aws.amazon.com/controltower/latest/userguide/configure-ous.html) in the *Control Tower User Guide*.
## For AWS Organizations based installation (without AWS Control Tower)
To set up AWS Organizations, refer to [Getting started with AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started.html) in the *AWS Organization User Guide*.
Ensure the [Mandatory accounts](mandatory-accounts.md) are created. The Landing Zone Accelerator on AWS requires these three accounts at minimum to successfully deploy to your environment.
For more information on managing accounts in an AWS Organization, refer to [Managing the AWS accounts in your organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts.html) in the *AWS Organization User Guide*.
## Update AWS CodeBuild concurrency quota
Follow this procedure to check your current CodeBuild concurrency quota.
1. Navigate to the [Service Quotas console](https://console.aws.amazon.com/servicequotas/) in the account and Region for which you will deploy the Landing Zone Accelerator on AWS solution.
1. In the navigation pane, choose **AWS services**.
1. Search for then select AWS CodeBuild.
1. Select **Concurrently running builds for Linux/Large environment**.
1. If the value under **Applied quota value** is less than 3, select the quota link. Otherwise, skip the remaining steps.
1. Choose **Request increase at account-level**. In the **Increase quota value** box, enter `3` or more as the new quota value.
1. Choose **Request**. Ensure this quota increase request has been approved prior to deploying the solution. You can view your request status by choosing **Quota request history** in the navigation sidebar.
## Ensure your global Region is accessible
Some AWS services and features apply configurations to your accounts at a global level rather than a regional level. In addition to the Regions that you enable in the solution configuration files; this solution requires access to the Region where global service API endpoints are hosted. The global Region depends on the AWS partition you will be deploying the solution to.
**AWS partitions and their corresponding global Region**
| AWS Partition | Global Region |
| --- | --- |
| **Standard (aws)** | `us-east-1` |
| **GovCloud US (aws-us-gov)** | `us-gov-west-1` |
| **China (aws-cn)** | `cn-northwest-1` |
**Important**
Ensure that you don’t have any existing AWS Organizations service control policies and/or Control Tower Region deny settings configured in your environment that would block access to the global Region listed above. You might experience Core pipeline failures if you do not allow access to this Region.
## Create a GitHub personal access token and store in Secrets Manager
You require a GitHub access token to access the Landing Zone Accelerator on AWS code repository. Instructions on how to create a personal access token are located on [GitHub Docs](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
**Note**
The GitHub access token must have `public_repo` permissions.
Store the personal access token in Secrets Manager as plain text in the home Region. Name the secret `accelerator/github-token` (case sensitive).
With the AWS Management Console in the home Region:
1. Store a new secret, and select **Other type of secrets**, **Plaintext**.
1. Paste your secret with no formatting, leading, or trailing spaces (completely remove the example text).
1. Select an encryption key.
1. Set the secret name to `accelerator/github-token` (case sensitive).
1. Select **Disable rotation**.
# AWS CloudFormation template
You can download the CloudFormation template for this solution before deploying it.
[https://s3.amazonaws.com/solutions-reference/landing-zone-accelerator-on-aws/latest/AWSAccelerator-InstallerStack.template](https://s3.amazonaws.com/solutions-reference/landing-zone-accelerator-on-aws/latest/AWSAccelerator-InstallerStack.template) **AWSAccelerator-InstallerStack.template** - Use this template to launch the solution and all associated components. The default configuration deploys the core and supporting solutions found in the [Architecture overview](architecture-overview.md). Manual changes to the template are strongly discouraged.
Before you launch the solution, review the [cost](cost.md), [architecture](architecture-details.md), [network security](security.md), and other considerations discussed earlier in this guide.
**Note**
AWS CloudFormation resources are created from AWS CDK constructs.
If you have previously deployed this solution, refer to [Update the solution](update-the-solution.md) for update instructions.
# Step 1. Launch the stack
This automated AWS CloudFormation template deploys the Landing Zone Accelerator on AWS in the AWS Cloud. You must complete the applicable steps in [Prerequisites](prerequisites.md) before launching the stack.
1. Sign into [AWS Management Console](https://aws.amazon.com/console) and select the button to launch `AWSAccelerator-InstallerStack` CloudFormation template. [https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?templateURL=https:%2F%2Fsolutions-reference.s3.amazonaws.com%2Flanding-zone-accelerator-on-aws%2Flatest%2FAWSAccelerator-InstallerStack.template&redirectId=ImplementationGuide](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?templateURL=https:%2F%2Fsolutions-reference.s3.amazonaws.com%2Flanding-zone-accelerator-on-aws%2Flatest%2FAWSAccelerator-InstallerStack.template&redirectId=ImplementationGuide)
1. The template launches in the US East (N. Virginia) Region by default. To launch the solution in a different AWS Region, use the Region selector in the console navigation bar.
**Note**
This solution recommends using the AWS Control Tower service, which isn’t currently available in all AWS Regions. We recommend launching this solution in an AWS Region where AWS Control Tower is available. For the most current availability by Region, refer to the [AWS Regional Services List](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/).
1. On the **Create stack** page, verify that the correct template URL is in the **Amazon S3 URL** text box and choose **Next**.
1. On the **Specify stack details** page, assign a name to your solution stack. We recommend you name your stack `AWSAccelerator-InstallerStack` to match the naming convention used by additional stacks that will be created by the Landing Zone Accelerator on AWS. For information about naming character limitations, refer to [IAM and STS quotas](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html) in the *AWS Identity and Access Management User Guide*.
1. Under **Parameters**, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/step-1.-launch-the-stack.html)
1. Choose **Next**.
1. On the **Configure stack options** page, choose **Next.**
1. On the **Review and create** page, review and confirm the settings. Select the box acknowledging that the template might create IAM resources.
1. Choose **Submit** to deploy the stack.
You can view the status of the stack in the AWS CloudFormation console in the **Status** column. You should receive a `CREATE_COMPLETE` status in approximately eight minutes.
# Step 2. Await initial environment deployment
Use the following procedure to ensure the Landing Zone Accelerator on AWS deploys a minimum configuration to your environment.
1. Sign in to the AWS Management Console and navigate to the **AWS CodePipeline** console. The `AWSAccelerator-Installer` pipeline should show a status of either `In Progress` or `Complete`. If `In Progress`, wait for the pipeline to complete.
1. When the `AWSAccelerator-Installer` pipeline has completed, a new `AWSAccelerator-Pipeline` pipeline is created that’s now `In Progress`. Refresh the AWS CodePipeline console if the new pipeline isn’t visible.
1. The `AWSAccelerator-Pipeline` pipeline takes approximately 45 minutes to complete. This initial deployment prepares your environment for Landing Zone Accelerator on AWS and deploy a minimal configuration. Resources deployed include AWS CloudFormation custom resources, CloudWatch Logs log groups for the custom resources, AWS KMS keys for encryption at rest, and Amazon S3 buckets for AWS service logging.
1. After completion of the preceding steps, your environment is ready to customize.
# Step 3. Update the configuration files
Use the following procedure to customize Landing Zone Accelerator on AWS to fit your environment’s needs. These files are stored in either a CodeCommit repository, S3 bucket, or a custom repository using [AWS CodeConnections](https://docs.aws.amazon.com/codeconnections/latest/APIReference/Welcome.html) depending on parameters selected during deployment. If you aren’t sure, check the `Configuration Repository Location` parameter of your `AWSAccelerator-Installer` stack.
## Using CodeCommit
1. Sign in to the AWS Management Console and navigate to the **CodeCommit** console. Navigate to the repository named **aws-accelerator-configuration**. The repository shows the Landing Zone Accelerator on AWS configuration files.
1. Each configuration file is named based on its purpose in Landing Zone Accelerator on AWS. A [sample configuration](https://github.com/awslabs/landing-zone-accelerator-on-aws/tree/main/reference/sample-configurations/lza-sample-config) is available on our GitHub repository. Customize each configuration file to deploy the additional AWS services and infrastructure required. You can use the CodeCommit console or a compatible Git client to manipulate these files. For more information, refer to [Edit the contents of a file in a CodeCommit repository](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-edit-file.html) in the *AWS CodeCommit User Guide*.
1. When finished editing the configuration files, navigate to the AWS CodePipeline console. Select **AWSAccelerator-Pipeline**, then **Release change**. This initiates a new pipeline instantiation and deploy the configuration changes to your environment.
1. Await successful completion of the pipeline. If any failures occur, the CodePipeline console displays the failure stage and action in red. To troubleshoot any errors, choose **Details** on the CodeBuild action to navigate to the failed action. In the CodeBuild console, you can view the **Build logs**, which indicates the error encountered during deployment. For more information, refer to [Troubleshooting](troubleshooting.md).
## Using Amazon S3
1. Sign in to the [Amazon S3 console](https://console.aws.amazon.com/s3).
1. Navigate to the bucket named `aws-accelerator-config- `-` `.
1. Download the S3 object `zipped/aws-accelerator-config.zip` and extract the contents to view your Landing Zone Accelerator on AWS configuration files.
1. Each configuration file is named based on its purpose in Landing Zone Accelerator on AWS. A [sample configuration](https://github.com/awslabs/landing-zone-accelerator-on-aws/tree/main/reference/sample-configurations/lza-sample-config) is available on our GitHub repository. Customize each configuration file to deploy the additional AWS services and infrastructure required. Make desired changes to these files locally, then save your changes.
1. When you’re finished editing the configuration files, compress the files into a new zip archive file named `aws-accelerator-config.zip`. Upload this file to the same S3 object path `zipped/aws-accelerator-config.zip` used in Step 1.
**Note**
The `aws-accelerator-config.zip` file contains all of the files at the root of the zip archive file. The following is an example of using the `tree` command to list the contents:
```
> tree -a .
.
├── accounts-config.yaml
├── global-config.yaml
├── iam-config.yaml
├── network-config.yaml
├── organization-config.yaml
├── security-config.yaml
```
1. Sign in to the [AWS CodePipeline console](https://console.aws.amazon.com/codepipeline). Select **AWSAccelerator-Pipeline**, then **Release** change. This initiates a new pipeline instantiation and deploys the configuration changes to your environment.
1. Await successful completion of the pipeline. If failures occur, the CodePipeline console displays the failure stage and action in red. To troubleshoot errors, choose **Details** on the CodeBuild action to navigate to the failed action. In the CodeBuild console, you can view the **Build logs**, which indicate the error encountered during deployment. For more information, refer to [Troubleshooting](troubleshooting.md).
## Using AWS CodeConnections
1. Sign in to the [Amazon Developer Tools console](https://us-east-1.console.aws.amazon.com/codesuite/home?region=us-east-1).
1. From the left-hand sidebar, select the **Settings** drop down and select **Connections**.
1. On the **Connections** page, select the **Create Connection** button.
1. To create a connection, follow the [Create a connection](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create.html) user guide in the *Developer Tools console*.
**Note**
When creating a connection, select **Install a new app**, otherwise it is possible the source stage in your pipeline may fail while attempting to connect to your configuration repository
1. After creating the Code Connection successfully, make sure to note the Code Connection ARN.
1. Once you have the Code Connection ARN, you can fill out the following Parameters in the LZA Installer Stack:
+ UseExistingConfigRepo: **Yes**
+ ExistingConfigRepositoryName: **aws-accelerator-config**
+ ExistingConfigRepositoryOwner: **awslabs**
**Note**
This needs to be your 3rd party "owner" or namespace
+ ExistingConfigRepositoryBranchName: **main**
**Note**
This needs to match your branch name in the 3rd party repo
+ ConfigurationRepositoryLocation: **codeconnection**
# Opt-in Regions
We built the opt-in Region configuration to help customers use the Landing Zone Accelerator on AWS solution in [opt-in Regions](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable).
**Note**
Not all AWS services are available in all Regions, including the AWS opt-in Regions. We update our [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services) list daily with which services are available in which Regions.
You must initially launch Landing Zone Accelerator on AWS in a Region where CodeCommit, AWS CodeBuild, and AWS CodePipeline are available. This will deploy the default resources that are depicted in the [Architecture overview](architecture-overview.md).
The following installation instructions leverage opt-in AWS Regions. Following these instructions deploys the default resources into the management account for items 1-8 of the [architecture diagram](architecture-overview.md#architecture-diagram). Items 9-10 of the architecture diagram, centralized logging and workload accounts, deploy in the opt-in (target) AWS Region.
**Note**
While the Landing Zone Accelerator on AWS solution can help you align with frameworks and best practices, customers are responsible for their own security and compliance practices.
## Prerequisites
To launch the Landing Zone Accelerator on AWS solution into opt-in AWS Regions, verify that the user who launches the solution can:
+ [Allow opt-in AWS Regions](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws-enable-disable-regions.html)
+ Perform IAM administration tasks
## Architecture
**Architecture diagram depicting Landing Zone Accelerator on AWS architecture in opt-in (Target) Regions.**
![\[image12\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/images/image12.png)
## Deployment
### Using an opt-in Region as the target Region
Deploying this solution with the default parameters builds the environment depicted in the previous figure. The default parameters use the **Home Region** for the Landing Zone Accelerator on AWS [Core pipeline](awsaccelerator-pipeline.md) and the **Target Region** for [centralized logging](centralized-logging.md).
#### Step 1. Deploy the solution in your AWS Management account
1. Identify the **Home Region** that you want to use. This Region must have Amazon S3, CodeBuild, and CodePipeline availability.
**Note**
Two main factors contribute to which Region to select as your **Home Region**: latency and cost. Choosing an AWS Region with close proximity to your user base location can achieve lower network latency. AWS services are priced differently from one Region to another.
1. [Prepare for an AWS Organizations based installation (without AWS Control Tower)](prerequisites.md#for-aws-organizations-based-installation-without-aws-control-tower). Use the following notes to guide you:
+ For a new environment, set up AWS Organizations.
+ Create a **LogArchive** account and an **Audit/Security Tooling** account.
+ Create a **Security** OU and **Infrastructure** OU.
1. [Set up Landing Zone Accelerator on AWS in your AWS standard account](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/automated-deployment.html).
#### Step 2. Allow your desired opt-in AWS Regions for all accounts
1. Sign in to your management account.
1. [Allow the Regions](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable) you want to use.
**Note**
When you allow a Region, AWS prepares your account in that Region, such as by distributing your IAM resources to the Region. This process takes a few minutes for most accounts, but it can take several hours. You can’t use the Region until this process is complete.
1. Log in to the **LogArchive** and **Audit/Security Tooling** accounts to repeat the actions to allow the opt-in Regions that you want to use.
#### Step 3. Update the configuration file in your AWS Management account
1. Using your management account, update the `global-config.yaml` file to list the new Region under the `enabledRegions` option, as shown in the following sample. In the sample, Europe (London) (`eu-west-2`) is the home Region and Middle East (Bahrain) (`me-south-1`) is the opt-in (target) Region:
```
homeRegion: eu-west-2
enabledRegions:
- eu-west-2
- me-south-1
```
1. Using your management account, update the `global-config.yaml` file to list the opt-in Region under the `centralizedLoggingRegion` option, as shown in the following sample:
```
logging:
account: LogArchive
centralizedLoggingRegion: me-south-1
cloudtrail:
enable: true
organizationTrail: true
organizationTrailSettings:
multiRegionTrail: true
globalServiceEvents: true
managementEvents: true
s3DataEvents: true
lambdaDataEvents: true
sendToCloudWatchLogs: true
apiErrorRateInsight: false
apiCallRateInsight: false
accountTrails: []
lifecycleRules: []
sessionManager:
sendToCloudWatchLogs: false
sendToS3: false
excludeRegions: []
excludeAccounts: []
lifecycleRules: []
attachPolicyToIamRoles: []
```
1. After the commit, confirm that the pipeline runs successfully.
# Deploy to AWS GovCloud (US) Regions
We architected this solution to follow the Defense Information Systems Agency (DISA) Cloud Computing Security Requirements Guide (CC SRG) for hosting Impact Level (IL)4 and IL5 workloads in the cloud when deployed in AWS GovCloud (US) Regions. Using this solution, you can deploy an architecture baseline that accommodates US Federal and DoD requirements to rapidly achieve Authority to Operate (ATO).
**Note**
While the Landing Zone Accelerator on AWS solution can help you align with frameworks and best practices, customers are responsible for their own ATO readiness.
An installation into AWS GovCloud (US) Regions is treated as an independent installation of the Landing Zone Accelerator on AWS solution. You can use this solution to manage your corresponding standard AWS environment, resulting in two concurrent Landing Zone Accelerator on AWS-based environments that you can manage in a unified way.
**Note**
Not all AWS services are available in all Regions, including the AWS GovCloud (US) Regions. We update our [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services) list daily with which services are available in which Regions.
# Prerequisites
To launch the Landing Zone Accelerator on AWS solution, verify the following:
+ The account used to launch the solution is allowed to access AWS GovCloud (US) Regions.
+ You’re authorized to create accounts in the AWS GovCloud (US) Regions. For more information on the AWS GovCloud (US) Regions, refer to the [AWS GovCloud (US) User Guide](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/welcome.html).
+ You have an account in an AWS GovCloud (US) Region that’s paired with a management account of an organization in a [standard AWS Region](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-differences.html).
# Architecture
**AWS GovCloud architecture diagram showing account types, services, and network connections.**
![\[landing zone accelerator on aws architecture in aws govcloud regions\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/images/landing-zone-accelerator-on-aws-architecture-in-aws-govcloud-regions.png)
# Deployment options for AWS GovCloud (US) workloads
We base the following options on amount of access type of workloads:
+ [Option 1](option-1-deploy-to-new-standard-and-aws-govcloud-us-accounts.md) - Deploy to new standard and AWS GovCloud (US) accounts. This is recommended for customers who are planning to host workloads in both standard and AWS GovCloud (US) Regions. Both Region types will have a Landing Zone Accelerator on AWS.
+ [Option 2](option-2-deploy-on-new-aws-govcloud-us-accounts.md) - Deploy on new AWS GovCloud (US) accounts. This environment has access to both standard and AWS GovCloud (US) Regions. To create new AWS GovCloud (US) accounts, you can use the `CreateGovCloudAccount` API with [Service Catalog](https://aws.amazon.com/servicecatalog/) to create new accounts in the standard Region and add these new accounts into the solution in the AWS GovCloud (US) Region. You only use the standard Region to vend new accounts; no workloads are present in the standard Region.
+ [Option 3](option-3.-deploy-on-existing-govcloud-accounts.md) - Deploy on existing AWS GovCloud (US) accounts. In this option, users have access to AWS GovCloud (US) only and can’t create their own AWS GovCloud (US) accounts. In this situation, AWS GovCloud (US) accounts are provided by third-party providers such as partners or resellers. If AWS Organizations is activated in the management account with [administrative permissions](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/design-considerations.html#administrative-role), then you can deploy the solution.
# Option 1: Deploy to new standard and AWS GovCloud (US) accounts
Deploying this solution with the default parameters builds the following environment in the AWS GovCloud (US) Region(s).
**Architecture diagram depicting AWS GovCloud (US) deployment.**
![\[image10\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/images/image10.png)
The AWS CloudFormation template includes a set of configuration files that have been specifically customized for AWS GovCloud (US) Regions. By following these instructions, you can deploy an environment that includes:
1. Use of AWS Control Tower to manage and govern your [AWS standard accounts](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/getting-started-standard-account-linking.html).
**Note**
In this implementation guide, the terms "AWS standard account" and "AWS standard Region" mean "AWS account that isn’t in an AWS GovCloud (US) Region" and "AWS Region that isn’t an AWS GovCloud (US) Region."
1. A deployment of the solution in your **AWS standard accounts** (refer to the left side of the previous figure), allowing you to activate additional security features and guardrails into your AWS standard accounts and providing you the ability to generate AWS GovCloud (US) accounts.
1. A deployment of the solution in your **AWS GovCloud (US) accounts** (refer to the right side of the previous figure) with the AWS best practices configuration of security services and an AWS best practices-recommended network topology. This configuration is architected to follow the US Department of Defense (DoD) Cloud Computing Security Requirements Guide (CC SRG) for hosting Impact Level (IL)4 and IL5 workloads in the cloud. Using this configuration, you can quickly deploy an architecture baseline that accommodates US federal and DoD requirements to rapidly achieve Authority to Operate (ATO). In addition, this solution is architected to support and accelerate DoD Cybersecurity Maturity Model Certification (CMMC) readiness.
**Important**
Don’t use the AWS standard account paired to AWS GovCloud (US) accounts to host any workloads.
## Step 1. Deploy the solution in your AWS standard Management account and create AWS GovCloud (US) accounts
1. Create an [AWS standard account](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/getting-started-standard-account-linking.html) that is [allowed to access AWS GovCloud (US) Region(s)](https://docs.aws.amazon.com/organizations/latest/APIReference/API_CreateGovCloudAccount.html) and is the AWS Organizations Management account.
1. [Set up and verify AWS Organizations through email.](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_create.html) (This step is optional but saves time in AWS Control Tower setup [Step 1.3].)
1. [Set up Landing Zone Accelerator on AWS](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/automated-deployment.html) in your AWS standard account.
1. After successfully setting up Landing Zone Accelerator on AWS in your AWS standard account, update the `organization-config.yaml` file in the `aws-accelerator-config` CodeCommit repository to make the new OU visible to Landing Zone Accelerator on AWS. [Run](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-rerun-manually.html) the Landing Zone Accelerator on AWS pipeline with this change.
```
enable: true
organizationalUnits:
- name: Security
- name: Infrastructure
- name: GovCloud
serviceControlPolicies: []
taggingPolicies: []
backupPolicies: []
```
1. After the Landing Zone Accelerator on AWS pipeline completes, create new AWS GovCloud (US) accounts using the ` [enableGovCloud](https://awslabs.github.io/landing-zone-accelerator-on-aws/latest/typedocs/latest/classes/_aws_accelerator_config.GovCloudAccountConfig.html#enableGovCloud) ` field in the ` [workloadAccounts](https://awslabs.github.io/landing-zone-accelerator-on-aws/latest/typedocs/latest/classes/_aws_accelerator_config.AccountsConfig.html#workloadAccounts) ` definition. These are AWS GovCloud accounts paired to your AWS standard account. You must specify these under `workloadAccounts:`. The following is a sample account configuration.
```
# commercial accounts-config.yaml
mandatoryAccounts:
- name: Management
description: >-
The management (primary) account. Do not change the name field for this mandatory account.
email: < landing-zone-management-email@example.com> <----- UPDATE EMAIL ADDRESS
organizationalUnit: Root
- name: LogArchive
description: >-
The log archive account. Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Security
- name: Audit
description: >-
The security audit account (also referred to as the audit account). Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Security
workloadAccounts:
- name: LogArchiveGC # referred to as LogArchive in the GovCloud account-config.yaml
description: The log archive account for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
# this OU has all GovCloud accounts.
# OU was created from Control Tower
# in organization-config.yaml this OU was added.
organizationalUnit: GovCloud
# enableGovCloud is a one-time non-reversible option
# which only works with creation of new accounts
enableGovCloud: true
- name: AuditGC # referred to as LogArchive in the GovCloud account-config.yaml
description: The security audit account (also referred to as the audit account) for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: GovCloud
enableGovCloud: true
```
1. The solution creates paired accounts which are joined in AWS Organizations in the AWS standard Region. These accounts will have a cross-account assume role in the AWS GovCloud (US) Region(s) but will not be a part of the AWS GovCloud (US) Organization.
1. Add new AWS GovCloud (US) accounts to the `accounts-config.yaml` file in the AWS standard Region and run the solution pipeline.
**Note**
We highly recommend that you vend all AWS GovCloud (US) accounts from the Landing Zone Accelerator on AWS solution.
1. After the pipeline completes, navigate to AWS Organizations console page to retrieve the commercial account IDs of the newly created accounts.
1. Navigate to the AWS GovCloud (US) account mapping table in Amazon DynamoDB. Find the table name from AWS Systems Manager parameter (SSM parameter) `/accelerator/prepare-stack/govCloudAccountMappingTableName`. In that table, look up rows with commercial account IDs from the previous step. The AWS GovCloud (US) account IDs are shown under the **govCloudAccountId** column. You need these AWS GovCloud (US) account IDs to onboard AWS GovCloud (US) accounts.
## Step 2. Deploy the solution in your AWS GovCloud (US) Management account
1. Log in to the AWS GovCloud (US) Management account.
1. [Set up and verify AWS Organizations through email.](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_create.html)
1. Invite AWS GovCloud (US) LogArchive and Audit account to your [organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_invites.html).
1. Accept the invite by using [switch to the role for the member account](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html#orgs_manage_accounts_access-cross-account-role).
**Note**
The role is defined as `managementAccountAccessRole` in the global-config.yaml configuration file for the AWS standard Management account.
1. [Deploy the solution](deploy-the-solution.md) in the AWS GovCloud (US) Management account. The input into the installer stack for LogArchive and Audit accounts will be the AWS GovCloud (US) accounts vended from the linked AWS standard account. (This implementation guide uses ( [<[email@example.com](mailto:email@example.com)>](mailto:email@example.com)) and <[govCloud-log-archive-email@example.com](mailto:govCloud-log-archive-email@example.com)> ( [<[govCloud-log-archive-email@example.com](mailto:govCloud-log-archive-email@example.com)>](mailto:govCloud-log-archive-email@example.com)) as example accounts.)
## Step 3. Update the configuration file in your AWS standard account to create new AWS GovCloud (US) accounts
1. Using the AWS standard account, update the `accounts-config.yaml` file to have two new accounts with the `enableGovCloud` option, as shown in the following sample.
```
# commercial accounts-config.yaml
mandatoryAccounts:
- name: Management
description: >-
The management (primary) account. Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Root
- name: LogArchive
description: >-
The log archive account. Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Security
- name: Audit
description: >-
The security audit account (also referred to as the audit account). Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Security
workloadAccounts:
- name: LogArchiveGC # referred to as LogArchive in the GovCloud account-config.yaml
description: The log archive account for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
# this OU has all GovCloud accounts.
# OU was created from Control Tower
# in organization-config.yaml this OU was added.
organizationalUnit: GovCloud
# enableGovCloud is a one-time non-reversible option
# which only works with creation of new accounts
enableGovCloud: true
- name: AuditGC # referred to as Audit in the GovCloud account-config.yaml
description: The security audit account (also referred to as the audit account) for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: GovCloud
enableGovCloud: true
- name: SharedServicesGC # referred to as SharedServices in the GovCloud account-config.yaml
description: Shared services account for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: GovCloud
enableGovCloud: true
- name: NetworkGC # referred to as Network in the GovCloud account-config.yaml
description: Network account for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: GovCloud
enableGovCloud: true
```
1. After the commit, confirm that the pipeline runs successfully.
1. From the AWS GovCloud (US) mapping table, retrieve the AWS GovCloud (US) account ID for the **SharedServicesGC** and **NetworkGC** accounts.
## Step 4. Configure solution in AWS GovCloud (US) Region(s) to manage new accounts
1. Log in to the AWS GovCloud (US) Management account.
1. Add the **SharedServices** and **Network** accounts as shown in the following sample.
```
# govCloud accounts-config.yaml
mandatoryAccounts:
- name: Management
description: >-
The management (primary) account. Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Root
- name: LogArchive
description: >-
The log archive account. Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Security
- name: Audit
description: >-
The security audit account (also referred to as the audit account). Do not change the name field for this mandatory account.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Security
workloadAccounts:
- name: SharedServices
description: Shared services account for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Infrastructure
- name: Network
description: Network account for GovCloud.
email: <----- UPDATE EMAIL ADDRESS
organizationalUnit: Infrastructure
accountIds:
- email: <----- UPDATE EMAIL ADDRESS
accountId: '000000000000' <----- UPDATE GOVCLOUD ACCOUNT ID from Commercial GovCloud mapping table
- email: <----- UPDATE EMAIL ADDRESS
accountId: '111111111111' <----- UPDATE GOVCLOUD ACCOUNT ID from Commercial GovCloud mapping table
- email: <----- UPDATE EMAIL ADDRESS
accountId: '222222222222' <----- UPDATE GOVCLOUD ACCOUNT ID from Commercial GovCloud mapping table
- email: <----- UPDATE EMAIL ADDRESS
accountId: '333333333333'
- email: <----- UPDATE EMAIL ADDRESS
accountId: '444444444444'
```
1. After the commit, confirm that the pipeline runs successfully.
# Option 2: Deploy on new AWS GovCloud (US) accounts
Deploying the solution in this pattern allows users to have workloads in AWS GovCloud (US) Regions only. The standard Region on the left is used to create AWS GovCloud (US) using Service Catalog.
**Note**
This deployment assumes that you want to limit your use of standard AWS Regions, and it includes steps to incorporate AWS Organizations SCPs that limit what the AWS standard accounts can do. If you also want to use standard AWS Regions (such as a US DoD customer that wants to run IL2 workloads in AWS US East/West Regions and IL4/IL5 workloads in AWS GovCloud [US] Regions through a shared AWS standard Management billing account), AWS recommends that you create new AWS standard accounts specifically for AWS standard Region usage.
**Architecture diagram depicting AWS GovCloud (US) account deployment.**
![\[image11\]](http://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/images/image11.png)
## Step 1. Launch the stack
1. Ensure that all [prerequisites](prerequisites.md) are complete. Ensure that you’ve set up AWS Organizations and that the account where the stack is launched can run the `CreateGovCloudAccount` API. See For AWS Organizations based installation (without AWS Control Tower) for more information.
1. Sign in to the AWS Management Console of your organization’s management account and select the following button to launch the `AWSAccelerator-GovCloudAccountVending` AWS CloudFormation template.
[https://s3.amazonaws.com/solutions-reference/landing-zone-accelerator-on-aws/latest/AWSAccelerator-GovCloudAccountVending.template](https://s3.amazonaws.com/solutions-reference/landing-zone-accelerator-on-aws/latest/AWSAccelerator-GovCloudAccountVending.template) **AWSAccelerator-GovCloudAccountVending.template** - Use this template to launch the AWS GovCloud (US) account vending component.
1. On the **Create stack** page, verify that the correct template URL is in the **Amazon S3 URL** text box and choose **Next**.
1. On the **Specify stack details** page, assign a name to your solution stack. We recommend you name your stack `AWSAccelerator-GovCloudAccountVending` to match the naming convention used for additional stacks that the solution creates. For information about naming character limitations, refer to [IAM and STS quotas](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html) in the *AWS Identity and Access Management User Guide*.
1. Choose **Next**.
1. On the Configure stack options page, choose Next.
1. On the **Review** page, review and confirm the settings. Select the box acknowledging that the template will create IAM resources.
1. Choose **Create stack** to deploy the stack.
## Step 2. Use Service Catalog to launch the product
1. In the AWS Management Console upper left section, select **Services** and then select **Service Catalog**.
1. Ensure that the in-use IAM resource that has permissions to access the portfolio **Landing Zone Accelerator on AWS**. Refer to [Grant Access to Users](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/catalogs_portfolios_users.html) in Service Catalog Administrator Guide.
1. In the left-hand navigation menu, under **Provisioning**, choose **Products**.
1. In **Products**, choose a Landing Zone Accelerator on AWS - GovCloud Account Vending product and then **Launch product**.
1. In **Provisioned product name**, enter or generate a name (for example, `Landing_Zone_Accelerator_GovCloud_Account_LogArchive`).
1. In **Product versions**, choose a version of the product (for example, v1.0.0).
1. In **Parameters**, specify the following parameters:
+ **Account Name** - Name of account (for example, `Accelerator Log Archive` Account)
+ **Account Email** - Valid email address (for example, `example+log-archive@amazon.com`)
+ **Organization Role Name** - Name of the IAM role that AWS Organizations automatically pre-configures in the new member accounts in both the AWS GovCloud (US) Regions and in the standard Region (for example, `OrganizationAccountAccessRole`)
1. Choose **Launch product**.
1. On the **Review** page, review the configuration information, and select **LAUNCH**. This creates a CloudFormation stack. The initial status of the product is shown as **Under change**. Wait for about ten minutes, and then refresh the screen until the status changes to **AVAILABLE**.
## Step 3. Get account IDs
1. In the AWS Management Console upper left section, select **Services** and then select **Service Catalog**.
1. In the left-hand navigation menu, under **Provisioning**, choose **Provisioned products**.
1. In **Provisioned Products**, choose the product that you created in step 3.8.
1. Choose **Events**.
1. Under the **Provisioned products** output, get the `GovCloudAccountId` and `AccountId`, which correspond to the AWS GovCloud (US) account ID and standard account ID, respectively.
## Step 4. Deploy the solution in your AWS GovCloud (US) Management account
**Important**
Ensure that the [prerequisites](prerequisites-1.md) have been completed.
1. Log in to the AWS GovCloud (US) Management account.
1. Deploy the solution by following [Step 2 of Option 1](option-1-deploy-to-new-standard-and-aws-govcloud-us-accounts.md#step-2.-deploy-the-solution-in-your-aws-govcloud-us-management-account).
1. To add more accounts:
1. Follow [Step 2](#step-2-use-aws-service-catalog-to-launch-the-product) and [Step 3](#step-3.-get-account-ids) of [Option 2](#option-2-deploy-on-new-aws-govcloud-us-accounts).
1. Follow [Step 4 ](option-1-deploy-to-new-standard-and-aws-govcloud-us-accounts.md#step-4.-configure-solution-in-aws-govcloud-us-regions-to-manage-new-accounts)of [Option 1](option-1-deploy-to-new-standard-and-aws-govcloud-us-accounts.md).
# Option 3: Deploy on existing AWS GovCloud (US) accounts
If you don’t have access to a standard Region to create new AWS GovCloud (US) accounts, work with your third party to request them. Then follow the instructions in [Deploy the solution](deploy-the-solution.md).