diff --git a/aws/projects/aws-lza-poc/README.md b/aws/projects/aws-lza-poc/README.md index 6fc3d35c..bf2964b3 100644 --- a/aws/projects/aws-lza-poc/README.md +++ b/aws/projects/aws-lza-poc/README.md @@ -1,36 +1,42 @@ -# AWS Control Tower and Landing Zone Accelerator POC +# Landing Zone Accelerator on AWS -# Accounts +## Concepts and Terminology -## Commercial Organization Management Account (Payer Account) +- *GovCloud main account* - There is a special account in AWS GovCloud, the one that associated with the commercial managment account. +Depending on which [organization model](lza-govcloud-deployment.md) to use, it may or may not be a management account. +This account plays an important role in new GovCloud account joining organization. -* show SSO URL -* account id -* account alias + When a GovCloud account is created by LZA, no default IAM users are included. So, you cannot sign into the new GovCloud account as an IAM user. +Instead, A role (OrganizationAccountAccessRole or AWSControlTowerExecution when using ControlTower) is created. This role has administrator permissions in the new GovCloud account. To access the new GovCloud account, you must assume this role +from the special GovCloud account paired with the management account of the Commercial organization. -## Commercial LZA + To distingush this special GovCloud account from other management or member accounts, we will use "GovCloud main account" term for it in this document. -* account id -* account alias -* repository +- [GovCloud Organization Structure Models and LZA GovCloud Deployment Options](lza-govcloud-deployment.md) -## GovCloud Organization Management Account +- [How to access newly created GovCloud accounts?](access-new-govcloud-account.md) + +## Work With LZA -* show SSO URL -* account id -* account alias +- [Create AWS GovCloud Accounts Using LZA](create-govcloud-accounts.md) -## GovCloud LZA +## Links -* account id -* account alias -* repository +1. AWS Login URLs: + 1. Commercial Cloud: + 2. GovCloud main account management console: + 3. GovCloud Org1 (Mathews): + 4. GovCloud Org2 (Delong): +2. GitHub Enterprise repositories for LZA configuration files: + 1. LZA in commercial Cloud: + 2. LZA in GovCloud (Delong): +3. [Landing Zone Accelerator on AWS](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/solution-overview.html) +4. [Landing Zone Accelerator on AWS Source Code](https://github.com/awslabs/landing-zone-accelerator-on-aws) +5. [Trusted Secure Enclaves Sensitive Edition (TSE-SE) Reference Architecture](https://github.com/aws-samples/landing-zone-accelerator-on-aws-for-tse-se/tree/main/architecture-doc) -# Diagrams - -# Links - -# CHANGELOG +## CHANGELOG - 1.0.0 - 2024-10-04 - initial +- 1.0.1 - 2024-10-17 + - First draft diff --git a/aws/projects/aws-lza-poc/access-new-govcloud-account.md b/aws/projects/aws-lza-poc/access-new-govcloud-account.md new file mode 100644 index 00000000..d4a75938 --- /dev/null +++ b/aws/projects/aws-lza-poc/access-new-govcloud-account.md @@ -0,0 +1,19 @@ +# How to access newly created GovCloud accounts? + +No matter which method you use to create a GovCloud account, you end up calling `CreateGovCloudAccount` API eventually: + +![Alt text](images/CreateGovCloudAccount.png) + +You call this action from the management account of your organization in the Commercial Cloud to create a standalone AWS account in the AWS GovCloud. After the account is created, the management account of an organization in the AWS GovCloud can invite it to that organization. + +When you call the `CreateGovCloudAccount` action, you create two accounts: a standalone account in the AWS GovCloud and an associated account in the Commercial Cloud for billing and support purposes. The account in the Commercial Cloud is automatically a member of the organization whose credentials made the request. Both accounts are associated with the same email address. + +A role is created in the new account in the Commercial Cloud that allows the management account in the organization in the Commercial Cloud to assume it. An AWS GovCloud account is then created and associated with the Commercial account that you just created. A role is also created in the new AWS GovCloud account that can be assumed by the AWS GovCloud **main account** paired with the management account of the Commercial organization. The role has administrator permissions in the new member account. + +If you don’t specify the `RoleName` in the `CreateGovCloudAccount` call, the role name defaults to **OrganizationAccountAccessRole**. When using ControlTower, then the default role name is **AWSControlTowerExecution**. + +Newly created GovCloud accounts do not include default IAM users. To access a new GovCloud account, you must assume a role from the GovCloud **main account** that is linked to the Commercial management account. + +## References + +1. [`CreateGovCloudAccount` Action](https://docs.aws.amazon.com/organizations/latest/APIReference/API_CreateGovCloudAccount.html) diff --git a/aws/projects/aws-lza-poc/create-govcloud-accounts.md b/aws/projects/aws-lza-poc/create-govcloud-accounts.md new file mode 100644 index 00000000..8796767d --- /dev/null +++ b/aws/projects/aws-lza-poc/create-govcloud-accounts.md @@ -0,0 +1,152 @@ +# Create AWS GovCloud Accounts Using LZA + +## NOTES + +- There are multiple ways to deploy **LZA** in GovCloud. In this case, we chose the **LZA** deployment option 1 with the GovCloud organization structure model 2 described [here](lza-govcloud-deployment.md) for our test environment. +- The **LZA** code pipeline can be triggered by an event fired when the **LZA** configuration source is changed. The **LZA** configuration source can be either a Git repository or an **S3** bucket. Previously, an **AWS CodeCommit** repository was the default configuration source, but with **AWS CodeCommit** is now deprecated, the preferred option is an **S3** bucket. + + Although using a **GitHub Enterprise** repository would be ideal, there are still technical challenges in connecting the **LZA** code pipeline with a **GitHub Enterprise** repository. +- Two GovCloud organizations have been set up. The management accounts for these organizations are: GovMgmt (125491008078) and GovMgmt1 (245311545213). +- The commercial management account (899421254963) and GovMgmt (125491008078) account were created before July 24, 2024 and the CodeCommit should still work. +- The GovMgmt1 (245311545213) account was created after July 24, 2024 and the CodeCommit is disabled. + +## Actions in Commercial Cloud + +1. Sign in to the AWS Identity Center of the commercial management account: +2. Expand the 'US Census Org Dev' account by clicking on it, then click on 'AWSAdministratorAccess' role link: + + ![Management Account](images/create-govcloud-accounts/US-Census-Org-Dev.png) + + **NOTE**: If the 'AWSAdministratorAccess' role is not assigned to your account, assume any role that has the necessary permissions to operate the AWS CodePipeline. +3. If you haven't done so already, clone the commercial **LZA** configuration repository on Census GitHub Enterprise server: : + + ```txt + git clone git@github.e.it.census.gov:SCT-Engineering/aws-accelerator-config-com.git + ``` + + **NOTE**: This repository contains all the configuration files we use in the **LZA** deployed in the commercial cloud. Currently, it serves solely to maintain the history of the configuration files and is not required by the **LZA** code pipeline. +4. Navigate to the local directory where you cloned the configuration files. Open the `accounts-config.yaml` file in an editor, and add one or more new account definitions to the end of the `workloadAccounts` section. + e.g. + + ```yaml + - name: GovDev1 + description: Dev account for GovCloud. + email: awsnewaccount+GovDev1@census.gov + organizationalUnit: GovCloud + enableGovCloud: true + ``` + + *name* - Name of the account to create. + *description* - A brief description of the account's purpose. + *email* - Account email address. It must be unique. + *organizationUnit* - Organization unit where the account will belong to. + *enableGovCloud* - Flag to indicate if a paired GovCloud account will be created as well. + + Save your changes. +5. Update the configuration source of the **LZA** code pipeline + + 1. If **AWS CodeCommit** repository is used as the configuration source of the **LZA** code pipeline, commit the changes made to your local Git repository in previous step and push the commit to the **AWS CodeCommit** repository named `aws-accelerator-config`. + Follow these instructions[instructions](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up.html) to set up the AWS CodeCommit connection. + + You can also directly edit the configuration files within **AWS Mangement Console**. If you make changes this way, please remember to update your local files as well. + 2. If an **AWS S3** bucket is the source, then zip all the files and directories (excluding '.git' directory) in the local configuration directory, name the zip file `aws-accelerator-config.zip`, and upload it to the `zipped` folder of the `aws-accelerator-config-899421254963-us-gov-east-1` **S3** bucket (Currently, this **S3** bucket doesn't exist. An **AWS CodeCommit** repository is used). + + Also push the commit to the [commercial **LZA** configuration GitHub repository](https://github.e.it.census.gov/SCT-Engineering/aws-accelerator-config-com). +6. When the configuration source of the **LZA** code pipeline is updated, + an EventBridge event will be fired which will then kick of the **LZA** code pipeline. + + Navigate to the AWS code pipeline named 'AWSAccelerator-Pipeline' to monitor its progress. + + ![AWSAccelerator-Pipeline](images/create-govcloud-accounts/pipeline.png) + + You will receive an notification email when the pipeline requires approval. +7. After the pipeline finishes successfully, go to the **AWS Parameter Store** and search for '/accelerator/prepare-stack/govCloudAccountMappingTableName' parameter. The value of this parameter is the DynamoDB table name where the newly created GovCloud account ID(s) are stored. + + ![GovCloud Accounti Mapping Table Name](images/create-govcloud-accounts/mapping-table-name.png) + Copy the parameter value. +8. Navigate to the DynamoDB Tables page and search for the table with the name we just copied. Click on the table name to view its overview. + On the table overview page, click on 'Explore table items' button. + + ![DynamoDB table](images/create-govcloud-accounts/dynamoDB.png) + + Locate the newly created account(s) and note down their account names and GovCloud account ID(s). We will need this information when adding them to the GovCloud organization. + + ![GovCloud Account IDs](images/create-govcloud-accounts/govcloud-account-ids.png) + + The GovCloud account IDs can also be obtained using the following CIL command: + > aws orgainziation list-create-account-status --output table + +## Actions in GovCloud + +1. Log into the AWS Management Console of the GovCloud main account paired with the commercial management account: . +2. Switch role into one of the newly created GovCloud accounts. You will need the account ID noted in the last action taken in the commercial management account. The role name is 'AWSControlTowerExecution'. + + ![Switch Role](images/create-govcloud-accounts/switch-role.png) +3. Go to **AWS IAM** and navigate to 'Roles' page. Search for the 'AWSControlTowerExecution' role. Click on the role name when it appears in the search results. Then click on the 'Trust relationships' tab and followed by the 'Edit trust policy' button. + + ![AWSControlTowerExecution Role](images/create-govcloud-accounts/awscontroltowerexecution-role.png) + + On the right side of the page, click 'Add' button to the right of 'Add a principal'. + + ![Add Principal](images/create-govcloud-accounts/add-principal1.png) + + In the popup window, select 'AWS account and root user' as the 'Principal type'. Additionally, replace the '{Account}' portion in the ARN with the account ID of the GovCloud management account (245311545213) in which the organization the new account will join. + + ![Add Principal](images/create-govcloud-accounts/add-principal2.png) + + Then click 'Add principal' button at the bottome right, followed by the 'Update policy' button on the next page to save the changes. + + You can now switch back to the GovCloud main account. +4. Repeat step 2&3 if multple GovCloud accounts were created. +5. Sign in to the AWS Identity Center of the GovCloud management account: +6. Expand the management account name ('GovMgmt1') by clicking on it, then click on 'AWSAdministratorAccess' role link: + + !['Management Account'](images/create-govcloud-accounts/govmgmt1.png) + +7. If you haven't done so already, clone the GovCloud **LZA** configuration repository on Census GitHub Enterprise server: : + + ```txt + git clone git@github.e.it.census.gov:SCT-Engineering/aws-accelerator-config-gov1.git + ``` + +8. Navigate to the local directory where you cloned the configuration files. Open the `accounts-config.yaml` file in an editor, and add one or more new account definitions to the end of the `workloadAccounts` section. + e.g. + + ```yaml + - name: GovDev1 + description: Dev account for GovCloud. + email: awsnewaccount+GovDev1@census.gov + organizationalUnit: GovCloud + ``` + + name - Name of the account. + description - A short description of the account. + email - Account email address. It should match that of the paired account on the commercial cloud side. + organizationUnit - Organization unit the account will resides. + + Additionally, add the account email and ID to the `accountIds` section. + + e.g. + + ```yaml + - email: awsnewaccount+GovDev1@census.gov + accountId: '245279194929' + ``` + + The `accountIds` section enables LZA to invite the accounts into the organization. + + Save your changes. +9. Update the configuration source of the **LZA** code pipeline + 1. If **AWS CodeCommit** repository is used as the configuration source of the **LZA** code pipeline, commit the changes made to your local Git repository in previous step and push the commit to the **AWS CodeCommit** repository named `aws-accelerator-config`. + + You can also directly edit the configuration files within **AWS Mangement Console**. If you make changes this way, please remember to update your local files as well. + 2. If an **AWS S3** bucket is the source, then zip all the files and directories (excluding '.git' directory) in the local configuration directory, name the zip file `aws-accelerator-config.zip`, and upload it to the `zipped` folder of the `aws-accelerator-config-245311545213-us-gov-east-1` **S3** bucket. + + Also push the commit to the [GovCloud **LZA** configuration GitHub repository](https://github.e.it.census.gov/SCT-Engineering/aws-accelerator-config-gov). +10. When the configuration source of the **LZA** code pipeline is updated, + an EventBridge event will be fired which will then kick of the **LZA** code pipeline. + + Navigate to the AWS code pipeline named 'AWSAccelerator-Pipeline' to monitor its progress. + + ![AWSAccelerator-Pipeline](images/create-govcloud-accounts/pipeline.png) +11. After the pipeline finishes successfully, go to the **AWS Organization** to verify that all the new accounts have joined the organization and are put in the correct **OU**. diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/CreateGovCloudAccount.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/CreateGovCloudAccount.png new file mode 100644 index 00000000..c9145ceb Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/CreateGovCloudAccount.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/US-Census-Org-Dev.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/US-Census-Org-Dev.png new file mode 100644 index 00000000..9ede703d Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/US-Census-Org-Dev.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal1.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal1.png new file mode 100644 index 00000000..804cd4b3 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal1.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal2.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal2.png new file mode 100644 index 00000000..a7eaa4d1 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal2.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/awscontroltowerexecution-role.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/awscontroltowerexecution-role.png new file mode 100644 index 00000000..d0f1539e Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/awscontroltowerexecution-role.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/dynamoDB.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/dynamoDB.png new file mode 100644 index 00000000..c1f5bb8d Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/dynamoDB.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/govcloud-account-ids.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/govcloud-account-ids.png new file mode 100644 index 00000000..e260fe15 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/govcloud-account-ids.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/govmgmt1.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/govmgmt1.png new file mode 100644 index 00000000..b21758ca Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/govmgmt1.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/mapping-table-name.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/mapping-table-name.png new file mode 100644 index 00000000..ef254a41 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/mapping-table-name.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/pipeline.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/pipeline.png new file mode 100644 index 00000000..e50f9cbd Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/pipeline.png differ diff --git a/aws/projects/aws-lza-poc/images/create-govcloud-accounts/switch-role.png b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/switch-role.png new file mode 100644 index 00000000..d4a7dfea Binary files /dev/null and b/aws/projects/aws-lza-poc/images/create-govcloud-accounts/switch-role.png differ diff --git a/aws/projects/aws-lza-poc/images/deployment-options/model1.png b/aws/projects/aws-lza-poc/images/deployment-options/model1.png new file mode 100644 index 00000000..df69e8c0 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/deployment-options/model1.png differ diff --git a/aws/projects/aws-lza-poc/images/deployment-options/model2.png b/aws/projects/aws-lza-poc/images/deployment-options/model2.png new file mode 100644 index 00000000..8852dd60 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/deployment-options/model2.png differ diff --git a/aws/projects/aws-lza-poc/images/deployment-options/option1-model1.png b/aws/projects/aws-lza-poc/images/deployment-options/option1-model1.png new file mode 100644 index 00000000..1e8ea0e2 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/deployment-options/option1-model1.png differ diff --git a/aws/projects/aws-lza-poc/images/deployment-options/option1-model2.png b/aws/projects/aws-lza-poc/images/deployment-options/option1-model2.png new file mode 100644 index 00000000..b9c45dea Binary files /dev/null and b/aws/projects/aws-lza-poc/images/deployment-options/option1-model2.png differ diff --git a/aws/projects/aws-lza-poc/images/deployment-options/option2-model1.png b/aws/projects/aws-lza-poc/images/deployment-options/option2-model1.png new file mode 100644 index 00000000..bd098581 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/deployment-options/option2-model1.png differ diff --git a/aws/projects/aws-lza-poc/images/deployment-options/option2-model2.png b/aws/projects/aws-lza-poc/images/deployment-options/option2-model2.png new file mode 100644 index 00000000..9924dd45 Binary files /dev/null and b/aws/projects/aws-lza-poc/images/deployment-options/option2-model2.png differ diff --git a/aws/projects/aws-lza-poc/lza-govcloud-deployment.md b/aws/projects/aws-lza-poc/lza-govcloud-deployment.md new file mode 100644 index 00000000..01d07f02 --- /dev/null +++ b/aws/projects/aws-lza-poc/lza-govcloud-deployment.md @@ -0,0 +1,67 @@ +# GovCloud Organization Structure Models and LZA GovCloud Deployment Options + +## GovCloud Organization Structure Models + +### Model 1 + +In this model, there exists only one GovCloud organization. The GovCloud organization is established within the GovCloud management account paired with the commercial management account housing the commercial organization. This setup maintains a streamlined relationship between the management accounts of both sides, facilitating easier management. + +![Model 1](images/deployment-options/model1.png) + +### Model 2 + +n this model, you have the flexibility to create multiple GovCloud organizations. These GovCloud organizations are established within the GovCloud accounts, each mapped to a respective commercial MEMBER account. The main GovCloud account mapped to the commercial management account is not utilized for organizational purposes. As there is only one commercial organization, and all billing for GovCloud accounts is routed through their paired commercial accounts, billing is centralized solely in the commercial management account. + +![Model 2](images/deployment-options/model2.png) + +## Three LZA GovCloud Deployment Options + +- Option 1 – Deploy to new standard (commercial) 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 – 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 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 – 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, then you can deploy the solution. + +## LZA Deployment Options with Different Organization Structure Models + +### Option 1 <-> Model 1 + +You deploy LZA to both your commercial management account and GovCloud management account, utilizing it for managing your organization account structure on both sides. Specifically, on the GovCloud side, LZA is deployed into the management account paired with the commercial management account. Notably, only one organization is created in the GovCloud. + +![Option1 and Model 1](images/deployment-options/option1-model1.png) + +### Option 1 <-> Model 2 + +You deploy LZA to both your commercial management account and GovCloud management account(s), utilizing it for managing your organization account structure on both sides. On the GovCloud side, LZA is deployed into the management account of each organization (NOTE: the GovCloud management accounts of model 2 are paired with commercial MEMBER accounts). + +![Option1 and Model 2](images/deployment-options/option1-model2.png) + +### Option 2 <-> Model 1 + +You're not managing your commercial organization account structure with LZA. However, you do have access to the commercial management account and can deploy resources within it. Within this setup, you deploy AWSAccelerator-GovCloudAccountVending in the commercial management account, initiating the creation of a Service Catalog product upon execution. Subsequently, you can utilize this product to generate GovCloud accounts. + +You deploy LZA only to the GovCloud management account paired with the commercial management account. You use LZA to manage your organization account structure on GovCloud side only. Notably, there exists only one organization in the GovCloud. + +![Option2 and Model 1](images/deployment-options/option2-model1.png) + +### Option 2 <-> Model 2 + +You're not using LZA to manage your commercial organization's account structure. However, you do have access to the commercial management account and can deploy resources within it. In this setup, AWSAccelerator-GovCloudAccountVending is deployed in the commercial management account, which triggers the creation of a Service Catalog product upon execution. You can then use this product to generate GovCloud accounts. + +LZA deployment is exclusively for GovCloud and is implemented in the GovCloud management account(s). + +![Option2 and Model 2](images/deployment-options/option2-model2.png) + +### Option 3 + +This deployment option closely resembles option 2, with one key distinction: you lack access to the commercial management account and cannot deploy an account vending machine into it. Instead, you depend on the entity managing your commercial environment to create new GovCloud accounts on your behalf. + +## LZA Deployment and Update + +The detailed LZA deployment guide can be found in [Landing Zone Accelerator on AWS](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/deploy-the-solution.html). Make sure all the prerequisites are met before delploying LZA. + +## References + +1. [AWS Organizations now available in the AWS GovCloud (US) Regions for central governance and management of AWS accounts](https://aws.amazon.com/blogs/security/aws-organizations-available-govcloud-regions-central-governance-management-accounts/) + +2. [Deployment options for AWS GovCloud (US) workloads](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/deployment-options-for-aws-govcloud-us-workloads.html)