Environments and Authentication¶
The AWS CDK refers to the combination of an account ID and a Region as an environment. The simplest environment is the one you get by default, which is the one you get when you have set up your credentials and a default Region as described in credentials_and_region.
When you create a _aws-cdk_core.Stack
instance, you can supply the target deployment environment
for the stack using the env property, as shown in the following example,
where REGION is the Region in which you want to create the stack and ACCOUNT is your account ID.
new MyStack(app, { env: { region: 'REGION', account: 'ACCOUNT' } });
For each of the two arguments region and account, the AWS CDK uses the following lookup procedure:
- If region or account are provided directly as an property to the Stack, use that.
- Otherwise, read default-account and default-region from the application’s context. These can be set in the AWS CDK Toolkit in either the local cdk.json file or the global version in $HOME/.cdk on Linux or MacOS or %USERPROFILE%.cdk on Windows.
- If these are not defined, it will determine them as follows:
- account: use account from default SDK credentials. Environment variables are tried first (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY), followed by credentials in $HOME/.aws/credentials on Linux or MacOS or %USERPROFILE%.aws\credentials on Windows.
- region: use the default region configured in $HOME/.aws/config on Linux or MacOS or %USERPROFILE%.aws\config on Windows.
- You can set these defaults manually, but we recommend you use
aws configure
, as described in the Getting Started With the AWS CDK topic.
We recommend you use the default environment for development stacks, and explicitly specify accounts and Regions for production stacks.
Note
Note that even though the region and account might explicitly be set on your
Stack, if you run cdk deploy
the AWS CDK will still use the
currently-configured SDK credentials, as provided via the AWS_
environment variables or aws configure
. This means that if you want to
deploy stacks to multiple accounts, you will have to set the correct
credentials for each invocation to cdk deploy STACK
.
In the future, we will provide the ability to specify credential sources for
individual accounts so that you can deploy to multiple accounts using one
invocation of cdk deploy
, but this feature is not available yet.
Environmental Context¶
When you synthesize a stack to create a AWS CloudFormation template, the AWS CDK might need information based on the
environment (account and Region), such as the availability zones or AMIs available in the Region.
To enable this feature, the AWS CDK Toolkit uses context providers,
and saves the context information into cdk.json
the first time you call cdk synth
.
The AWS CDK currently supports the following context providers.
_aws-cdk_core.AvailabilityZoneProvider
- Use this provider to get the list of all supported availability zones in this environment. For example, the following code iterates over all of the AZs in the current environment.
const zones: string[] = new AvailabilityZoneProvider(this).availabilityZones;
for (let zone of zones) {
// do somethning for each zone!
}
_aws-cdk_core.SSMParameterProvider
- Use this provider to read values from the current Region’s SSM parameter store. For example, the follow code returns the value of the ‘my-awesome-value’ key:
const ami: string = new SSMParameterProvider(this).getString('my-awesome-value');