Environments
Each Stack
instance in your AWS CDK app is explicitly or implicitly associated
with an environment (env
). An environment is the target AWS account and region
into which the stack is intended to be deployed.
For all but the simplest deployments, you will need to bootstrap each environment you will deploy into. Deployment requires certain AWS resources to be available, and these resources are provisioned by bootstrapping.
If you don't specify an environment when you define a stack, the stack is said to
be
environment-agnostic. AWS CloudFormation templates synthesized from such a stack will
try to use deploy-time resolution on environment-related attributes such as
stack.account
, stack.region
, and
stack.availabilityZones
(Python: availability_zones
).
In an environment-agnostic stack, any constructs that use availability zones will see two of them, allowing the stack to be deployed to any region.
When using cdk deploy to deploy environment-agnostic stacks, the AWS CDK CLI uses the specified AWS CLI profile (or the default profile, if none is specified) to determine where to deploy. The AWS CDK CLI follows a protocol similar to the AWS CLI to determine which AWS credentials to use when performing operations against your AWS account. See AWS CDK Toolkit (cdk command) for details.
For production stacks, we recommend that you explicitly specify the environment for
each
stack in your app using the env
property. The following example specifies different
environments for its two different stacks.
When you hard-code the target account and region as above, the stack will always be
deployed
to that specific account and region. To make the stack deployable to a different target,
but to
determine the target at synthesis time, your stack can use two environment variables
provided by
the AWS CDK CLI: CDK_DEFAULT_ACCOUNT
and CDK_DEFAULT_REGION
. These
variables are set based on the AWS profile specified using the --profile
option, or the default AWS profile if you don't specify one.
The following code fragment shows how to access the account and region passed from the AWS CDK CLI in your stack.
The AWS CDK distinguishes between not specifying the env
property at all and
specifying it using CDK_DEFAULT_ACCOUNT
and CDK_DEFAULT_REGION
. The
former implies that the stack should synthesize an environment-agnostic template.
Constructs
that are defined in such a stack cannot use any information about their environment.
For
example, you can't write code like if (stack.region === 'us-east-1')
or use
framework facilities like Vpc.fromLookup (Python: from_lookup
), which need to query your AWS
account. These features do not work at all without an explicit environment specified;
to use
them, you must specify env
.
When you pass in your environment using CDK_DEFAULT_ACCOUNT
and
CDK_DEFAULT_REGION
, the stack will be deployed in the account and Region
determined by the AWS CDK CLI at the time of synthesis. This allows environment-dependent
code to
work, but it also means that the synthesized template could be different based on
the machine,
user, or session under which it is synthesized. This behavior is often acceptable
or even
desirable during development, but it would probably be an anti-pattern for production
use.
You can set env
however you like, using any valid expression. For example, you
might write your stack to support two additional environment variables to let you
override the
account and region at synthesis time. We'll call these CDK_DEPLOY_ACCOUNT
and
CDK_DEPLOY_REGION
here, but you could name them anything you like, as they are
not set by the AWS CDK. In the following stack's environment, we use our alternative
environment
variables if they're set, falling back to the default environment provided by the
AWS CDK if they
are not.
With your stack's environment declared this way, you can now write a short script
or batch
file like the following to set the variables from command line arguments, then call
cdk
deploy
. Any arguments beyond the first two are passed through to cdk
deploy
and can be used to specify command-line options or stacks.
Then you can write additional scripts that call the "deploy-to" script to deploy to specific environments (even multiple environments per script):
When deploying to multiple environments, consider whether you want to continue deploying to other environments after a deployment fails. The following example avoids deploying to the second production environment if the first doesn't succeed.
Developers could still use the normal cdk deploy
command to deploy to their own
AWS environments for development.