From 8166c7459092d89d95487b90c9762c7911cdeda8 Mon Sep 17 00:00:00 2001 From: Delong Yang Date: Thu, 17 Oct 2024 08:19:48 -0400 Subject: [PATCH] First draft of LZA doc --- aws/projects/aws-lza-poc/README.md | 52 +++--- .../access-new-govcloud-account.md | 19 +++ .../aws-lza-poc/create-govcloud-accounts.md | 152 ++++++++++++++++++ .../CreateGovCloudAccount.png | Bin 0 -> 14917 bytes .../US-Census-Org-Dev.png | Bin 0 -> 24812 bytes .../add-principal1.png | Bin 0 -> 67625 bytes .../add-principal2.png | Bin 0 -> 28161 bytes .../awscontroltowerexecution-role.png | Bin 0 -> 73364 bytes .../create-govcloud-accounts/dynamoDB.png | Bin 0 -> 155882 bytes .../govcloud-account-ids.png | Bin 0 -> 47705 bytes .../create-govcloud-accounts/govmgmt1.png | Bin 0 -> 19927 bytes .../mapping-table-name.png | Bin 0 -> 66688 bytes .../create-govcloud-accounts/pipeline.png | Bin 0 -> 73483 bytes .../create-govcloud-accounts/switch-role.png | Bin 0 -> 21959 bytes .../images/deployment-options/model1.png | Bin 0 -> 68408 bytes .../images/deployment-options/model2.png | Bin 0 -> 80248 bytes .../deployment-options/option1-model1.png | Bin 0 -> 52602 bytes .../deployment-options/option1-model2.png | Bin 0 -> 76217 bytes .../deployment-options/option2-model1.png | Bin 0 -> 51834 bytes .../deployment-options/option2-model2.png | Bin 0 -> 75553 bytes .../aws-lza-poc/lza-govcloud-deployment.md | 67 ++++++++ 21 files changed, 267 insertions(+), 23 deletions(-) create mode 100644 aws/projects/aws-lza-poc/access-new-govcloud-account.md create mode 100644 aws/projects/aws-lza-poc/create-govcloud-accounts.md create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/CreateGovCloudAccount.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/US-Census-Org-Dev.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal1.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/add-principal2.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/awscontroltowerexecution-role.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/dynamoDB.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/govcloud-account-ids.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/govmgmt1.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/mapping-table-name.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/pipeline.png create mode 100644 aws/projects/aws-lza-poc/images/create-govcloud-accounts/switch-role.png create mode 100644 aws/projects/aws-lza-poc/images/deployment-options/model1.png create mode 100644 aws/projects/aws-lza-poc/images/deployment-options/model2.png create mode 100644 aws/projects/aws-lza-poc/images/deployment-options/option1-model1.png create mode 100644 aws/projects/aws-lza-poc/images/deployment-options/option1-model2.png create mode 100644 aws/projects/aws-lza-poc/images/deployment-options/option2-model1.png create mode 100644 aws/projects/aws-lza-poc/images/deployment-options/option2-model2.png create mode 100644 aws/projects/aws-lza-poc/lza-govcloud-deployment.md 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 0000000000000000000000000000000000000000..c9145ceb173ec02d5f8fe5c878c18d9bff97786b GIT binary patch literal 14917 zcmch;XH-+)zwR55CZK?HL_m6rbdU}r5Sk#J(3Bpk^j@S%lb+C(?|~bCd;iba&J+_Sp(@T}rKD{WC~s@!dj z!Z+>mnTkgRJL`oLKPSW-M~8-`Lq}K5k1Lm?#U>8DM%TyA{Z6%S;@L5Gn#? z%C7_%cHHH=+i+D%0_CUFphVo=IPO$BWl91n9X6zAQmfg1Ucrx^vL=@vsa>tWUk%8` z^@0qWi)gDiY$P@$rG{XkISK1w+0qBA392)5f-C_xb=hBkP^mESaQDXksHGu`+O