Skip to content

feat: add support for AWS China regions #794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
danxie1999 wants to merge 3 commits into
base: master
Choose a base branch
from
Open

feat: add support for AWS China regions #794

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8627be4
feat: add support for AWS China region
danxie1999 Mar 4, 2025
ba03038
Fix the MegaLinter and add pytest for China code
danxie1999 Mar 26, 2025
72f4e02
Fix the china extra stack deletion issue.
danxie1999 Apr 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions docs/admin-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,9 @@ definitions in them as desired.
## adfconfig

The `adfconfig.yml` file resides on the
[management account](#management-account) CodeCommit Repository (in `us-east-1`)
and defines the general high-level configuration for the AWS Deployment
Framework.
[management account](#management-account) CodeCommit Repository
(in `us-east-1` or `cn-north-1`) and defines the general
high-level configuration for the AWS Deployment Framework.

The configuration properties are synced into AWS Systems Manager Parameter
Store and are used for certain orchestration options throughout your
Expand Down Expand Up @@ -964,8 +964,8 @@ To determine the current version, follow these steps:
### ADF version you have deployed

To check the current version of ADF that you have deployed, go to the management
account in us-east-1. Check the CloudFormation stack output or tag of the
`serverlessrepo-aws-deployment-framework` Stack.
account in us-east-1 or cn-north-1. Check the CloudFormation stack
Copy link
Collaborator

@sbkok sbkok Jul 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of adding cn-north-1 everywhere where us-east-1 is used, I would like to suggest we add a mapping table at the top to explain what values to use for each partition.

Otherwise we should also add the us-gov region everywhere, in case that partition is used.
For the US-Gov partition, the region they should deploy to is us-gov-west-1.

output or tag of the `serverlessrepo-aws-deployment-framework` Stack.

- In the outputs tab, it will show the version as the `ADFVersionNumber`.
- In the tags on the CloudFormation stack, it is presented as
Expand All @@ -985,8 +985,8 @@ releases](https://github.com/awslabs/aws-deployment-framework/releases).
The `serverlessrepo-aws-deployment-framework` stack is updated through this
process with new changes that were included in that release of ADF.

To check the progress in the management account in `us-east-1`, follow these
steps:
To check the progress in the management account in
`us-east-1` or `cn-north-1`, follow these steps:

1. Go to the [CloudFormation
console](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks?filteringStatus=active&filteringText=serverlessrepo-aws-deployment-framework&viewNested=true&hideStacks=false)
Expand Down Expand Up @@ -1028,7 +1028,7 @@ Which branch is used is determined by:

Alternatively, you can also perform the update using the AWS CLI.

In the management account in `us-east-1`:
In the management account in `us-east-1` or `cn-north-1`:

1. Go to the Pull Request section of the `aws-deployment-framework-bootstrap`
[CodeCommit
Expand All @@ -1043,7 +1043,7 @@ In the management account in `us-east-1`:
changes that it proposes. Once reviewed, merge the pull request to continue.

Confirm the `aws-deployment-framework-bootstrap` pipeline in the management
account in `us-east-1`:
account in `us-east-1` or `cn-north-1`:

1. Go to the [CodePipeline console for the aws-deployment-framework-bootstrap
pipeline](https://console.aws.amazon.com/codesuite/codepipeline/pipelines/aws-deployment-framework-bootstrap-pipeline/view?region=us-east-1).
Expand All @@ -1059,7 +1059,7 @@ creation and on-boarding process in parallel.
These are managed through Step Function state machines.

1. Navigate to the [AWS Step Functions service](https://us-east-1.console.aws.amazon.com/states/home?region=us-east-1#/statemachines)
in the management account in `us-east-1`.
in the management account in `us-east-1` or `cn-north-1`.
2. Check the `AccountManagementStateMachine...` state machine, all recent
invocations since we performed the update should succeed. It could be the
case that there are no invocations at all. In that case, wait a minute and
Expand Down Expand Up @@ -1138,10 +1138,11 @@ Alternatively, you can also perform the update using the AWS CLI.

If you wish to remove ADF you can delete the CloudFormation stack named
`serverlessrepo-aws-deployment-framework` in the management account in
the `us-east-1` region. This will remove most resources created by ADF
the `us-east-1` region for global partition deployments; for China deployments
in `cn-north-1` region. This will remove most resources created by ADF
in the management account. With the exception of S3 buckets and SSM parameters.
If you bootstrapped ADF into the management account you need to manually remove
the bootstrap stacks as well.
If you bootstrapped ADF into the management account you need to manually
remove the bootstrap stacks as well.

Feel free to delete the S3 buckets, SSM parameters that start with the `/adf`
prefix, as well as other CloudFormation stacks such as:
Expand All @@ -1164,7 +1165,7 @@ the base stack when the account is moved to the Root of the AWS Organization.
One thing to keep in mind if you are planning to re-install ADF is that you
will want to clean up the parameter from SSM Parameter Store. You can safely
remove all `/adf` prefixed SSM parameters. But most importantly, you need to
remove the `/adf/deployment_account_id` in `us-east-1` on the
remove the `/adf/deployment_account_id` in `us-east-1` or `cn-north-1` on the
management account.
As AWS Step Functions uses this parameter to determine if ADF has already got a
deployment account setup. If you re-install ADF with this parameter set to a
Expand All @@ -1187,7 +1188,7 @@ There are two ways to enable this:
to deploy the latest version again, set the `Log Level` to `DEBUG` to get
extra logging information about the issue you are experiencing.
2. If you are running an older version of ADF, please navigate to the
CloudFormation Console in `us-east-1` of the AWS Management account.
CloudFormation Console in `us-east-1` or `cn-north-1` of the AWS Management account.
3. Update the stack.
4. For any ADF deployment of `v3.2.0` and later, please change the `Log Level`
parameter and set it to `DEBUG`. Deploy those changes and revert them after
Expand All @@ -1202,7 +1203,7 @@ Please trace the failed component and dive into/report the debug information.

The main components to look at are:

1. In the AWS Management Account in `us-east-1`:
1. In the AWS Management Account in `us-east-1` or `cn-north-1`:
2. The [CloudFormation aws-deployment-framework stack](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks?filteringStatus=active&filteringText=aws-deployment-framework&viewNested=true&hideStacks=false).
3. The [CloudWatch Logs for the Lambda functions deployed by ADF](https://console.aws.amazon.com/lambda/home?region=us-east-1#/functions?f0=true&n0=false&op=and&v0=ADF).
4. Check if the [CodeCommit pull
Expand All @@ -1211,8 +1212,8 @@ The main components to look at are:
branch for the `aws-deployment-framework-bootstrap` (ADF Bootstrap) repository.
5. The [CodePipeline execution of the AWS Bootstrap pipeline](https://console.aws.amazon.com/codesuite/codepipeline/pipelines/aws-deployment-framework-bootstrap-pipeline/view?region=us-east-1).
6. Navigate to the [AWS Step Functions service](https://us-east-1.console.aws.amazon.com/states/home?region=us-east-1#/statemachines)
in the management account in `us-east-1`. Check the state machines named
`AccountManagementStateMachine...` and
in the management account in `us-east-1` or `cn-north-1`. Check the
state machines named `AccountManagementStateMachine...` and
`AccountBootstrappingStateMachine...`. Look at recent executions only.
- When you find one that has a failed execution, check the components that
are marked orange/red in the diagram.
Expand Down
28 changes: 15 additions & 13 deletions docs/installation-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ It is okay to install ADF and AWS Control Tower in different regions.
For example:

- Install AWS Control Tower in `eu-central-1`.
- Install ADF in `us-east-1`.
- Install ADF in `us-east-1` or `cn-north-1`.
Copy link
Collaborator

@sbkok sbkok Jul 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does that work, having AWS Control Tower deployed in eu-central-1 while deploying ADF in cn-north-1?


**If you want to use ADF and AWS Control Tower, we recommend that you setup
AWS Control Tower prior to installing ADF.**
Expand All @@ -44,12 +44,12 @@ Ensure you have setup [AWS CloudTrail](https://aws.amazon.com/cloudtrail/)
regions**, the trail itself can be created in any region. Events [triggered via
CloudTrail](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_incident-response.html)
for AWS Organizations can only be acted upon in the us-east-1 (North Virginia)
region.
or cn-northwest-1 region.
Copy link
Collaborator

@sbkok sbkok Jul 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this correct? This is the first time you reference cn-northwest-1. Everywhere else where us-east-1 was stated in the docs you referenced cn-north-1. Can you please check if this is the right one to use here?


Please use the [AWS CloudTrail
instructions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
to configure the CloudTrail in the `us-east-1` region within the AWS
Organizations Management AWS Account.
to configure the CloudTrail in the `us-east-1` or `cn-north-1` region
within the AWS Organizations Management AWS Account.

### 1.2. Enable AWS Organizations API Access

Expand Down Expand Up @@ -289,10 +289,10 @@ or applications into via AWS CodePipeline *(this can be updated later)*.

When deploying ADF for the first time, part of the installation process will
automatically create an AWS CodeCommit repository in the management AWS Account
within the `us-east-1` region. It will also make the initial commit to the
default branch of this repository with a default set of examples that act as a
starting point to help define the AWS Account bootstrapping processes for your
Organization.
within the `us-east-1` or `cn-north-1` region. It will also make the initial
commit to the default branch of this repository with a default set of
examples that act as a starting point to help define the AWS Account
bootstrapping processes for your Organization.

Part of the questions that follow will end up in the initial commit into the
repository. These are passed directly the `adfconfig.yml` file prior to it
Expand Down Expand Up @@ -330,7 +330,7 @@ To gather the values, you can either find them in the
`aws-deployment-framework-bootstrap` repository in the `adfconfig.yml`
file. Or by looking up the values that were specified the last time ADF got
installed/updated via the CloudFormation template parameters of the
`serverlessrepo-aws-deployment-framework` stack in `us-east-1`.
`serverlessrepo-aws-deployment-framework` stack in `us-east-1` or `cn-north-1`.

#### Stack Name

Expand All @@ -352,6 +352,7 @@ Value to use depends on the AWS partition it is deployed to:

- For the AWS partition (most common), use; `us-east-1`
- For the US-Gov partition, use: `us-gov-west-1`
- For the China partition, use `cn-north-1`

**Explanation:**
ADF needs to be deployed in the region where the control plane of the
Expand Down Expand Up @@ -517,7 +518,7 @@ This can always be updated later via the `adfconfig.yml` file.

You don't need to include the main region in this list. For example, if you
use the example values for the default region and target regions, it will allow
pipelines to deploy to `eu-west-1`, `eu-central-`, and `us-east-1`.
pipelines to deploy to `eu-west-1`, `eu-central-`, `cn-north-1` and `us-east-1`.
Copy link
Collaborator

@sbkok sbkok Jul 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AWS does not support deploying cross multiple partitions as far as I know.
Listing cn-north-1 here makes it look like ADF does support this. I would recommend to remove cn-north-1 in this line, and fix the missing number on eu-central- with this suggestion:

Suggested change
pipelines to deploy to `eu-west-1`, `eu-central-`, `cn-north-1` and `us-east-1`.
pipelines to deploy to `eu-west-1`, `eu-central-1`, and `us-east-1`.


*This is not required when performing an update between versions of ADF.*
*Only supported when installing ADF for the first time.
Expand Down Expand Up @@ -647,8 +648,9 @@ automatically in the background, to follow its progress:

1. Please navigate to the AWS Console in the AWS Management account.
As the stack `serverlessrepo-aws-deployment-framework` completes you can now
open AWS CodePipeline from within the management account in `us-east-1` and
see that there is an initial pipeline execution that started.
open AWS CodePipeline from within the management account in `us-east-1`
or `cn-north-1` and see that there is an initial pipeline
execution that started.

Upon first installation, this pipeline might fail to fetch the source
code from the repository. Click the retry failed action button to try again.
Expand Down Expand Up @@ -693,7 +695,7 @@ automatically in the background, to follow its progress:
that started the bootstrap process for the deployment account. You can view
the progress of this in the management account in the AWS Step Functions
console for the step function `AccountBootstrappingStateMachine-` in the
`us-east-1` region.
`us-east-1` or `cn-north-1` region.

3. Once the Step Function has completed, switch roles over to the newly
bootstrapped deployment account in the region you defined as your main
Expand Down
2 changes: 1 addition & 1 deletion docs/samples-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Management Account. By default, there is a `global.yml` in the root of the
be appended to as required.

If we look at AWS Step Functions in the management account in `us-east-1`
we can see the progress of the bootstrap process.
or `cn-north-1` we can see the progress of the bootstrap process.

![run-state-machine](./images/run-state-machine.png)

Expand Down
2 changes: 2 additions & 0 deletions docs/user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -980,6 +980,8 @@ There are five different styles that one could choose from.
method](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html).
- In case the bucket is stored in `us-east-1`, it will return:
`https://s3.amazonaws.com/${bucket}/${key}`
- In case the bucket is stored in `cn-north-1` or `cn-northwest-1`, it will return:
`https://${bucket}.s3.${region}.amazonaws.cn/${key}`
- In case the bucket is stored in any other region, it will return:
`https://s3-${region}.amazonaws.com/${bucket}/${key}`
- `virtual-hosted` style, will return the S3 location using the virtual hosted
Expand Down
6 changes: 5 additions & 1 deletion src/lambda_codebase/initial_commit/bootstrap_repository/adf-bootstrap/deployment/global.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -809,6 +809,10 @@ Resources:
commands:
- aws s3 cp s3://$SHARED_MODULES_BUCKET/adf-build/ ./adf-build/ --recursive --only-show-errors
- aws s3 cp --sse aws:kms --sse-kms-key-id $ADF_PIPELINE_ASSET_KMS_ARN ./adf-build/templates/ s3://$ADF_PIPELINE_ASSET_BUCKET/adf-build/templates/ --recursive --only-show-errors
- |
if [ "${AWS::Region}" = "cn-north-1" ]; then
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
fi
- pip install -r adf-build/requirements.txt -r adf-build/helpers/requirements.txt -q -t ./adf-build
pre_build:
commands:
Expand Down Expand Up @@ -1193,7 +1197,7 @@ Resources:
StringEquals:
aws:PrincipalOrgID: !Ref OrganizationId
ArnLike:
aws:PrincipalArn: 'arn:aws:iam::*:role/adf-codecommit-role'
aws:PrincipalArn: !Sub 'arn:${AWS::Partition}:iam::*:role/adf-codecommit-role'
Resource:
- !Sub arn:${AWS::Partition}:s3:::${PipelineBucket}/*
Principal:
Expand Down
Loading