This is the AWS CDK v1 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and will now only receive critical bug fixes and security patches. New features will be developed for CDK v2 exclusively. Support for CDK v1 will end entirely on June 1, 2023. Migrate to CDK v2 to have access to the latest features and fixes.
Apps
As described in Constructs, to provision infrastructure resources, all
constructs that represent AWS resources must be defined, directly or indirectly, within the
scope of a Stack construct. An App is a container for one or more stacks: it
serves as each stack's scope. Stacks within a single App
can easily refer to each
others' resources (and attributes of those resources). The AWS CDK infers dependencies between
stacks so that they can be deployed in the correct order. You can deploy any or all of the
stacks defined within an app at with a single cdk deploy
command.
The following example declares a stack class named MyFirstStack
that includes a
single Amazon S3 bucket. However, this only declares a stack. You still need to define (also known as
to instantiate) it in some scope to deploy it.
However, this code has only declared a stack. For the stack to actually
be synthesized into a AWS CloudFormation template and deployed, it needs to be instantiated. And, like all
CDK constructs, it must be instantiated in some context. The App
is that
context.
The app construct
To define the previous stack within the scope of an application, use the App
construct. The following example app instantiates a MyFirstStack
and produces the
AWS CloudFormation template that the stack defined.
The App
construct doesn't require any initialization arguments, because it's
the only construct that can be used as a root for the construct tree. You can now use the
App
instance as a scope for defining a single instance of your stack.
App lifecycle
The following diagram shows the phases that the AWS CDK goes through when you call the cdk deploy. This command deploys the resources that your app defines.
![](/images/cdk/v1/guide/images/Lifecycle.png)
An AWS CDK app goes through the following phases in its lifecycle.
- 1. Construction (or Initialization)
-
Your code instantiates all of the defined constructs and then links them together. In this stage, all of the constructs (app, stacks, and their child constructs) are instantiated and the constructor chain is executed. Most of your app code is executed in this stage.
- 2. Preparation
-
All constructs that have implemented the
prepare
method participate in a final round of modifications, to set up their final state. The preparation phase happens automatically. As a user, you don't see any feedback from this phase. It's rare to need to use the "prepare" hook, and generally not recommended. You should be very careful when mutating the construct tree during this phase, because the order of operations could impact behavior. - 3. Validation
-
All constructs that have implemented the
validate
method can validate themselves to ensure that they're in a state that will correctly deploy. You will get notified of any validation failures that happen during this phase. Generally, we recommend that you perform validation as soon as possible (usually as soon as you get some input) and throw exceptions as early as possible. Performing validation early improves diagnosability as stack traces will be more accurate, and ensures that your code can continue to execute safely. - 4. Synthesis
-
This is the final stage of the execution of your AWS CDK app. It's triggered by a call to
app.synth()
, and it traverses the construct tree and invokes thesynthesize
method on all constructs. Constructs that implementsynthesize
can participate in synthesis and emit deployment artifacts to the resulting cloud assembly. These artifacts include AWS CloudFormation templates, AWS Lambda application bundles, file and Docker image assets, and other deployment artifacts. Cloud assemblies describes the output of this phase. In most cases, you won't need to implement thesynthesize
method - 5. Deployment
-
In this phase, the AWS CDK Toolkit takes the deployment artifacts cloud assembly produced by the synthesis phase and deploys it to an AWS environment. It uploads assets to Amazon S3 and Amazon ECR, or wherever they need to go, and then starts an AWS CloudFormation deployment to deploy the application and create the resources.
By the time the AWS CloudFormation deployment phase (step 5) starts, your AWS CDK app has already finished and exited. This has the following implications:
-
The AWS CDK app can't respond to events that happen during deployment, such as a resource being created or the whole deployment finishing. To run code during the deployment phase, you must inject it into the AWS CloudFormation template as a custom resource. For more information about adding a custom resource to your app, see the AWS CloudFormation module, or the custom-resource
example. -
The AWS CDK app might have to work with values that can't be known at the time it runs. For example, if the AWS CDK app defines an Amazon S3 bucket with an automatically generated name, and you retrieve the
bucket.bucketName
(Python:bucket_name
) attribute, that value is not the name of the deployed bucket. Instead, you get aToken
value. To determine whether a particular value is available, callcdk.isUnresloved(value)
(Python:is_unresolved
). See Tokens for details.
Cloud assemblies
The call to app.synth()
is what tells the AWS CDK to synthesize a cloud
assembly from an app. Typically you don't interact directly with cloud assemblies. They are
files that include everything needed to deploy your app to a cloud environment. For example,
it includes an AWS CloudFormation template for each stack in your app, and a copy of any file assets or
Docker images that you reference in your app.
See the cloud assembly specification
To interact with the cloud assembly that your AWS CDK app creates, you typically use the AWS CDK Toolkit, a command-line tool. But any tool that can read the cloud assembly format can be used to deploy your app.
The CDK Toolkit needs to know how to execute your AWS CDK app. If you created the
project from a template using the cdk init
command, your app's
cdk.json
file includes an app
key that specifies the
necessary command for the language the app is written in. If your language requires
compilation, the command line performs this step before running the app, so you can't forget
to do it.
If you did not create your project using the CDK Toolkit, or wish to override the command
line given in cdk.json
, you can use the --app option
when issuing the cdk
command.
cdk --app '
executable
'cdk-command
...
The executable
part of the command indicates the command that
should be run to execute your CDK application. Use quotation marks as shown, since such
commands contain spaces. The cdk-command
is a subcommand like
synth or deploy that tells the CDK Toolkit what you
want to do with your app. Follow this with any additional options needed for that
subcommand.
The CLI can also interact directly with an already-synthesized cloud assembly. To do that,
just pass the directory in which the cloud assembly is stored in --app. The
following example lists the stacks defined in the cloud assembly stored under
./my-cloud-assembly
.
cdk --app ./my-cloud-assembly ls