Version:

Deploying the AWS CDK Application

The AWS Cloud Development Kit (AWS CDK) is a software development framework from AWS for defining cloud infrastructure for your project and provisioning it through AWS CloudFormation.

Note:

The AWS Gems have been updated to support AWS CDK v2,the new long term AWS CDK version. AWS CDK v1 entered maintenance on June 1, 2022, and will now receive only critical bug fixes and security patches.

For those still using the AWS CDK v1, a legacy snapshot of the sample applications are available in a cdkv1 folder inside each Gem. See the AWS CDK Migration Guide for advice about how to migrate legacy AWS CDK applications to the AWS CDK v2.

The AWS Core Gem includes an optional Python AWS CDK application that provides two stacks:

  1. A core stack to use as the basis for a project’s AWS CDK application.
  2. An example stack with example resources that can be connected to ScriptBehavior samples in Core.

The Python project is set up like a standard Python project. The initialization process uses virtual environments, created with virtualenv and stored under the .venv directory.

To create the virtual environment, you must have a python3 executable (or python for Windows) in your path with access to the venv package. If the automatic creation of the virtualenv fails, you can create the virtualenv manually.

Prerequisites

Working with the AWS CDK application

There are a few one-time set up steps to prepare for your first AWS CDK deployment. The following commands should all be run from the cdk directory of the Gem you’re working with.

1. Set up Python environment

For the latest instructions, refer to the README.MD located in <engine root>\Gems\AWSCore\cdk.

  1. Open a command prompt to the cdk directory of the Gem you’re working with.

    cd <ENGINE_ROOT>\Gems\<AWS_GEM>\cdk
    

    For example when deploying the AWS CDK application for AWS Core Gem

    cd <ENGINE_ROOT>\Gems\AWSCore\cdk
    
  2. Create a virtualenv.

    # Windows
    python -m venv .venv
    
    # Mac or Linux
    python3 -m venv .venv
    
  3. Activate your virtualenv.

    # Windows
    .venv\Scripts\activate.bat
    
    # Mac or Linux
    source .venv/bin/activate
    
  4. Install the required dependencies.

    # Windows
    pip install -r requirements.txt
    
    # Mac or Linux
    pip3 install -r requirements.txt
    

2. Set environment variables or accept defaults

VariableDescription
O3DE_AWS_DEPLOY_REGIONThe region to deploy the stacks into, will default to CDK_DEFAULT_REGION.
O3DE_AWS_DEPLOY_ACCOUNTThe account to deploy stacks into, will default to CDK_DEFAULT_ACCOUNT.
O3DE_AWS_PROJECT_NAMEThe name of the O3DE project that stacks should be deployed for, will default to AWS-PROJECT.

See Environments in the AWS CDK Developer Guide for more information including how to pass parameters to use for environment variables.

3. Bootstrap the environment

An AWS environment is a combination of an AWS account and region and must be bootstrapped to provision common AWS CDK resources used for deployment. This only needs to happen once.

Use the AWS CDK bootstrap command to bootstrap one or more AWS environments.

cdk bootstrap aws://ACCOUNT-NUMBER-1/REGION-1 aws://ACCOUNT-NUMBER-2/REGION-2 ...

For example:

cdk bootstrap aws://123456789012/us-east-1

For more information about the bootstrap provisioning process, see the Bootstrapping section of the AWS CDK Developer Guide.

4. Synthesize the project

At this point you can now synthesize the AWS CloudFormation template. Use the AWS CDK synth command from the cdk directory of the Gem whose application you are deploying.

cdk synth

To add additional dependencies, such as other AWS CDK libraries, just add them to your requirements.txt file and rerun the pip install -r requirements.txt command.

5. Deploy the project

To deploy the AWS CDK application, use the deploy command from the cdk directory of the Gem whose application you are deploying.

cdk deploy

The deploy command displays progress information as your stack is deployed.

Useful commands

CommandDescription
cdk lsList all stacks in the app.
cdk synthEmits the synthesized AWS CloudFormation template.
cdk deployDeploy this stack to your default AWS account/region.
cdk diffCompare deployed stack with current state.
cdk docsOpen AWS CDK documentation.

Troubleshooting

For help troubleshooting, see Troubleshooting Common AWS CDK Issues in the AWS CDK Developer Guide.