This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.
# Learn AWS CDK core concepts
Learn core concepts behind the AWS Cloud Development Kit (AWS CDK).
## AWS CDK and IaC
The AWS CDK is an open-source framework that you can use to manage your AWS infrastructure using code. This approach is known as *infrastructure as code (IaC)*. By managing and provisioning your infrastructure as code, you treat your infrastructure in the same way that developers treat code. This provides many benefits, such as version control and scalability. To learn more about IaC, see [What is Infrastructure as Code?](https://aws.amazon.com/what-is/iac/)
## AWS CDK and AWS CloudFormation
The AWS CDK is tightly integrated with AWS CloudFormation. AWS CloudFormation is a fully managed service that you can use to manage and provision your infrastructure on AWS. With AWS CloudFormation, you define your infrastructure in templates and deploy them to AWS CloudFormation. The AWS CloudFormation service then provisions your infrastructure according to the configuration defined in your templates.
AWS CloudFormation templates are *declarative*, meaning they declare the desired state or outcome of your infrastructure. Using JSON or YAML, you declare your AWS infrastructure by defining AWS *resources* and *properties*. Resources represent the many services on AWS and properties represent your desired configuration of those services. When you deploy your template to AWS CloudFormation, your resources and their configured properties are provisioned as described in your template.
With the AWS CDK, you can manage your infrastructure *imperatively*, using general-purpose programming languages. Instead of just defining a desired state declaratively, you can define the logic or sequence necessary to reach the desired state. For example, you can use `if` statements or conditional loops that determine how to reach a desired end state for your infrastructure.
Infrastructure created with the AWS CDK is eventually translated, or *synthesized* into AWS CloudFormation templates and deployed using the AWS CloudFormation service. So while the AWS CDK offers a different approach to creating your infrastructure, you still receive the benefits of AWS CloudFormation, such as extensive AWS resource configuration support and robust deployment processes.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the * AWS CloudFormation User Guide*.
## AWS CDK and abstractions
With AWS CloudFormation, you must define every detail of how your resources are configured. This provides the benefit of having complete control over your infrastructure. However, this requires you to learn, understand, and create robust templates that contain resource configuration details and relationships between resources, such as permissions and event-driven interactions.
With the AWS CDK, you can have the same control over your resource configurations. However, the AWS CDK also offers powerful abstractions, which can speed up and simplify the infrastructure development process. For example, the AWS CDK includes constructs that provide sensible default configurations and helper methods that generate boilerplate code for you. The AWS CDK also offers tools, such as the AWS CDK Command Line Interface (AWS CDK CLI), that perform infrastructure management actions for you.
## Learn more about core AWS CDK concepts
**Interacting with the AWS CDK**
When using with the AWS CDK, you will primarily interact with the AWS Construct Library and the AWS CDK CLI.
**Developing with the AWS CDK**
The AWS CDK can be written in any [supported programming language](languages.md). You start with a [CDK project](projects.md), which contains a structure of folders and files, including [assets](assets.md). Within the project, you create a [CDK application](apps.md). Within the app, you define a [stack](stacks.md), which directly represents a CloudFormation stack. Within the stack, you define your AWS resources and properties using [constructs](constructs.md).
**Deploying with the AWS CDK**
You deploy CDK apps into an AWS [environment](environments.md). Before deploying, you must perform a one-time [bootstrapping](bootstrapping.md) to prepare your environment.
**Learn more**
To learn more about AWS CDK core concepts, see the topics in this section.
# Supported programming languages for the AWS CDK
The AWS Cloud Development Kit (AWS CDK) has first-class support for the following general-purpose programming languages:
+ TypeScript
+ JavaScript
+ Python
+ Java
+ C\$1
+ Go
Other JVM and .NET CLR languages may also be used in theory, but we do not offer official support at this time.
The AWS CDK is developed in one language, TypeScript. To support the other languages, the AWS CDK utilizes a tool called [JSII](https://github.com/aws/jsii) to generate language bindings.
We attempt to offer each language’s usual conventions to make development with the AWS CDK as natural and intuitive as possible. For example, we distribute AWS Construct Library modules using your preferred language’s standard repository, and you install them using the language’s standard package manager. Methods and properties are also named using your language’s recommended naming patterns.
The following are a few code examples:
**Example**
```
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
bucketName: 'amzn-s3-demo-bucket',
versioned: true,
websiteRedirect: {hostName: 'aws.amazon.com'}});
```
```
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
bucketName: 'amzn-s3-demo-bucket',
versioned: true,
websiteRedirect: {hostName: 'aws.amazon.com'}});
```
```
bucket = s3.Bucket("amzn-s3-demo-bucket", bucket_name="amzn-s3-demo-bucket", versioned=True,
website_redirect=s3.RedirectTarget(host_name="aws.amazon.com"))
```
```
Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket")
.bucketName("amzn-s3-demo-bucket")
.versioned(true)
.websiteRedirect(new RedirectTarget.Builder()
.hostName("aws.amazon.com").build())
.build();
```
```
var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps {
BucketName = "amzn-s3-demo-bucket",
Versioned = true,
WebsiteRedirect = new RedirectTarget {
HostName = "aws.amazon.com"
}});
```
```
bucket := awss3.NewBucket(scope, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps {
BucketName: jsii.String("amzn-s3-demo-bucket"),
Versioned: jsii.Bool(true),
WebsiteRedirect: &awss3.RedirectTarget {
HostName: jsii.String("aws.amazon.com"),
},
})
```
**Note**
These code snippets are intended for illustration only. They are incomplete and won’t run as they are.
The AWS Construct Library is distributed using each language’s standard package management tools, including NPM, PyPi, Maven, and NuGet. We also provide a version of the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) for each language.
To help you use the AWS CDK in your preferred language, this guide includes the following topics for supported languages:
+ [Working with the AWS CDK in TypeScript](work-with-cdk-typescript.md)
+ [Working with the AWS CDK in JavaScript](work-with-cdk-javascript.md)
+ [Working with the AWS CDK in Python](work-with-cdk-python.md)
+ [Working with the AWS CDK in Java](work-with-cdk-java.md)
+ [Working with the AWS CDK in C\$1](work-with-cdk-csharp.md)
+ [Working with the AWS CDK in Go](work-with-cdk-go.md)
TypeScript was the first language supported by the AWS CDK, and much of the AWS CDK example code is written in TypeScript. This guide includes a topic specifically to show how to adapt TypeScript AWS CDK code for use with the other supported languages. For more information, see [Comparing AWS CDK in TypeScript with other languages](work-with.md#work-with-cdk-compare).
# The AWS CDK libraries
Learn about the core libraries that you will use with the AWS Cloud Development Kit (AWS CDK).
## The AWS CDK Library
The AWS CDK Library, also referred to as `aws-cdk-lib`, is the main library that you will use to develop applications with the AWS CDK. It is developed and maintained by AWS. This library contains base classes, such as [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html) and [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html). It also contains the libraries you will use to define your infrastructure through constructs.
## The AWS Construct Library
The AWS Construct Library is a part of the AWS CDK Library. It contains a collection of [constructs](constructs.md) that are developed and maintained by AWS. It is organized into various modules for each AWS service. Each module includes constructs that you can use to define your AWS resources and properties.
## The Constructs library
The Constructs library, commonly referred to as `constructs`, is a library for defining and composing cloud infrastructure components. It contains the core [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html) class, which represents the construct building block. This class is the foundational base class of all constructs from the AWS Construct Library. The Constructs library is a separate general-purpose library that is used by other construct-based tools such as *CDK for Terraform* and *CDK for Kubernetes*.
## The AWS CDK API reference
The [AWS CDK API reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) contains official reference documentation for the AWS CDK Library, including the AWS Construct Library and Constructs library. A version of the API reference is provided for each supported programming language.
+ For AWS CDK Library (`aws-cdk-lib`) documentation, see [aws-cdk-lib module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html).
+ Documentation for constructs in the AWS Construct Library are organized by AWS service in the following format: `aws-cdk-lib.`. For example, construct documentation for Amazon Simple Storage Service (Amazon S3), can be found at [aws-cdk-lib.aws\$1s3 module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3-readme.html).
+ For Constructs library (constructs) documentation, see [constructs module](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs-readme.html).
### Contribute to the AWS CDK API reference
The AWS CDK is open-source and we welcome you to contribute. Community contributions positively impact and improve the AWS CDK. For instructions on contributing specifically to AWS CDK API reference documentation, see [Documentation](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md#documentation) in the *aws-cdk GitHub repository*.
## Learn more
For instructions on importing and using the CDK Library, see [Work with the CDK library](work-with.md).
# AWS CDK projects
An AWS Cloud Development Kit (AWS CDK) project represents the files and folders that contain your CDK code. Contents will vary based on your programming language.
You can create your AWS CDK project manually or with the AWS CDK Command Line Interface (AWS CDK CLI) `cdk init` command. In this topic, we will refer to the project structure and naming conventions of files and folders created by the AWS CDK CLI. You can customize and organize your CDK projects to fit your needs.
**Note**
Project structure created by the AWS CDK CLI may vary across versions over time.
## Universal files and folders
`.git`
If you have `git` installed, the AWS CDK CLI automatically initializes a Git repository for your project. The `.git` directory contains information about the repository.
`.gitignore`
Text file used by Git to specify files and folders to ignore.
`README.md`
Text file that provides you with basic guidance and important information for managing your AWS CDK project. Modify this file as necessary to document important information regarding your CDK project.
`cdk.json`
Configuration file for the AWS CDK. This file provides instruction to the AWS CDK CLI regarding how to run your app.
## Language-specific files and folders
The following files and folders are unique to each supported programming language.
**Example**
The following is an example project created in the `my-cdk-ts-project` directory using the `cdk init --language typescript` command:
```
my-cdk-ts-project
├── .git
├── .gitignore
├── .npmignore
├── README.md
├── bin
│ └── my-cdk-ts-project.ts
├── cdk.json
├── jest.config.js
├── lib
│ └── my-cdk-ts-project-stack.ts
├── node_modules
├── package-lock.json
├── package.json
├── test
│ └── my-cdk-ts-project.test.ts
└── tsconfig.json
```
`.npmignore`
File that specifies which files and folders to ignore when publishing a package to the `npm` registry. This file is similar to `.gitignore`, but is specific to `npm` packages.
`bin/my-cdk-ts-project.ts`
The *application file* defines your CDK app. CDK projects can contain one or more application files. Application files are stored in the `bin` folder.
The following is an example of a basic application file that defines a CDK app:
```
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { MyCdkTsProjectStack } from '../lib/my-cdk-ts-project-stack';
const app = new cdk.App();
new MyCdkTsProjectStack(app, 'MyCdkTsProjectStack');
```
`jest.config.js`
Configuration file for Jest. * Jest * is a popular JavaScript testing framework.
`lib/my-cdk-ts-project-stack.ts`
The *stack file* defines your CDK stack. Within your stack, you define AWS resources and properties using constructs.
The following is an example of a basic stack file that defines a CDK stack:
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
export class MyCdkTsProjectStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// code that defines your resources and properties go here
}
}
```
`node_modules`
Common folder in Node.js projects that contain dependencies for your project.
`package-lock.json`
Metadata file that works with the `package.json` file to manage versions of dependencies.
`package.json`
Metadata file that is commonly used in Node.js projects. This file contains information about your CDK project such as the project name, script definitions, dependencies, and other import project-level information.
`test/my-cdk-ts-project.test.ts`
A test folder is created to organize tests for your CDK project. A sample test file is also created.
You can write tests in TypeScript and use Jest to compile your TypeScript code before running tests.
`tsconfig.json`
Configuration file used in TypeScript projects that specifies compiler options and project settings.
The following is an example project created in the `my-cdk-js-project` directory using the `cdk init --language javascript` command:
```
my-cdk-js-project
├── .git
├── .gitignore
├── .npmignore
├── README.md
├── bin
│ └── my-cdk-js-project.js
├── cdk.json
├── jest.config.js
├── lib
│ └── my-cdk-js-project-stack.js
├── node_modules
├── package-lock.json
├── package.json
└── test
└── my-cdk-js-project.test.js
```
`.npmignore`
File that specifies which files and folders to ignore when publishing a package to the `npm` registry. This file is similar to `.gitignore`, but is specific to `npm` packages.
`bin/my-cdk-js-project.js`
The *application file* defines your CDK app. CDK projects can contain one or more application files. Application files are stored in the `bin` folder.
The following is an example of a basic application file that defines a CDK app:
```
#!/usr/bin/env node
const cdk = require('aws-cdk-lib');
const { MyCdkJsProjectStack } = require('../lib/my-cdk-js-project-stack');
const app = new cdk.App();
new MyCdkJsProjectStack(app, 'MyCdkJsProjectStack');
```
`jest.config.js`
Configuration file for Jest. * Jest * is a popular JavaScript testing framework.
`lib/my-cdk-js-project-stack.js`
The *stack file* defines your CDK stack. Within your stack, you define AWS resources and properties using constructs.
The following is an example of a basic stack file that defines a CDK stack:
```
const { Stack, Duration } = require('aws-cdk-lib');
class MyCdkJsProjectStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// code that defines your resources and properties go here
}
}
module.exports = { MyCdkJsProjectStack }
```
`node_modules`
Common folder in Node.js projects that contain dependencies for your project.
`package-lock.json`
Metadata file that works with the `package.json` file to manage versions of dependencies.
`package.json`
Metadata file that is commonly used in Node.js projects. This file contains information about your CDK project such as the project name, script definitions, dependencies, and other import project-level information.
`test/my-cdk-js-project.test.js`
A test folder is created to organize tests for your CDK project. A sample test file is also created.
You can write tests in JavaScript and use Jest to compile your JavaScript code before running tests.
The following is an example project created in the `my-cdk-py-project` directory using the `cdk init --language python` command:
```
my-cdk-py-project
├── .git
├── .gitignore
├── .venv
├── README.md
├── app.py
├── cdk.json
├── my_cdk_py_project
│ ├── __init__.py
│ └── my_cdk_py_project_stack.py
├── requirements-dev.txt
├── requirements.txt
├── source.bat
└── tests
├── __init__.py
└── unit
```
`.venv`
The CDK CLI automatically creates a virtual environment for your project. The `.venv` directory refers to this virtual environment.
`app.py`
The *application file* defines your CDK app. CDK projects can contain one or more application files.
The following is an example of a basic application file that defines a CDK app:
```
#!/usr/bin/env python3
import os
import aws_cdk as cdk
from my_cdk_py_project.my_cdk_py_project_stack import MyCdkPyProjectStack
app = cdk.App()
MyCdkPyProjectStack(app, "MyCdkPyProjectStack")
app.synth()
```
`my_cdk_py_project`
Directory that contains your *stack files*. The CDK CLI creates the following here:
+ \$1\$1init\$1\$1.py – An empty Python package definition file.
+ `my_cdk_py_project` – File that defines your CDK stack. You then define AWS resources and properties within the stack using constructs.
The following is an example of a stack file:
```
from aws_cdk import Stack
from constructs import Construct
class MyCdkPyProjectStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# code that defines your resources and properties go here
```
`requirements-dev.txt`
File similar to `requirements.txt`, but used to manage dependencies specifically for development purposes rather than production.
`requirements.txt`
Common file used in Python projects to specify and manage project dependencies.
`source.bat`
Batch file for Windows that is used to set up the Python virtual environment.
`tests`
Directory that contains tests for your CDK project.
The following is an example of a unit test:
```
import aws_cdk as core
import aws_cdk.assertions as assertions
from my_cdk_py_project.my_cdk_py_project_stack import MyCdkPyProjectStack
def test_sqs_queue_created():
app = core.App()
stack = MyCdkPyProjectStack(app, "my-cdk-py-project")
template = assertions.Template.from_stack(stack)
template.has_resource_properties("AWS::SQS::Queue", {
"VisibilityTimeout": 300
})
```
The following is an example project created in the `my-cdk-java-project` directory using the `cdk init --language java` command:
```
my-cdk-java-project
├── .git
├── .gitignore
├── README.md
├── cdk.json
├── pom.xml
└── src
├── main
└── test
```
`pom.xml`
File that contains configuration information and metadata about your CDK project. This file is a part of Maven.
`src/main`
Directory containing your *application* and *stack* files.
The following is an example application file:
```
package com.myorg;
import software.amazon.awscdk.App;
import software.amazon.awscdk.Environment;
import software.amazon.awscdk.StackProps;
import java.util.Arrays;
public class MyCdkJavaProjectApp {
public static void main(final String[] args) {
App app = new App();
new MyCdkJavaProjectStack(app, "MyCdkJavaProjectStack", StackProps.builder()
.build());
app.synth();
}
}
```
The following is an example stack file:
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
public class MyCdkJavaProjectStack extends Stack {
public MyCdkJavaProjectStack(final Construct scope, final String id) {
this(scope, id, null);
}
public MyCdkJavaProjectStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// code that defines your resources and properties go here
}
}
```
`src/test`
Directory containing your test files. The following is an example:
```
package com.myorg;
import software.amazon.awscdk.App;
import software.amazon.awscdk.assertions.Template;
import java.io.IOException;
import java.util.HashMap;
import org.junit.jupiter.api.Test;
public class MyCdkJavaProjectTest {
@Test
public void testStack() throws IOException {
App app = new App();
MyCdkJavaProjectStack stack = new MyCdkJavaProjectStack(app, "test");
Template template = Template.fromStack(stack);
template.hasResourceProperties("AWS::SQS::Queue", new HashMap() {{
put("VisibilityTimeout", 300);
}});
}
}
```
The following is an example project created in the `my-cdk-csharp-project` directory using the `cdk init --language csharp` command:
```
my-cdk-csharp-project
├── .git
├── .gitignore
├── README.md
├── cdk.json
└── src
├── MyCdkCsharpProject
└── MyCdkCsharpProject.sln
```
`src/MyCdkCsharpProject`
Directory containing your *application* and *stack* files.
The following is an example application file:
```
using Amazon.CDK;
using System;
using System.Collections.Generic;
using System.Linq;
namespace MyCdkCsharpProject
{
sealed class Program
{
public static void Main(string[] args)
{
var app = new App();
new MyCdkCsharpProjectStack(app, "MyCdkCsharpProjectStack", new StackProps{});
app.Synth();
}
}
}
```
The following is an example stack file:
```
using Amazon.CDK;
using Constructs;
namespace MyCdkCsharpProject
{
public class MyCdkCsharpProjectStack : Stack
{
internal MyCdkCsharpProjectStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// code that defines your resources and properties go here
}
}
}
```
This directory also contains the following:
+ `GlobalSuppressions.cs` – File used to suppress specific compiler warnings or errors across your project.
+ `.csproj` – XML-based file used to define project settings, dependencies, and build configurations. ---
`src/MyCdkCsharpProject.sln`
Microsoft Visual Studio Solution File used to organize and manage related projects.
The following is an example project created in the `my-cdk-go-project` directory using the `cdk init --language go` command:
```
my-cdk-go-project
├── .git
├── .gitignore
├── README.md
├── cdk.json
├── go.mod
├── my-cdk-go-project.go
└── my-cdk-go-project_test.go
```
`go.mod`
File that contains module information and is used to manage dependencies and versioning for your Go project.
`my-cdk-go-project.go`
File that defines your CDK application and stacks.
The following is an example:
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type MyCdkGoProjectStackProps struct {
awscdk.StackProps
}
func NewMyCdkGoProjectStack(scope constructs.Construct, id string, props *MyCdkGoProjectStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// The code that defines your resources and properties go here
return stack
}
func main() {
defer jsii.Close()
app := awscdk.NewApp(nil)
NewMyCdkGoProjectStack(app, "MyCdkGoProjectStack", &MyCdkGoProjectStackProps{
awscdk.StackProps{
Env: env(),
},
})
app.Synth(nil)
}
func env() *awscdk.Environment {
return nil
}
```
`my-cdk-go-project_test.go`
File that defines a sample test.
The following is an example:
```
package main
import (
"testing"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/assertions"
"github.com/aws/jsii-runtime-go"
)
func TestMyCdkGoProjectStack(t *testing.T) {
// GIVEN
app := awscdk.NewApp(nil)
// WHEN
stack := NewMyCdkGoProjectStack(app, "MyStack", nil)
// THEN
template := assertions.Template_FromStack(stack, nil)
template.HasResourceProperties(jsii.String("AWS::SQS::Queue"), map[string]interface{}{
"VisibilityTimeout": 300,
})
}
```
# AWS CDK apps
The AWS Cloud Development Kit (AWS CDK) application or *app* is a collection of one or more CDK [stacks](stacks.md). Stacks are a collection of one or more [constructs](constructs.md), which define AWS resources and properties. Therefore, the overall grouping of your stacks and constructs are known as your CDK app.
## How to create a CDK app
You create an app by defining an app instance in the application file of your [project](projects.md). To do this, you import and use the [App](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html) construct from the AWS Construct Library. The `App` construct doesn’t require any initialization arguments. It is the only construct that can be used as the root.
The ` [App](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html) ` and ` [Stack](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html) ` classes from the AWS Construct Library are unique constructs. Compared to other constructs, they don’t configure AWS resources on their own. Instead, they are used to provide context for your other constructs. All constructs that represent AWS resources must be defined, directly or indirectly, within the scope of a `Stack` construct. `Stack` constructs are defined within the scope of an `App` construct.
Apps are then synthesized to create AWS CloudFormation templates for your stacks. The following is an example:
**Example**
```
const app = new App();
new MyFirstStack(app, 'hello-cdk');
app.synth();
```
```
const app = new App();
new MyFirstStack(app, 'hello-cdk');
app.synth();
```
```
app = App()
MyFirstStack(app, "hello-cdk")
app.synth()
```
```
App app = new App();
new MyFirstStack(app, "hello-cdk");
app.synth();
```
```
var app = new App();
new MyFirstStack(app, "hello-cdk");
app.Synth();
```
```
app := awscdk.NewApp(nil)
MyFirstStack(app, "MyFirstStack", &MyFirstStackProps{
awscdk.StackProps{
Env: env(),
},
})
app.Synth(nil)
```
Stacks within a single app can easily refer to each other’s resources and properties. 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 within an app with a single `cdk deploy` command.
## The construct tree
Constructs are defined inside of other constructs using the `scope` argument that is passed to every construct, with the `App` class as the root. In this way, an AWS CDK app defines a hierarchy of constructs known as the *construct tree*.
The root of this tree is your app, which is an instance of the `App` class. Within the app, you instantiate one or more stacks. Within stacks, you instantiate constructs, which may themselves instantiate resources or other constructs, and so on down the tree.
Constructs are *always* explicitly defined within the scope of another construct, which creates relationships between constructs. Almost always, you should pass `this` (in Python, `self`) as the scope, indicating that the new construct is a child of the current construct. The intended pattern is that you derive your construct from [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html), then instantiate the constructs it uses in its constructor.
Passing the scope explicitly allows each construct to add itself to the tree, with this behavior entirely contained within the [`Construct` base class](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html). It works the same way in every language supported by the AWS CDK and does not require additional customization.
**Important**
Technically, it’s possible to pass some scope other than `this` when instantiating a construct. You can add constructs anywhere in the tree, or even in another stack in the same app. For example, you could write a mixin-style function that adds constructs to a scope passed in as an argument. The practical difficulty here is that you can’t easily ensure that the IDs you choose for your constructs are unique within someone else’s scope. This practice also makes your code more difficult to understand, maintain, and reuse. Therefore, we recommend that you use the general structure of the construct tree.
The AWS CDK uses the IDs of all constructs in the path from the tree’s root to each child construct to generate the unique IDs required by AWS CloudFormation. This approach means that construct IDs only need to be unique within their scope, rather than within the entire stack as in native AWS CloudFormation. However, if you move a construct to a different scope, its generated stack-unique ID changes, and AWS CloudFormation won’t consider it the same resource.
The construct tree is separate from the constructs that you define in your AWS CDK code. However, it’s accessible through any construct’s `node` attribute, which is a reference to the node that represents that construct in the tree. Each node is a [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Node.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Node.html) instance, the attributes of which provide access to the tree’s root and to the node’s parent scopes and children.
1. `node.children` – The direct children of the construct.
1. `node.id` – The identifier of the construct within its scope.
1. `node.path` – The full path of the construct including the IDs of all of its parents.
1. `node.root` – The root of the construct tree (the app).
1. `node.scope` – The scope (parent) of the construct, or undefined if the node is the root.
1. `node.scopes` – All parents of the construct, up to the root.
1. `node.uniqueId` – The unique alphanumeric identifier for this construct within the tree (by default, generated from `node.path` and a hash).
The construct tree defines an implicit order in which constructs are synthesized to resources in the final AWS CloudFormation template. Where one resource must be created before another, AWS CloudFormation or the AWS Construct Library generally infers the dependency. They then make sure that the resources are created in the right order.
You can also add an explicit dependency between two nodes by using `node.addDependency()`. For more information, see [Dependencies](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html#dependencies) in the * AWS CDK API Reference*.
The AWS CDK provides a simple way to visit every node in the construct tree and perform an operation on each one. For more information, see [Aspects and the AWS CDK](aspects.md).
# Introduction to AWS CDK stacks
An AWS CDK stack is the smallest single unit of deployment. It represents a collection of AWS resources that you define using CDK constructs. When you deploy CDK apps, the resources within a CDK stack are deployed together as an AWS CloudFormation stack. To learn more about AWS CloudFormation stacks, see [Managing AWS resources as a single unit with AWS CloudFormation stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacks.html) in the * AWS CloudFormation User Guide*.
You define a stack by extending or inheriting from the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html) construct. The following example is a common pattern for defining a CDK stack on a separate file, known as a *stack file*. Here, we extend or inherit the `Stack` class and define a constructor that accepts `scope`, `id`, and `props`. Then, we invoke the base `Stack` class constructor using `super` with the received `scope`, `id`, and `props`:
**Example**
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
export class MyCdkStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define your constructs here
}
}
```
```
const { Stack } = require('aws-cdk-lib');
class MyCdkStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define your constructs here
}
}
module.exports = { MyCdkStack }
```
```
from aws_cdk import (
Stack,
)
from constructs import Construct
class MyCdkStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define your constructs here
```
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
public class MyCdkStack extends Stack {
public MyCdkStack(final Construct scope, final String id) {
this(scope, id, null);
}
public MyCdkStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Define your constructs here
}
}
```
```
using Amazon.CDK;
using Constructs;
namespace MyCdk
{
public class MyCdkStack : Stack
{
internal MyCdkStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Define your constructs here
}
}
}
```
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type CdkDemoAppStackProps struct {
awscdk.StackProps
}
func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// The code that defines your stack goes here
return stack
}
func main() {
defer jsii.Close()
app := awscdk.NewApp(nil)
NewCdkDemoAppStack(app, "CdkDemoAppStack", &CdkDemoAppStackProps{
awscdk.StackProps{
Env: env(),
},
})
app.Synth(nil)
}
//...
```
The previous example has only defined a stack. To create the stack, it must be instantiated within the context of your CDK app. A common pattern is to define your CDK app and initialize your stack on a separate file, known as an *application file*.
The following is an example that creates a CDK stack named `MyCdkStack`. Here, the CDK app is created and `MyCdkStack` is instantiated in the context of the app:
**Example**
```
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { MyCdkStack } from '../lib/my-cdk-stack';
const app = new cdk.App();
new MyCdkStack(app, 'MyCdkStack', {
});
```
```
#!/usr/bin/env node
const cdk = require('aws-cdk-lib');
const { MyCdkStack } = require('../lib/my-cdk-stack');
const app = new cdk.App();
new MyCdkStack(app, 'MyCdkStack', {
});
```
Located in `app.py`:
```
#!/usr/bin/env python3
import os
import aws_cdk as cdk
from my_cdk.my_cdk_stack import MyCdkStack
app = cdk.App()
MyCdkStack(app, "MyCdkStack",)
app.synth()
```
```
package com.myorg;
import software.amazon.awscdk.App;
import software.amazon.awscdk.Environment;
import software.amazon.awscdk.StackProps;
import java.util.Arrays;
public class MyCdkApp {
public static void main(final String[] args) {
App app = new App();
new MyCdkStack(app, "MyCdkStack", StackProps.builder()
.build());
app.synth();
}
}
```
```
using Amazon.CDK;
using System;
using System.Collections.Generic;
using System.Linq;
namespace MyCdk
{
sealed class Program
{
public static void Main(string[] args)
{
var app = new App();
new MyCdkStack(app, "MyCdkStack", new StackProps
{});
app.Synth();
}
}
}
```
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
// ...
func main() {
defer jsii.Close()
app := awscdk.NewApp(nil)
NewMyCdkStack(app, "MyCdkStack", &MyCdkStackProps{
awscdk.StackProps{
Env: env(),
},
})
app.Synth(nil)
}
// ...
```
The following example creates a CDK app that contains two stacks:
**Example**
```
const app = new App();
new MyFirstStack(app, 'stack1');
new MySecondStack(app, 'stack2');
app.synth();
```
```
const app = new App();
new MyFirstStack(app, 'stack1');
new MySecondStack(app, 'stack2');
app.synth();
```
```
app = App()
MyFirstStack(app, 'stack1')
MySecondStack(app, 'stack2')
app.synth()
```
```
App app = new App();
new MyFirstStack(app, "stack1");
new MySecondStack(app, "stack2");
app.synth();
```
```
var app = new App();
new MyFirstStack(app, "stack1");
new MySecondStack(app, "stack2");
app.Synth();
```
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type MyFirstStackProps struct {
awscdk.StackProps
}
func NewMyFirstStack(scope constructs.Construct, id string, props *MyFirstStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
myFirstStack := awscdk.NewStack(scope, &id, &sprops)
// The code that defines your stack goes here
return myFirstStack
}
type MySecondStackProps struct {
awscdk.StackProps
}
func NewMySecondStack(scope constructs.Construct, id string, props *MySecondStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
mySecondStack := awscdk.NewStack(scope, &id, &sprops)
// The code that defines your stack goes here
return mySecondStack
}
func main() {
defer jsii.Close()
app := awscdk.NewApp(nil)
NewMyFirstStack(app, "MyFirstStack", &MyFirstStackProps{
awscdk.StackProps{
Env: env(),
},
})
NewMySecondStack(app, "MySecondStack", &MySecondStackProps{
awscdk.StackProps{
Env: env(),
},
})
app.Synth(nil)
}
// ...
```
## About the stack API
The [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html) object provides a rich API, including the following:
+ `Stack.of(construct)` – A static method that returns the **Stack** in which a construct is defined. This is useful if you need to interact with a stack from within a reusable construct. The call fails if a stack cannot be found in scope.
+ `stack.stackName` (Python: `stack_name`) – Returns the physical name of the stack. As mentioned previously, all AWS CDK stacks have a physical name that the AWS CDK can resolve during synthesis.
+ `stack.region` and `stack.account` – Return the AWS Region and account, respectively, into which this stack will be deployed. These properties return one of the following:
+ The account or Region explicitly specified when the stack was defined
+ A string-encoded token that resolves to the AWS CloudFormation pseudo parameters for account and Region to indicate that this stack is environment agnostic
For information about how environments are determined for stacks, see [Environments for the AWS CDK](environments.md).
+ `stack.addDependency(stack)` (Python: `stack.add_dependency(stack)`) – Can be used to explicitly define dependency order between two stacks. This order is respected by the `cdk deploy` command when deploying multiple stacks at once.
+ `stack.tags` – Returns a [TagManager](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.TagManager.html) that you can use to add or remove stack-level tags. This tag manager tags all resources within the stack, and also tags the stack itself when it’s created through AWS CloudFormation.
+ `stack.partition`, `stack.urlSuffix` (Python: `url_suffix`), `stack.stackId` (Python: `stack_id`), and `stack.notificationArn` (Python: `notification_arn`) – Return tokens that resolve to the respective AWS CloudFormation pseudo parameters, such as `{ "Ref": "AWS::Partition" }`. These tokens are associated with the specific stack object so that the AWS CDK framework can identify cross-stack references.
+ `stack.availabilityZones` (Python: `availability_zones`) – Returns the set of Availability Zones available in the environment in which this stack is deployed. For environment-agnostic stacks, this always returns an array with two Availability Zones. For environment-specific stacks, the AWS CDK queries the environment and returns the exact set of Availability Zones available in the Region that you specified.
+ `stack.parseArn(arn)` and `stack.formatArn(comps)` (Python: `parse_arn`, `format_arn`) – Can be used to work with Amazon Resource Names (ARNs).
+ `stack.toJsonString(obj)` (Python: `to_json_string`) – Can be used to format an arbitrary object as a JSON string that can be embedded in an AWS CloudFormation template. The object can include tokens, attributes, and references, which are only resolved during deployment.
+ `stack.templateOptions` (Python: `template_options`) – Use to specify AWS CloudFormation template options, such as Transform, Description, and Metadata, for your stack.
## Working with stacks
Stacks are deployed as an AWS CloudFormation stack into an AWS [environment](environments.md). The environment covers a specific AWS account and AWS Region.
When you run the `cdk synth` command for an app with multiple stacks, the cloud assembly includes a separate template for each stack instance. Even if the two stacks are instances of the same class, the AWS CDK emits them as two individual templates.
You can synthesize each template by specifying the stack name in the `cdk synth` command. The following example synthesizes the template for `stack1`:
```
$ cdk synth
```
This approach is conceptually different from how AWS CloudFormation templates are normally used, where a template can be deployed multiple times and parameterized through [AWS CloudFormation parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html). Although AWS CloudFormation parameters can be defined in the AWS CDK, they are generally discouraged because AWS CloudFormation parameters are resolved only during deployment. This means that you cannot determine their value in your code.
For example, to conditionally include a resource in your app based on a parameter value, you must set up an [AWS CloudFormation condition](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html) and tag the resource with it. The AWS CDK takes an approach where concrete templates are resolved at synthesis time. Therefore, you can use an `if` statement to check the value to determine whether a resource should be defined or some behavior should be applied.
**Note**
The AWS CDK provides as much resolution as possible during synthesis time to enable idiomatic and natural usage of your programming language.
Like any other construct, stacks can be composed together into groups. The following code shows an example of a service that consists of three stacks: a control plane, a data plane, and monitoring stacks. The service construct is defined twice: once for the beta environment and once for the production environment.
**Example**
```
import { App, Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
interface EnvProps {
prod: boolean;
}
// imagine these stacks declare a bunch of related resources
class ControlPlane extends Stack {}
class DataPlane extends Stack {}
class Monitoring extends Stack {}
class MyService extends Construct {
constructor(scope: Construct, id: string, props?: EnvProps) {
super(scope, id);
// we might use the prod argument to change how the service is configured
new ControlPlane(this, "cp");
new DataPlane(this, "data");
new Monitoring(this, "mon"); }
}
const app = new App();
new MyService(app, "beta");
new MyService(app, "prod", { prod: true });
app.synth();
```
```
const { App, Stack } = require('aws-cdk-lib');
const { Construct } = require('constructs');
// imagine these stacks declare a bunch of related resources
class ControlPlane extends Stack {}
class DataPlane extends Stack {}
class Monitoring extends Stack {}
class MyService extends Construct {
constructor(scope, id, props) {
super(scope, id);
// we might use the prod argument to change how the service is configured
new ControlPlane(this, "cp");
new DataPlane(this, "data");
new Monitoring(this, "mon");
}
}
const app = new App();
new MyService(app, "beta");
new MyService(app, "prod", { prod: true });
app.synth();
```
```
from aws_cdk import App, Stack
from constructs import Construct
# imagine these stacks declare a bunch of related resources
class ControlPlane(Stack): pass
class DataPlane(Stack): pass
class Monitoring(Stack): pass
class MyService(Construct):
def __init__(self, scope: Construct, id: str, *, prod=False):
super().__init__(scope, id)
# we might use the prod argument to change how the service is configured
ControlPlane(self, "cp")
DataPlane(self, "data")
Monitoring(self, "mon")
app = App();
MyService(app, "beta")
MyService(app, "prod", prod=True)
app.synth()
```
```
package com.myorg;
import software.amazon.awscdk.App;
import software.amazon.awscdk.Stack;
import software.constructs.Construct;
public class MyApp {
// imagine these stacks declare a bunch of related resources
static class ControlPlane extends Stack {
ControlPlane(Construct scope, String id) {
super(scope, id);
}
}
static class DataPlane extends Stack {
DataPlane(Construct scope, String id) {
super(scope, id);
}
}
static class Monitoring extends Stack {
Monitoring(Construct scope, String id) {
super(scope, id);
}
}
static class MyService extends Construct {
MyService(Construct scope, String id) {
this(scope, id, false);
}
MyService(Construct scope, String id, boolean prod) {
super(scope, id);
// we might use the prod argument to change how the service is configured
new ControlPlane(this, "cp");
new DataPlane(this, "data");
new Monitoring(this, "mon");
}
}
public static void main(final String argv[]) {
App app = new App();
new MyService(app, "beta");
new MyService(app, "prod", true);
app.synth();
}
}
```
```
using Amazon.CDK;
using Constructs;
// imagine these stacks declare a bunch of related resources
public class ControlPlane : Stack {
public ControlPlane(Construct scope, string id=null) : base(scope, id) { }
}
public class DataPlane : Stack {
public DataPlane(Construct scope, string id=null) : base(scope, id) { }
}
public class Monitoring : Stack
{
public Monitoring(Construct scope, string id=null) : base(scope, id) { }
}
public class MyService : Construct
{
public MyService(Construct scope, string id, Boolean prod=false) : base(scope, id)
{
// we might use the prod argument to change how the service is configured
new ControlPlane(this, "cp");
new DataPlane(this, "data");
new Monitoring(this, "mon");
}
}
class Program
{
static void Main(string[] args)
{
var app = new App();
new MyService(app, "beta");
new MyService(app, "prod", prod: true);
app.Synth();
}
}
```
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type ControlPlaneStackProps struct {
awscdk.StackProps
}
func NewControlPlaneStack(scope constructs.Construct, id string, props *ControlPlaneStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
ControlPlaneStack := awscdk.NewStack(scope, jsii.String(id), &sprops)
// The code that defines your stack goes here
return ControlPlaneStack
}
type DataPlaneStackProps struct {
awscdk.StackProps
}
func NewDataPlaneStack(scope constructs.Construct, id string, props *DataPlaneStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
DataPlaneStack := awscdk.NewStack(scope, jsii.String(id), &sprops)
// The code that defines your stack goes here
return DataPlaneStack
}
type MonitoringStackProps struct {
awscdk.StackProps
}
func NewMonitoringStack(scope constructs.Construct, id string, props *MonitoringStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
MonitoringStack := awscdk.NewStack(scope, jsii.String(id), &sprops)
// The code that defines your stack goes here
return MonitoringStack
}
type MyServiceStackProps struct {
awscdk.StackProps
Prod bool
}
func NewMyServiceStack(scope constructs.Construct, id string, props *MyServiceStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
MyServiceStack := awscdk.NewStack(scope, jsii.String(id), &sprops)
NewControlPlaneStack(MyServiceStack, "cp", &ControlPlaneStackProps{
StackProps: sprops,
})
NewDataPlaneStack(MyServiceStack, "data", &DataPlaneStackProps{
StackProps: sprops,
})
NewMonitoringStack(MyServiceStack, "mon", &MonitoringStackProps{
StackProps: sprops,
})
return MyServiceStack
}
func main() {
defer jsii.Close()
app := awscdk.NewApp(nil)
betaProps := MyServiceStackProps{
StackProps: awscdk.StackProps{
Env: env(),
},
Prod: false,
}
NewMyServiceStack(app, "beta", &betaProps)
prodProps := MyServiceStackProps{
StackProps: awscdk.StackProps{
Env: env(),
},
Prod: true,
}
NewMyServiceStack(app, "prod", &prodProps)
app.Synth(nil)
}
// ...
```
This AWS CDK app eventually consists of six stacks, three for each environment:
```
$ cdk ls
betacpDA8372D3
betadataE23DB2BA
betamon632BD457
prodcp187264CE
proddataF7378CE5
prodmon631A1083
```
The physical names of the AWS CloudFormation stacks are automatically determined by the AWS CDK based on the stack’s construct path in the tree. By default, a stack’s name is derived from the construct ID of the `Stack` object. However, you can specify an explicit name by using the `stackName` prop (in Python, `stack_name`), as follows.
**Example**
```
new MyStack(this, 'not:a:stack:name', { stackName: 'this-is-stack-name' });
```
```
new MyStack(this, 'not:a:stack:name', { stackName: 'this-is-stack-name' });
```
```
MyStack(self, "not:a:stack:name", stack_name="this-is-stack-name")
```
```
new MyStack(this, "not:a:stack:name", StackProps.builder()
.StackName("this-is-stack-name").build());
```
```
new MyStack(this, "not:a:stack:name", new StackProps
{
StackName = "this-is-stack-name"
});
```
### Working with nested stacks
A *nested stack* is a CDK stack that you create inside another stack, known as the parent stack. You create nested stacks using the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.NestedStack.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.NestedStack.html) construct.
By using nested stacks, you can organize resources across multiple stacks. Nested stacks also offer a way around the AWS CloudFormation 500-resource limit for stacks. A nested stack counts as only one resource in the stack that contains it. However, it can contain up to 500 resources, including additional nested stacks.
The scope of a nested stack must be a `Stack` or `NestedStack` construct. The nested stack doesn’t need to be declared lexically inside its parent stack. It is necessary only to pass the parent stack as the first parameter (`scope`) when instantiating the nested stack. Aside from this restriction, defining constructs in a nested stack works exactly the same as in an ordinary stack.
At synthesis time, the nested stack is synthesized to its own AWS CloudFormation template, which is uploaded to the AWS CDK staging bucket at deployment. Nested stacks are bound to their parent stack and are not treated as independent deployment artifacts. They aren’t listed by `cdk list`, and they can’t be deployed by `cdk deploy`.
References between parent stacks and nested stacks are automatically translated to stack parameters and outputs in the generated AWS CloudFormation templates, as with any [cross-stack reference](resources.md#resource-stack).
**Warning**
Changes in security posture are not displayed before deployment for nested stacks. This information is displayed only for top-level stacks.
# Introduction to AWS CDK stages
An AWS Cloud Development Kit (AWS CDK) *stage* represents a group of one or more CDK stacks that are configured to deploy together. Use stages to deploy the same grouping of stacks to multiple environments, such as development, testing, and production.
To configure a CDK stage, import and use the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stage.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stage.html) construct.
The following is a basic example that defines a CDK stage named `MyAppStage`. We add two CDK stacks, named `AppStack` and `DatabaseStack` to our stage. For this example, `AppStack` contains application resources and `DatabaseStack` contains database resources. We then create two instances of `MyAppStage`, for development and production environments:
**Example**
In `cdk-demo-app/lib/app-stack.ts`:
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// Define the app stack
export class AppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// The code that defines your application goes here
}
}
```
In `cdk-demo-app/lib/database-stack.ts`:
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// Define the database stack
export class DatabaseStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// The code that defines your database goes here
}
}
```
In `cdk-demo-app/lib/my-stage.ts`:
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Stage } from 'aws-cdk-lib';
import { AppStack } from './app-stack';
import { DatabaseStack } from './database-stack';
// Define the stage
export class MyAppStage extends Stage {
constructor(scope: Construct, id: string, props?: cdk.StageProps) {
super(scope, id, props);
// Add both stacks to the stage
new AppStack(this, 'AppStack');
new DatabaseStack(this, 'DatabaseStack');
}
}
```
In `cdk-demo-app/bin/cdk-demo-app.ts`:
```
#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { MyAppStage } from '../lib/my-stage';
// Create a CDK app
const app = new cdk.App();
// Create the development stage
new MyAppStage(app, 'Dev', {
env: {
account: '123456789012',
region: 'us-east-1'
}
});
// Create the production stage
new MyAppStage(app, 'Prod', {
env: {
account: '098765432109',
region: 'us-east-1'
}
});
```
In `cdk-demo-app/lib/app-stack.js`:
```
const { Stack } = require('aws-cdk-lib');
class AppStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// The code that defines your application goes here
}
}
module.exports = { AppStack }
```
In `cdk-demo-app/lib/database-stack.js`:
```
const { Stack } = require('aws-cdk-lib');
class DatabaseStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// The code that defines your database goes here
}
}
module.exports = { DatabaseStack }
```
In `cdk-demo-app/lib/my-stage.js`:
```
const { Stage } = require('aws-cdk-lib');
const { AppStack } = require('./app-stack');
const { DatabaseStack } = require('./database-stack');
// Define the stage
class MyAppStage extends Stage {
constructor(scope, id, props) {
super(scope, id, props);
// Add both stacks to the stage
new AppStack(this, 'AppStack');
new DatabaseStack(this, 'DatabaseStack');
}
}
module.exports = { MyAppStage };
```
In `cdk-demo-app/bin/cdk-demo-app.js`:
```
#!/usr/bin/env node
const cdk = require('aws-cdk-lib');
const { MyAppStage } = require('../lib/my-stage');
// Create the CDK app
const app = new cdk.App();
// Create the development stage
new MyAppStage(app, 'Dev', {
env: {
account: '123456789012',
region: 'us-east-1',
},
});
// Create the production stage
new MyAppStage(app, 'Prod', {
env: {
account: '098765432109',
region: 'us-east-1',
},
});
```
In `cdk-demo-app/cdk_demo_app/app_stack.py`:
```
from aws_cdk import Stack
from constructs import Construct
# Define the app stack
class AppStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# The code that defines your application goes here
```
In `cdk-demo-app/cdk_demo_app/database_stack.py`:
```
from aws_cdk import Stack
from constructs import Construct
# Define the database stack
class DatabaseStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# The code that defines your database goes here
```
In `cdk-demo-app/cdk_demo_app/my_stage.py`:
```
from aws_cdk import Stage
from constructs import Construct
from .app_stack import AppStack
from .database_stack import DatabaseStack
# Define the stage
class MyAppStage(Stage):
def __init__(self, scope: Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Add both stacks to the stage
AppStack(self, "AppStack")
DatabaseStack(self, "DatabaseStack")
```
In `cdk-demo-app/app.py`:
```
#!/usr/bin/env python3
import os
import aws_cdk as cdk
from cdk_demo_app.my_stage import MyAppStage
# Create a CDK app
app = cdk.App()
# Create the development stage
MyAppStage(app, 'Dev',
env=cdk.Environment(account='123456789012', region='us-east-1'),
)
# Create the production stage
MyAppStage(app, 'Prod',
env=cdk.Environment(account='098765432109', region='us-east-1'),
)
app.synth()
```
In `cdk-demo-app/src/main/java/com/myorg/AppStack.java`:
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
public class AppStack extends Stack {
public AppStack(final Construct scope, final String id) {
this(scope, id, null);
}
public AppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// The code that defines your application goes here
}
}
```
In `cdk-demo-app/src/main/java/com/myorg/DatabaseStack.java`:
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
public class DatabaseStack extends Stack {
public DatabaseStack(final Construct scope, final String id) {
this(scope, id, null);
}
public DatabaseStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// The code that defines your database goes here
}
}
```
In `cdk-demo-app/src/main/java/com/myorg/MyAppStage.java`:
```
package com.myorg;
import software.amazon.awscdk.Stage;
import software.amazon.awscdk.StageProps;
import software.constructs.Construct;
// Define the stage
public class MyAppStage extends Stage {
public MyAppStage(final Construct scope, final String id, final software.amazon.awscdk.Environment env) {
super(scope, id, StageProps.builder().env(env).build());
// Add both stacks to the stage
new AppStack(this, "AppStack");
new DatabaseStack(this, "DatabaseStack");
}
}
```
In `cdk-demo-app/src/main/java/com/myorg/CdkDemoAppApp.java`:
```
package com.myorg;
import software.amazon.awscdk.App;
import software.amazon.awscdk.Environment;
import software.amazon.awscdk.StackProps;
import java.util.Arrays;
public class CdkDemoAppApp {
public static void main(final String[] args) {
// Create a CDK app
App app = new App();
// Create the development stage
new MyAppStage(app, "Dev", Environment.builder()
.account("123456789012")
.region("us-east-1")
.build());
// Create the production stage
new MyAppStage(app, "Prod", Environment.builder()
.account("098765432109")
.region("us-east-1")
.build());
app.synth();
}
}
```
In `cdk-demo-app/src/CdkDemoApp/AppStack.cs`:
```
using Amazon.CDK;
using Constructs;
namespace CdkDemoApp
{
public class AppStack : Stack
{
internal AppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// The code that defines your application goes here
}
}
}
```
In `cdk-demo-app/src/CdkDemoApp/DatabaseStack.cs`:
```
using Amazon.CDK;
using Constructs;
namespace CdkDemoApp
{
public class DatabaseStack : Stack
{
internal DatabaseStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// The code that defines your database goes here
}
}
}
```
In `cdk-demo-app/src/CdkDemoApp/MyAppStage.cs`:
```
using Amazon.CDK;
using Constructs;
namespace CdkDemoApp
{
// Define the stage
public class MyAppStage : Stage
{
internal MyAppStage(Construct scope, string id, Environment env) : base(scope, id, new StageProps { Env = env })
{
// Add both stacks to the stage
new AppStack(this, "AppStack");
new DatabaseStack(this, "DatabaseStack");
}
}
}
```
In `cdk-demo-app/src/CdkDemoApp/program.cs`:
```
using Amazon.CDK;
using System;
using System.Collections.Generic;
using System.Linq;
namespace CdkDemoApp
{
sealed class Program
{
public static void Main(string[] args)
{
// Create a CDK app
var app = new App();
// Create the development stage
new MyAppStage(app, "Dev", new Amazon.CDK.Environment
{
Account = "123456789012",
Region = "us-east-1"
});
// Create the production stage
new MyAppStage(app, "Prod", new Amazon.CDK.Environment
{
Account = "098765432109",
Region = "us-east-1"
});
app.Synth();
}
}
}
```
In `cdk-demo-app/cdk-demo-app.go`:
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
// Define the app stack
type AppStackProps struct {
awscdk.StackProps
}
func NewAppStack(scope constructs.Construct, id string, props *AppStackProps) awscdk.Stack {
stack := awscdk.NewStack(scope, &id, &props.StackProps)
// The code that defines your application goes here
return stack
}
// Define the database stack
type DatabaseStackProps struct {
awscdk.StackProps
}
func NewDatabaseStack(scope constructs.Construct, id string, props *DatabaseStackProps) awscdk.Stack {
stack := awscdk.NewStack(scope, &id, &props.StackProps)
// The code that defines your database goes here
return stack
}
// Define the stage
type MyAppStageProps struct {
awscdk.StageProps
}
func NewMyAppStage(scope constructs.Construct, id string, props *MyAppStageProps) awscdk.Stage {
stage := awscdk.NewStage(scope, &id, &props.StageProps)
// Add both stacks to the stage
NewAppStack(stage, "AppStack", &AppStackProps{
StackProps: awscdk.StackProps{
Env: props.Env,
},
})
NewDatabaseStack(stage, "DatabaseStack", &DatabaseStackProps{
StackProps: awscdk.StackProps{
Env: props.Env,
},
})
return stage
}
func main() {
defer jsii.Close()
// Create a CDK app
app := awscdk.NewApp(nil)
// Create the development stage
NewMyAppStage(app, "Dev", &MyAppStageProps{
StageProps: awscdk.StageProps{
Env: &awscdk.Environment{
Account: jsii.String("123456789012"),
Region: jsii.String("us-east-1"),
},
},
})
// Create the production stage
NewMyAppStage(app, "Prod", &MyAppStageProps{
StageProps: awscdk.StageProps{
Env: &awscdk.Environment{
Account: jsii.String("098765432109"),
Region: jsii.String("us-east-1"),
},
},
})
app.Synth(nil)
}
func env() *awscdk.Environment {
return nil
}
```
When we run `cdk synth`, two cloud assemblies are created in `cdk.out`. These two cloud assemblies contain the synthesized AWS CloudFormation template and assets for each stage. The following is snippet of our project directory:
**Example**
```
cdk-demo-app
├── bin
│ └── cdk-demo-app.ts
├── cdk.out
│ ├── assembly-Dev
│ │ ├── DevAppStack.assets.json
│ │ ├── DevAppStack.template.json
│ │ ├── DevDatabaseStack.assets.json
│ │ ├── DevDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── assembly-Prod
│ │ ├── ProdAppStack.assets.json
│ │ ├── ProdAppStack.template.json
│ │ ├── ProdDatabaseStack.assets.json
│ │ ├── ProdDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
└── lib
├── app-stack.ts
├── database-stack.ts
└── my-stage.ts
```
```
cdk-demo-app
├── bin
│ └── cdk-demo-app.js
├── cdk.out
│ ├── assembly-Dev
│ │ ├── DevAppStack.assets.json
│ │ ├── DevAppStack.template.json
│ │ ├── DevDatabaseStack.assets.json
│ │ ├── DevDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── assembly-Prod
│ │ ├── ProdAppStack.assets.json
│ │ ├── ProdAppStack.template.json
│ │ ├── ProdDatabaseStack.assets.json
│ │ ├── ProdDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
└── lib
├── app-stack.js
├── database-stack.js
└── my-stage.js
```
```
cdk-demo-app
├── app.py
├── cdk.out
│ ├── assembly-Dev
│ │ ├── DevAppStack.assets.json
│ │ ├── DevAppStack.template.json
│ │ ├── DevDatabaseStack.assets.json
│ │ ├── DevDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── assembly-Prod
│ │ ├── ProdAppStack.assets.json
│ │ ├── ProdAppStack.template.json
│ │ ├── ProdDatabaseStack.assets.json
│ │ ├── ProdDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── cdk.out
│ ├── manifest.json
│ └── tree.json
└── cdk_demo_app
├── __init__.py
├── app_stack.py
├── database_stack.py
└── my_stage.py
```
```
cdk-demo-app
├── cdk.out
│ ├── assembly-Dev
│ │ ├── DevAppStack.assets.json
│ │ ├── DevAppStack.template.json
│ │ ├── DevDatabaseStack.assets.json
│ │ ├── DevDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── assembly-Prod
│ │ ├── ProdAppStack.assets.json
│ │ ├── ProdAppStack.template.json
│ │ ├── ProdDatabaseStack.assets.json
│ │ ├── ProdDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── cdk.out
│ ├── manifest.json
│ └── tree.json
└── src
└── main
└── java
└── com
└── myorg
├── AppStack.java
├── CdkDemoAppApp.java
├── DatabaseStack.java
└── MyAppStage.java
```
```
cdk-demo-app
├── cdk.out
│ ├── assembly-Dev
│ │ ├── DevAppStack.assets.json
│ │ ├── DevAppStack.template.json
│ │ ├── DevDatabaseStack.assets.json
│ │ ├── DevDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── assembly-Prod
│ │ ├── ProdAppStack.assets.json
│ │ ├── ProdAppStack.template.json
│ │ ├── ProdDatabaseStack.assets.json
│ │ ├── ProdDatabaseStack.template.json
│ │ ├── cdk.out
│ │ └── manifest.json
│ ├── cdk.out
│ ├── manifest.json
│ └── tree.json
└── src
└── CdkDemoApp
├── AppStack.cs
├── DatabaseStack.cs
├── MyAppStage.cs
└── Program.cs
```
```
cdk-demo-app
├── cdk-demo-app.go
└── cdk.out
├── assembly-Dev
│ ├── DevAppStack.assets.json
│ ├── DevAppStack.template.json
│ ├── DevDatabaseStack.assets.json
│ ├── DevDatabaseStack.template.json
│ ├── cdk.out
│ └── manifest.json
├── assembly-Prod
│ ├── ProdAppStack.assets.json
│ ├── ProdAppStack.template.json
│ ├── ProdDatabaseStack.assets.json
│ ├── ProdDatabaseStack.template.json
│ ├── cdk.out
│ └── manifest.json
├── cdk.out
├── manifest.json
└── tree.json
```
When we list our stacks with `cdk list`, we see a total of four stacks:
```
$ cdk list
Dev/AppStack (Dev-AppStack)
Dev/DatabaseStack (Dev-DatabaseStack)
Prod/AppStack (Prod-AppStack)
Prod/DatabaseStack (Prod-DatabaseStack)
```
To deploy a specific stage, we run `cdk deploy` and provide the stacks to deploy. The following is an example that uses the `/*` wildcard to deploy both stacks in our `Dev` stage:
```
$ cdk deploy <"Dev/*">
✨ Synthesis time: 3.18s
Dev/AppStack (Dev-AppStack)
Dev/AppStack (Dev-AppStack): deploying... [1/2]
✅ Dev/AppStack (Dev-AppStack)
✨ Deployment time: 1.11s
Stack ARN:
...
✨ Total time: 4.29s
Dev/DatabaseStack (Dev-DatabaseStack)
Dev/DatabaseStack (Dev-DatabaseStack): deploying... [2/2]
✅ Dev/DatabaseStack (Dev-DatabaseStack)
✨ Deployment time: 1.09s
Stack ARN:
...
✨ Total time: 4.27s
```
# AWS CDK Constructs
Constructs are the basic building blocks of AWS Cloud Development Kit (AWS CDK) applications. A construct is a component within your application that represents one or more AWS CloudFormation resources and their configuration. You build your application, piece by piece, by importing and configuring constructs.
## Import and use constructs
Constructs are classes that you import into your CDK applications from the [AWS Construct Library](libraries.md#libraries-construct). You can also create and distribute your own constructs, or use constructs created by third-party developers.
Constructs are part of the Construct Programming Model (CPM). They are available to use with other tools such as CDK for Terraform (CDKtf), CDK for Kubernetes (CDK8s), and Projen.
Numerous third parties have also published constructs compatible with the AWS CDK. Visit [Construct Hub](https://constructs.dev/search?q=&cdk=aws-cdk&cdkver=2&offset=0) to explore the AWS CDK construct partner ecosystem.
## Construct levels
Constructs from the AWS Construct Library are categorized into three levels. Each level offers an increasing level of abstraction. The higher the abstraction, the easier to configure, requiring less expertise. The lower the abstraction, the more customization available, requiring more expertise.
**Level 1 (L1) constructs**
L1 constructs, also known as *CFN resources*, are the lowest-level construct and offer no abstraction. Each L1 construct maps directly to a single AWS CloudFormation resource. With L1 constructs, you import a construct that represents a specific AWS CloudFormation resource. You then define the resource’s properties within your construct instance.
L1 constructs are great to use when you are familiar with AWS CloudFormation and need complete control over defining your AWS resource properties.
In the AWS Construct Library, L1 constructs are named starting with `Cfn`, followed by an identifier for the AWS CloudFormation resource that it represents. For example, the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.CfnBucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.CfnBucket.html) construct is an L1 construct that represents an [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) AWS CloudFormation resource.
L1 constructs are generated from the [AWS CloudFormation resource specification](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-resource-specification.html). If a resource exists in AWS CloudFormation, it’ll be available in the AWS CDK as an L1 construct. New resources or properties may take up to a week to become available in the AWS Construct Library. For more information, see [AWS resource and property types reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) in the * AWS CloudFormation User Guide*.
**Level 2 (L2) constructs**
L2 constructs, also known as *curated* constructs, are thoughtfully developed by the CDK team and are usually the most widely used construct type. L2 constructs map directly to single AWS CloudFormation resources, similar to L1 constructs. Compared to L1 constructs, L2 constructs provide a higher-level abstraction through an intuitive intent-based API. L2 constructs include sensible default property configurations, best practice security policies, and generate a lot of the boilerplate code and glue logic for you.
L2 constructs also provide helper methods for most resources that make it simpler and quicker to define properties, permissions, event-based interactions between resources, and more. Many of these features are also available as independent building blocks called [Mixins](mixins.md), which can be applied to both L1 and L2 constructs using the `.with()` method.
The [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) class is an example of an L2 construct for an Amazon Simple Storage Service (Amazon S3) bucket resource.
The AWS Construct Library contains L2 constructs that are designated stable and ready for production use. For L2 constructs under development, they are designated as experimental and offered in a separate module.
**Level 3 (L3) constructs**
L3 constructs, also known as *patterns*, are the highest-level of abstraction. Each L3 construct can contain a collection of resources that are configured to work together to accomplish a specific task or service within your application. L3 constructs are used to create entire AWS architectures for particular use cases in your application.
To provide complete system designs, or substantial parts of a larger system, L3 constructs offer opinionated default property configurations. They are built around a particular approach toward solving a problem and providing a solution. With L3 constructs, you can create and configure multiple resources quickly, with the fewest amount of input and code.
The [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs_patterns.ApplicationLoadBalancedFargateService.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs_patterns.ApplicationLoadBalancedFargateService.html) class is an example of an L3 construct that represents an AWS Fargate service running on an Amazon Elastic Container Service (Amazon ECS) cluster and fronted by an application load balancer.
Similar to L2 constructs, L3 constructs that are ready for production use are included in the AWS Construct Library. Those under development are offered in separate modules.
## Defining constructs
### Composition
*Composition* is the key pattern for defining higher-level abstractions through constructs. A high-level construct can be composed from any number of lower-level constructs. From a bottom-up perspective, you use constructs to organize the individual AWS resources that you want to deploy. You use whatever abstractions are convenient for your purpose, with as many levels as you need.
With composition, you define reusable components and share them like any other code. For example, a team can define a construct that implements the company’s best practice for an Amazon DynamoDB table, including backup, global replication, automatic scaling, and monitoring. The team can share the construct internally with other teams, or publicly.
Teams can use constructs like any other library package. When the library is updated, developers get access to the new version’s improvements and bug fixes, similar to any other code library.
### Initialization
Constructs are implemented in classes that extend the [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html) base class. You define a construct by instantiating the class. All constructs take three parameters when they are initialized:
+ **scope** – The construct’s parent or owner. This can either be a stack or another construct. Scope determines the construct’s place in the [construct tree](apps.md#apps-tree). You should usually pass `this` (`self` in Python), which represents the current object, for the scope.
+ **id** – An [identifier](identifiers.md) that must be unique within the scope. The identifier serves as a namespace for everything that’s defined within the construct. It’s used to generate unique identifiers, such as [resource names](resources.md#resources-physical-names) and AWS CloudFormation logical IDs.
Identifiers need only be unique within a scope. This lets you instantiate and reuse constructs without concern for the constructs and identifiers they might contain, and enables composing constructs into higher-level abstractions. In addition, scopes make it possible to refer to groups of constructs all at once. Examples include for [tagging](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tag.html), or specifying where the constructs will be deployed.
+ **props** – A set of properties or keyword arguments, depending on the language, that define the construct’s initial configuration. Higher-level constructs provide more defaults, and if all prop elements are optional, you can omit the props parameter completely.
### Configuration
Most constructs accept `props` as their third argument (or in Python, keyword arguments), a name/value collection that defines the construct’s configuration. The following example defines a bucket with AWS Key Management Service (AWS KMS) encryption and static website hosting enabled. Since it does not explicitly specify an encryption key, the `Bucket` construct defines a new `kms.Key` and associates it with the bucket.
**Example**
```
new s3.Bucket(this, 'MyEncryptedBucket', {
encryption: s3.BucketEncryption.KMS,
websiteIndexDocument: 'index.html'
});
```
```
new s3.Bucket(this, 'MyEncryptedBucket', {
encryption: s3.BucketEncryption.KMS,
websiteIndexDocument: 'index.html'
});
```
```
s3.Bucket(self, "MyEncryptedBucket", encryption=s3.BucketEncryption.KMS,
website_index_document="index.html")
```
```
Bucket.Builder.create(this, "MyEncryptedBucket")
.encryption(BucketEncryption.KMS_MANAGED)
.websiteIndexDocument("index.html").build();
```
```
new Bucket(this, "MyEncryptedBucket", new BucketProps
{
Encryption = BucketEncryption.KMS_MANAGED,
WebsiteIndexDocument = "index.html"
});
```
```
awss3.NewBucket(stack, jsii.String("MyEncryptedBucket"), &awss3.BucketProps{
Encryption: awss3.BucketEncryption_KMS,
WebsiteIndexDocument: jsii.String("index.html"),
})
```
### Interacting with constructs
Constructs are classes that extend the base [Construct](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html) class. After you instantiate a construct, the construct object exposes a set of methods and properties that let you interact with the construct and pass it around as a reference to other parts of the system.
The AWS CDK framework doesn’t put any restrictions on the APIs of constructs. Authors can define any API they want. However, the AWS constructs that are included with the AWS Construct Library, such as `s3.Bucket`, follow guidelines and common patterns. This provides a consistent experience across all AWS resources.
Most AWS constructs have a set of [grant](permissions.md#permissions-grants) methods that you can use to grant AWS Identity and Access Management (IAM) permissions on that construct to a principal. The following example grants the IAM group `data-science` permission to read from the Amazon S3 bucket `raw-data`.
**Example**
```
const rawData = new s3.Bucket(this, 'raw-data');
const dataScience = new iam.Group(this, 'data-science');
rawData.grants.read(dataScience);
```
```
const rawData = new s3.Bucket(this, 'raw-data');
const dataScience = new iam.Group(this, 'data-science');
rawData.grants.read(dataScience);
```
```
raw_data = s3.Bucket(self, 'raw-data')
data_science = iam.Group(self, 'data-science')
raw_data.grants.read(data_science)
```
```
Bucket rawData = new Bucket(this, "raw-data");
Group dataScience = new Group(this, "data-science");
rawData.getGrants().read(dataScience);
```
```
var rawData = new Bucket(this, "raw-data");
var dataScience = new Group(this, "data-science");
rawData.Grants.Read(dataScience);
```
```
rawData := awss3.NewBucket(stack, jsii.String("raw-data"), nil)
dataScience := awsiam.NewGroup(stack, jsii.String("data-science"), nil)
rawData.Grants().Read(dataScience, nil)
```
Another common pattern is for AWS constructs to set one of the resource’s attributes from data supplied elsewhere. Attributes can include Amazon Resource Names (ARNs), names, or URLs.
The following code defines an AWS Lambda function and associates it with an Amazon Simple Queue Service (Amazon SQS) queue through the queue’s URL in an environment variable.
**Example**
```
const jobsQueue = new sqs.Queue(this, 'jobs');
const createJobLambda = new lambda.Function(this, 'create-job', {
runtime: lambda.Runtime.NODEJS_18_X,
handler: 'index.handler',
code: lambda.Code.fromAsset('./create-job-lambda-code'),
environment: {
QUEUE_URL: jobsQueue.queueUrl
}
});
```
```
const jobsQueue = new sqs.Queue(this, 'jobs');
const createJobLambda = new lambda.Function(this, 'create-job', {
runtime: lambda.Runtime.NODEJS_18_X,
handler: 'index.handler',
code: lambda.Code.fromAsset('./create-job-lambda-code'),
environment: {
QUEUE_URL: jobsQueue.queueUrl
}
});
```
```
jobs_queue = sqs.Queue(self, "jobs")
create_job_lambda = lambda_.Function(self, "create-job",
runtime=lambda_.Runtime.NODEJS_18_X,
handler="index.handler",
code=lambda_.Code.from_asset("./create-job-lambda-code"),
environment=dict(
QUEUE_URL=jobs_queue.queue_url
)
)
```
```
final Queue jobsQueue = new Queue(this, "jobs");
Function createJobLambda = Function.Builder.create(this, "create-job")
.handler("index.handler")
.code(Code.fromAsset("./create-job-lambda-code"))
.environment(java.util.Map.of( // Map.of is Java 9 or later
"QUEUE_URL", jobsQueue.getQueueUrl()))
.build();
```
```
var jobsQueue = new Queue(this, "jobs");
var createJobLambda = new Function(this, "create-job", new FunctionProps
{
Runtime = Runtime.NODEJS_18_X,
Handler = "index.handler",
Code = Code.FromAsset(@".\create-job-lambda-code"),
Environment = new Dictionary
{
["QUEUE_URL"] = jobsQueue.QueueUrl
}
});
```
```
createJobLambda := awslambda.NewFunction(stack, jsii.String("create-job"), &awslambda.FunctionProps{
Runtime: awslambda.Runtime_NODEJS_18_X(),
Handler: jsii.String("index.handler"),
Code: awslambda.Code_FromAsset(jsii.String(".\\create-job-lambda-code"), nil),
Environment: &map[string]*string{
"QUEUE_URL": jsii.String(*jobsQueue.QueueUrl()),
},
})
```
For information about the most common API patterns in the AWS Construct Library, see [Resources and the AWS CDK](resources.md).
### Add features with Mixins
Mixins are composable features that you can apply to any construct using the `.with()` method. Mixins let you add functionality to L1 and L2 constructs without having to use a different construct or write low-level code.
For example, you can enable versioning and block public access on an Amazon S3 bucket — whether it’s an L1 `CfnBucket` or an L2 `Bucket`:
**Example**
```
import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
// Apply mixins to an L1 construct
new s3.CfnBucket(this, 'MyBucket')
.with(new s3.mixins.BucketVersioning())
.with(new s3.mixins.BucketBlockPublicAccess());
// Apply mixins to an L2 construct
new s3.Bucket(this, 'MyL2Bucket', { removalPolicy: cdk.RemovalPolicy.DESTROY })
.with(new s3.mixins.BucketAutoDeleteObjects());
```
```
const cdk = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
// Apply mixins to an L1 construct
new s3.CfnBucket(this, 'MyBucket')
.with(new s3.mixins.BucketVersioning())
.with(new s3.mixins.BucketBlockPublicAccess());
// Apply mixins to an L2 construct
new s3.Bucket(this, 'MyL2Bucket', { removalPolicy: cdk.RemovalPolicy.DESTROY })
.with(new s3.mixins.BucketAutoDeleteObjects());
```
```
import aws_cdk as cdk
import aws_cdk.aws_s3 as s3
# Apply mixins to an L1 construct
s3.CfnBucket(self, "MyBucket") \
.with_(s3.mixins.BucketVersioning()) \
.with_(s3.mixins.BucketBlockPublicAccess())
# Apply mixins to an L2 construct
s3.Bucket(self, "MyL2Bucket", removal_policy=cdk.RemovalPolicy.DESTROY) \
.with_(s3.mixins.BucketAutoDeleteObjects())
```
```
import software.amazon.awscdk.*;
import software.amazon.awscdk.services.s3.*;
// Apply mixins to an L1 construct
CfnBucket bucket = new CfnBucket(this, "MyBucket");
bucket.with(new BucketVersioning());
bucket.with(new BucketBlockPublicAccess());
// Apply mixins to an L2 construct
Bucket l2Bucket = Bucket.Builder.create(this, "MyL2Bucket")
.removalPolicy(RemovalPolicy.DESTROY)
.build();
l2Bucket.with(new BucketAutoDeleteObjects());
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.S3;
// Apply mixins to an L1 construct
var bucket = new CfnBucket(this, "MyBucket");
bucket.With(new BucketVersioning());
bucket.With(new BucketBlockPublicAccess());
// Apply mixins to an L2 construct
var l2Bucket = new Bucket(this, "MyL2Bucket", new BucketProps
{
RemovalPolicy = RemovalPolicy.DESTROY
});
l2Bucket.With(new BucketAutoDeleteObjects());
```
```
bucket := awss3.NewCfnBucket(stack, jsii.String("MyBucket"), nil)
bucket.With(awss3.NewBucketVersioning())
bucket.With(awss3.NewBucketBlockPublicAccess())
l2Bucket := awss3.NewBucket(stack, jsii.String("MyL2Bucket"), &awss3.BucketProps{
RemovalPolicy: awscdk.RemovalPolicy_DESTROY,
})
l2Bucket.With(awss3.NewBucketAutoDeleteObjects())
```
Mixins are available through the `mixins` namespace of each service module (for example, `s3.mixins`). Each mixin targets a specific resource type and is named after that resource. When you apply a mixin to an L2 construct, it automatically applies to the underlying L1 resource.
For more information about Mixins, see [Mixins](mixins.md).
### The app and stack construct
The [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html) and [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html) classes from the AWS Construct Library are unique constructs. Compared to other constructs, they don’t configure AWS resources on their own. Instead, they are used to provide context for your other constructs. All constructs that represent AWS resources must be defined, directly or indirectly, within the scope of a `Stack` construct. `Stack` constructs are defined within the scope of an `App` construct.
To learn more about CDK apps, see [AWS CDK apps](apps.md). To learn more about CDK stacks, see [Introduction to AWS CDK stacks](stacks.md).
The following example defines an app with a single stack. Within the stack, an L2 construct is used to configure an Amazon S3 bucket resource.
**Example**
```
import { App, Stack, StackProps } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
class HelloCdkStack extends Stack {
constructor(scope: App, id: string, props?: StackProps) {
super(scope, id, props);
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
}
}
const app = new App();
new HelloCdkStack(app, "HelloCdkStack");
```
```
const { App , Stack } = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
class HelloCdkStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
}
}
const app = new App();
new HelloCdkStack(app, "HelloCdkStack");
```
```
from aws_cdk import App, Stack
import aws_cdk.aws_s3 as s3
from constructs import Construct
class HelloCdkStack(Stack):
def __init__(self, scope: Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
s3.Bucket(self, "MyFirstBucket", versioned=True)
app = App()
HelloCdkStack(app, "HelloCdkStack")
```
Stack defined in `HelloCdkStack.java` file:
```
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.*;
public class HelloCdkStack extends Stack {
public HelloCdkStack(final Construct scope, final String id) {
this(scope, id, null);
}
public HelloCdkStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
Bucket.Builder.create(this, "MyFirstBucket")
.versioned(true).build();
}
}
```
App defined in `HelloCdkApp.java` file:
```
import software.amazon.awscdk.App;
import software.amazon.awscdk.StackProps;
public class HelloCdkApp {
public static void main(final String[] args) {
App app = new App();
new HelloCdkStack(app, "HelloCdkStack", StackProps.builder()
.build());
app.synth();
}
}
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.S3;
namespace HelloCdkApp
{
internal static class Program
{
public static void Main(string[] args)
{
var app = new App();
new HelloCdkStack(app, "HelloCdkStack");
app.Synth();
}
}
public class HelloCdkStack : Stack
{
public HelloCdkStack(Construct scope, string id, IStackProps props=null) : base(scope, id, props)
{
new Bucket(this, "MyFirstBucket", new BucketProps { Versioned = true });
}
}
}
```
```
func NewHelloCdkStack(scope constructs.Construct, id string, props *HelloCdkStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
awss3.NewBucket(stack, jsii.String("MyFirstBucket"), &awss3.BucketProps{
Versioned: jsii.Bool(true),
})
return stack
}
```
## Working with constructs
### Working with L1 constructs
L1 constructs map directly to individual AWS CloudFormation resources. You must provide the resource’s required configuration.
In this example, we create a `bucket` object using the `CfnBucket` L1 construct:
**Example**
```
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket"
});
```
```
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket"
});
```
```
bucket = s3.CfnBucket(self, "amzn-s3-demo-bucket", bucket_name="amzn-s3-demo-bucket")
```
```
CfnBucket bucket = new CfnBucket.Builder().bucketName("amzn-s3-demo-bucket").build();
```
```
var bucket = new CfnBucket(this, "amzn-s3-demo-bucket", new CfnBucketProps
{
BucketName= "amzn-s3-demo-bucket"
});
```
```
awss3.NewCfnBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.CfnBucketProps{
BucketName: jsii.String("amzn-s3-demo-bucket"),
})
```
Construct properties that aren’t simple Booleans, strings, numbers, or containers are handled differently in the supported languages.
**Example**
```
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket",
corsConfiguration: {
corsRules: [{
allowedOrigins: ["*"],
allowedMethods: ["GET"]
}]
}
});
```
```
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket",
corsConfiguration: {
corsRules: [{
allowedOrigins: ["*"],
allowedMethods: ["GET"]
}]
}
});
```
In Python, these properties are represented by types defined as inner classes of the L1 construct. For example, the optional property `cors_configuration` of a `CfnBucket` requires a wrapper of type `CfnBucket.CorsConfigurationProperty`. Here we are defining `cors_configuration` on a `CfnBucket` instance.
```
bucket = CfnBucket(self, "amzn-s3-demo-bucket", bucket_name="amzn-s3-demo-bucket",
cors_configuration=CfnBucket.CorsConfigurationProperty(
cors_rules=[CfnBucket.CorsRuleProperty(
allowed_origins=["*"],
allowed_methods=["GET"]
)]
)
)
```
In Java, these properties are represented by types defined as inner classes of the L1 construct. For example, the optional property `corsConfiguration` of a `CfnBucket` requires a wrapper of type `CfnBucket.CorsConfigurationProperty`. Here we are defining `corsConfiguration` on a `CfnBucket` instance.
```
CfnBucket bucket = CfnBucket.Builder.create(this, "amzn-s3-demo-bucket")
.bucketName("amzn-s3-demo-bucket")
.corsConfiguration(new CfnBucket.CorsConfigurationProperty.Builder()
.corsRules(Arrays.asList(new CfnBucket.CorsRuleProperty.Builder()
.allowedOrigins(Arrays.asList("*"))
.allowedMethods(Arrays.asList("GET"))
.build()))
.build())
.build();
```
In C\$1, these properties are represented by types defined as inner classes of the L1 construct. For example, the optional property `CorsConfiguration` of a `CfnBucket` requires a wrapper of type `CfnBucket.CorsConfigurationProperty`. Here we are defining `CorsConfiguration` on a `CfnBucket` instance.
```
var bucket = new CfnBucket(this, "amzn-s3-demo-bucket", new CfnBucketProps
{
BucketName = "amzn-s3-demo-bucket",
CorsConfiguration = new CfnBucket.CorsConfigurationProperty
{
CorsRules = new object[] {
new CfnBucket.CorsRuleProperty
{
AllowedOrigins = new string[] { "*" },
AllowedMethods = new string[] { "GET" },
}
}
}
});
```
In Go, these types are named using the name of the L1 construct, an underscore, and the property name. For example, the optional property `CorsConfiguration` of a `CfnBucket` requires a wrapper of type `CfnBucket_CorsConfigurationProperty`. Here we are defining `CorsConfiguration` on a `CfnBucket` instance.
```
awss3.NewCfnBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.CfnBucketProps{
BucketName: jsii.String("amzn-s3-demo-bucket"),
CorsConfiguration: &awss3.CfnBucket_CorsConfigurationProperty{
CorsRules: []awss3.CorsRule{
awss3.CorsRule{
AllowedOrigins: jsii.Strings("*"),
AllowedMethods: &[]awss3.HttpMethods{"GET"},
},
},
},
})
```
**Important**
You can’t use L2 property types with L1 constructs, or vice versa. When working with L1 constructs, always use the types defined for the L1 construct you’re using. Do not use types from other L1 constructs (some may have the same name, but they are not the same type).
Some of our language-specific API references currently have errors in the paths to L1 property types, or don’t document these classes at all. We hope to fix this soon. In the meantime, remember that such types are always inner classes of the L1 construct they are used with.
#### Referencing resources from other constructs
When configuring construct properties that reference other AWS resources, you have two equivalent options:
+ **String references**: Pass explicit string values such as ARNs, names, or other resource identifiers
+ **Object references**: Pass construct objects directly. This avoids having to determine which identifier type a property expects—the CDK handles that for you.
##### Using string references
You can always pass explicit string values such as ARNs, names, or other resource identifiers. This approach works for all properties and is required for nested properties within complex objects.
The following example creates a Lambda function using an L1 construct (`CfnFunction`) with a role defined using an L2 construct (`Role`). The role’s ARN is passed to the `role` property:
**Example**
```
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
managedPolicies: [
iam.ManagedPolicy.fromAwsManagedPolicyName(
'service-role/AWSLambdaBasicExecutionRole'
),
],
});
const myFunction = new lambda.CfnFunction(this, 'HelloWorldFunction', {
runtime: 'nodejs24.x',
role: role.roleArn, // Pass the ARN string explicitly
handler: 'index.handler',
code: {
zipFile: `
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`}
});
```
```
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
managedPolicies: [
iam.ManagedPolicy.fromAwsManagedPolicyName(
'service-role/AWSLambdaBasicExecutionRole'
)
]
});
const myFunction = new lambda.CfnFunction(this, "HelloWorldFunction", {
runtime: 'nodejs24.x',
role: role.roleArn, // Pass the ARN string explicitly
handler: 'index.handler',
code: {
zipFile: `
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`}
});
```
```
role = iam.Role(self, "MyRole",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
managed_policies=[
iam.ManagedPolicy.from_aws_managed_policy_name(
"service-role/AWSLambdaBasicExecutionRole"
)
]
)
my_function = _lambda.CfnFunction(self, "HelloWorldFunction",
runtime="nodejs24.x",
role=role.role_arn, # Pass the ARN string explicitly
handler="index.handler",
code=_lambda.CfnFunction.CodeProperty(
zip_file=
"""
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"""
)
)
```
```
Role role = Role.Builder.create(this, "MyRole")
.assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
.managedPolicies(Arrays.asList(
ManagedPolicy.fromAwsManagedPolicyName(
"service-role/AWSLambdaBasicExecutionRole"
)
))
.build();
CfnFunction myFunction = CfnFunction.Builder.create(this, "HelloWorldFunction")
.runtime("nodejs24.x")
.role(role.getRoleArn()) // Pass the ARN string explicitly
.handler("index.handler")
.code(CfnFunction.CodeProperty.builder()
.zipFile(
"exports.handler = async function(event) {" +
" return {" +
" statusCode: 200," +
" body: JSON.stringify('Hello World!')," +
" };" +
"};")
.build())
.build();
```
```
var role = new Role(this, "MyRole", new RoleProps
{
AssumedBy = new ServicePrincipal("lambda.amazonaws.com"),
ManagedPolicies = new[]
{
ManagedPolicy.FromAwsManagedPolicyName(
"service-role/AWSLambdaBasicExecutionRole"
)
}
});
var myFunction = new CfnFunction(this, "HelloWorldFunction", new CfnFunctionProps
{
Runtime = "nodejs24.x",
Role = role.RoleArn, // Pass the ARN string explicitly
Handler = "index.handler",
Code = new CfnFunction.CodeProperty
{
ZipFile = @"
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"
}
});
```
```
role := awsiam.NewRole(stack, jsii.String("MyRole"), &awsiam.RoleProps{
AssumedBy: awsiam.NewServicePrincipal(jsii.String("lambda.amazonaws.com"), nil),
ManagedPolicies: &[]awsiam.IManagedPolicy{
awsiam.ManagedPolicy_FromAwsManagedPolicyName(jsii.String("service-role/AWSLambdaBasicExecutionRole")),
},
})
myFunction := awslambda.NewCfnFunction(stack, jsii.String("HelloWorldFunction"), &awslambda.CfnFunctionProps{
Runtime: jsii.String("nodejs24.x"),
Role: role.RoleArn(), // Pass the ARN string explicitly
Handler: jsii.String("index.handler"),
Code: &awslambda.CfnFunction_CodeProperty{
ZipFile: jsii.String(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
},
})
```
##### Using object references
For selected properties, you can pass construct objects directly instead of extracting their attributes manually. Support for object references varies by property and may expand over time as new properties are added.
When you pass an object reference in the construct’s `props`, the CDK resolves it to the appropriate string value (such as an ARN, name, or other identifier). If you later access the corresponding property on the construct instance, you’ll see this resolved string value, not the original object reference.
Object references work only for top-level properties of constructs. Nested properties within complex objects require explicit string values.
The following example shows the same Lambda function, but using the role object instead of the role’s ARN string:
**Example**
```
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
managedPolicies: [
iam.ManagedPolicy.fromAwsManagedPolicyName(
'service-role/AWSLambdaBasicExecutionRole'
),
],
});
const myFunction = new lambda.CfnFunction(this, 'HelloWorldFunction', {
runtime: 'nodejs24.x',
role: role, // CDK resolves to role ARN automatically
handler: 'index.handler',
code: {
zipFile: `
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`}
});
// After creation, myFunction.role contains the resolved ARN string
```
```
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
managedPolicies: [
iam.ManagedPolicy.fromAwsManagedPolicyName(
'service-role/AWSLambdaBasicExecutionRole'
)
]
});
const myFunction = new lambda.CfnFunction(this, "HelloWorldFunction", {
runtime: 'nodejs24.x',
role: role, // CDK resolves to role ARN automatically
handler: 'index.handler',
code: {
zipFile: `
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`}
});
// After creation, myFunction.role contains the resolved ARN string
```
```
role = iam.Role(self, "MyRole",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
managed_policies=[
iam.ManagedPolicy.from_aws_managed_policy_name(
"service-role/AWSLambdaBasicExecutionRole"
)
]
)
my_function = _lambda.CfnFunction(self, "HelloWorldFunction",
runtime="nodejs24.x",
role=role, # CDK resolves to role ARN automatically
handler="index.handler",
code=_lambda.CfnFunction.CodeProperty(
zip_file=
"""
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"""
)
)
# After creation, my_function.role contains the resolved ARN string
```
```
Role role = Role.Builder.create(this, "MyRole")
.assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
.managedPolicies(Arrays.asList(
ManagedPolicy.fromAwsManagedPolicyName(
"service-role/AWSLambdaBasicExecutionRole"
)
))
.build();
CfnFunction myFunction = CfnFunction.Builder.create(this, "HelloWorldFunction")
.runtime("nodejs24.x")
.role(role) // CDK resolves to role ARN automatically
.handler("index.handler")
.code(CfnFunction.CodeProperty.builder()
.zipFile(
"exports.handler = async function(event) {" +
" return {" +
" statusCode: 200," +
" body: JSON.stringify('Hello World!')," +
" };" +
"};")
.build())
.build();
// After creation, myFunction.getRole() contains the resolved ARN string
```
```
var role = new Role(this, "MyRole", new RoleProps
{
AssumedBy = new ServicePrincipal("lambda.amazonaws.com"),
ManagedPolicies = new[]
{
ManagedPolicy.FromAwsManagedPolicyName(
"service-role/AWSLambdaBasicExecutionRole"
)
}
});
var myFunction = new CfnFunction(this, "HelloWorldFunction", new CfnFunctionProps
{
Runtime = "nodejs24.x",
Role = role, // CDK resolves to role ARN automatically
Handler = "index.handler",
Code = new CfnFunction.CodeProperty
{
ZipFile = @"
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"
}
});
// After creation, myFunction.Role contains the resolved ARN string
```
```
role := awsiam.NewRole(stack, jsii.String("MyRole"), &awsiam.RoleProps{
AssumedBy: awsiam.NewServicePrincipal(jsii.String("lambda.amazonaws.com"), nil),
ManagedPolicies: &[]awsiam.IManagedPolicy{
awsiam.ManagedPolicy_FromAwsManagedPolicyName(jsii.String("service-role/AWSLambdaBasicExecutionRole")),
},
})
myFunction := awslambda.NewCfnFunction(stack, jsii.String("HelloWorldFunction"), &awslambda.CfnFunctionProps{
Runtime: jsii.String("nodejs24.x"),
Role: role, // CDK resolves to role ARN automatically
Handler: jsii.String("index.handler"),
Code: &awslambda.CfnFunction_CodeProperty{
ZipFile: jsii.String(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
},
})
// After creation, *myFunction.Role() contains the resolved ARN string
```
### Working with L2 constructs
In the following example, we define an Amazon S3 bucket by creating an object from the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) L2 construct:
**Example**
```
import * as s3 from 'aws-cdk-lib/aws-s3';
// "this" is HelloCdkStack
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
```
```
const s3 = require('aws-cdk-lib/aws-s3');
// "this" is HelloCdkStack
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
```
```
import aws_cdk.aws_s3 as s3
# "self" is HelloCdkStack
s3.Bucket(self, "MyFirstBucket", versioned=True)
```
```
import software.amazon.awscdk.services.s3.*;
public class HelloCdkStack extends Stack {
public HelloCdkStack(final Construct scope, final String id) {
this(scope, id, null);
}
public HelloCdkStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
Bucket.Builder.create(this, "MyFirstBucket")
.versioned(true).build();
}
}
```
```
using Amazon.CDK.AWS.S3;
// "this" is HelloCdkStack
new Bucket(this, "MyFirstBucket", new BucketProps
{
Versioned = true
});
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
"github.com/aws/jsii-runtime-go"
)
// stack is HelloCdkStack
awss3.NewBucket(stack, jsii.String("MyFirstBucket"), &awss3.BucketProps{
Versioned: jsii.Bool(true),
})
```
`MyFirstBucket` is not the name of the bucket that AWS CloudFormation creates. It is a logical identifier given to the new construct within the context of your CDK app. The [physicalName](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Resource.html#physicalname) value will be used to name the AWS CloudFormation resource.
## Working with third-party constructs
[Construct Hub](https://constructs.dev/search?q=&cdk=aws-cdk&cdkver=2&sort=downloadsDesc&offset=0) is a resource to help you discover additional constructs from AWS, third parties, and the open-source CDK community.
### Writing your own constructs
In addition to using existing constructs, you can also write your own constructs and let anyone use them in their apps. All constructs are equal in the AWS CDK. Constructs from the AWS Construct Library are treated the same as a construct from a third-party library published via NPM, Maven, or PyPI. Constructs published to your company’s internal package repository are also treated in the same way.
To declare a new construct, create a class that extends the [Construct](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html) base class, in the `constructs` package, then follow the pattern for initializer arguments.
The following example shows how to declare a construct that represents an Amazon S3 bucket. The S3 bucket sends an Amazon Simple Notification Service (Amazon SNS) notification every time someone uploads a file into it.
**Example**
```
export interface NotifyingBucketProps {
prefix?: string;
}
export class NotifyingBucket extends Construct {
constructor(scope: Construct, id: string, props: NotifyingBucketProps = {}) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
const topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(topic),
{ prefix: props.prefix });
}
}
```
```
class NotifyingBucket extends Construct {
constructor(scope, id, props = {}) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
const topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(topic),
{ prefix: props.prefix });
}
}
module.exports = { NotifyingBucket }
```
```
class NotifyingBucket(Construct):
def __init__(self, scope: Construct, id: str, *, prefix=None):
super().__init__(scope, id)
bucket = s3.Bucket(self, "bucket")
topic = sns.Topic(self, "topic")
bucket.add_object_created_notification(s3notify.SnsDestination(topic),
s3.NotificationKeyFilter(prefix=prefix))
```
```
public class NotifyingBucket extends Construct {
public NotifyingBucket(final Construct scope, final String id) {
this(scope, id, null, null);
}
public NotifyingBucket(final Construct scope, final String id, final BucketProps props) {
this(scope, id, props, null);
}
public NotifyingBucket(final Construct scope, final String id, final String prefix) {
this(scope, id, null, prefix);
}
public NotifyingBucket(final Construct scope, final String id, final BucketProps props, final String prefix) {
super(scope, id);
Bucket bucket = new Bucket(this, "bucket");
Topic topic = new Topic(this, "topic");
if (prefix != null)
bucket.addObjectCreatedNotification(new SnsDestination(topic),
NotificationKeyFilter.builder().prefix(prefix).build());
}
}
```
```
public class NotifyingBucketProps : BucketProps
{
public string Prefix { get; set; }
}
public class NotifyingBucket : Construct
{
public NotifyingBucket(Construct scope, string id, NotifyingBucketProps props = null) : base(scope, id)
{
var bucket = new Bucket(this, "bucket");
var topic = new Topic(this, "topic");
bucket.AddObjectCreatedNotification(new SnsDestination(topic), new NotificationKeyFilter
{
Prefix = props?.Prefix
});
}
}
```
```
type NotifyingBucketProps struct {
awss3.BucketProps
Prefix *string
}
func NewNotifyingBucket(scope constructs.Construct, id *string, props *NotifyingBucketProps) awss3.Bucket {
var bucket awss3.Bucket
if props == nil {
bucket = awss3.NewBucket(scope, jsii.String(*id+"Bucket"), nil)
} else {
bucket = awss3.NewBucket(scope, jsii.String(*id+"Bucket"), &props.BucketProps)
}
topic := awssns.NewTopic(scope, jsii.String(*id+"Topic"), nil)
if props == nil {
bucket.AddObjectCreatedNotification(awss3notifications.NewSnsDestination(topic))
} else {
bucket.AddObjectCreatedNotification(awss3notifications.NewSnsDestination(topic), &awss3.NotificationKeyFilter{
Prefix: props.Prefix,
})
}
return bucket
}
```
**Note**
Our `NotifyingBucket` construct inherits not from `Bucket` but rather from `Construct`. We are using composition, not inheritance, to bundle an Amazon S3 bucket and an Amazon SNS topic together. In general, composition is preferred over inheritance when developing AWS CDK constructs.
The `NotifyingBucket` constructor has a typical construct signature: `scope`, `id`, and `props`. The last argument, `props`, is optional (gets the default value `{}`) because all props are optional. (The base `Construct` class does not take a `props` argument.) You could define an instance of this construct in your app without `props`, for example:
**Example**
```
new NotifyingBucket(this, 'MyNotifyingBucket');
```
```
new NotifyingBucket(this, 'MyNotifyingBucket');
```
```
NotifyingBucket(self, "MyNotifyingBucket")
```
```
new NotifyingBucket(this, "MyNotifyingBucket");
```
```
new NotifyingBucket(this, "MyNotifyingBucket");
```
```
NewNotifyingBucket(stack, jsii.String("MyNotifyingBucket"), nil)
```
Or you could use `props` (in Java, an additional parameter) to specify the path prefix to filter on, for example:
**Example**
```
new NotifyingBucket(this, 'MyNotifyingBucket', { prefix: 'images/' });
```
```
new NotifyingBucket(this, 'MyNotifyingBucket', { prefix: 'images/' });
```
```
NotifyingBucket(self, "MyNotifyingBucket", prefix="images/")
```
```
new NotifyingBucket(this, "MyNotifyingBucket", "/images");
```
```
new NotifyingBucket(this, "MyNotifyingBucket", new NotifyingBucketProps
{
Prefix = "/images"
});
```
```
NewNotifyingBucket(stack, jsii.String("MyNotifyingBucket"), &NotifyingBucketProps{
Prefix: jsii.String("images/"),
})
```
Typically, you would also want to expose some properties or methods on your constructs. It’s not very useful to have a topic hidden behind your construct, because users of your construct aren’t able to subscribe to it. Adding a `topic` property lets consumers access the inner topic, as shown in the following example:
**Example**
```
export class NotifyingBucket extends Construct {
public readonly topic: sns.Topic;
constructor(scope: Construct, id: string, props: NotifyingBucketProps) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
this.topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(this.topic), { prefix: props.prefix });
}
}
```
```
class NotifyingBucket extends Construct {
constructor(scope, id, props) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
this.topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(this.topic), { prefix: props.prefix });
}
}
module.exports = { NotifyingBucket };
```
```
class NotifyingBucket(Construct):
def __init__(self, scope: Construct, id: str, *, prefix=None, **kwargs):
super().__init__(scope, id)
bucket = s3.Bucket(self, "bucket")
self.topic = sns.Topic(self, "topic")
bucket.add_object_created_notification(s3notify.SnsDestination(self.topic),
s3.NotificationKeyFilter(prefix=prefix))
```
```
public class NotifyingBucket extends Construct {
public Topic topic = null;
public NotifyingBucket(final Construct scope, final String id) {
this(scope, id, null, null);
}
public NotifyingBucket(final Construct scope, final String id, final BucketProps props) {
this(scope, id, props, null);
}
public NotifyingBucket(final Construct scope, final String id, final String prefix) {
this(scope, id, null, prefix);
}
public NotifyingBucket(final Construct scope, final String id, final BucketProps props, final String prefix) {
super(scope, id);
Bucket bucket = new Bucket(this, "bucket");
topic = new Topic(this, "topic");
if (prefix != null)
bucket.addObjectCreatedNotification(new SnsDestination(topic),
NotificationKeyFilter.builder().prefix(prefix).build());
}
}
```
```
public class NotifyingBucket : Construct
{
public readonly Topic topic;
public NotifyingBucket(Construct scope, string id, NotifyingBucketProps props = null) : base(scope, id)
{
var bucket = new Bucket(this, "bucket");
topic = new Topic(this, "topic");
bucket.AddObjectCreatedNotification(new SnsDestination(topic), new NotificationKeyFilter
{
Prefix = props?.Prefix
});
}
}
```
To do this in Go, we’ll need a little extra plumbing. Our original `NewNotifyingBucket` function returned an `awss3.Bucket`. We’ll need to extend `Bucket` to include a `topic` member by creating a `NotifyingBucket` struct. Our function will then return this type.
```
type NotifyingBucket struct {
awss3.Bucket
topic awssns.Topic
}
func NewNotifyingBucket(scope constructs.Construct, id *string, props *NotifyingBucketProps) NotifyingBucket {
var bucket awss3.Bucket
if props == nil {
bucket = awss3.NewBucket(scope, jsii.String(*id+"Bucket"), nil)
} else {
bucket = awss3.NewBucket(scope, jsii.String(*id+"Bucket"), &props.BucketProps)
}
topic := awssns.NewTopic(scope, jsii.String(*id+"Topic"), nil)
if props == nil {
bucket.AddObjectCreatedNotification(awss3notifications.NewSnsDestination(topic))
} else {
bucket.AddObjectCreatedNotification(awss3notifications.NewSnsDestination(topic), &awss3.NotificationKeyFilter{
Prefix: props.Prefix,
})
}
var nbucket NotifyingBucket
nbucket.Bucket = bucket
nbucket.topic = topic
return nbucket
}
```
Now, consumers can subscribe to the topic, for example:
**Example**
```
const queue = new sqs.Queue(this, 'NewImagesQueue');
const images = new NotifyingBucket(this, '/images');
images.topic.addSubscription(new sns_sub.SqsSubscription(queue));
```
```
const queue = new sqs.Queue(this, 'NewImagesQueue');
const images = new NotifyingBucket(this, '/images');
images.topic.addSubscription(new sns_sub.SqsSubscription(queue));
```
```
queue = sqs.Queue(self, "NewImagesQueue")
images = NotifyingBucket(self, prefix="Images")
images.topic.add_subscription(sns_sub.SqsSubscription(queue))
```
```
NotifyingBucket images = new NotifyingBucket(this, "MyNotifyingBucket", "/images");
images.topic.addSubscription(new SqsSubscription(queue));
```
```
var queue = new Queue(this, "NewImagesQueue");
var images = new NotifyingBucket(this, "MyNotifyingBucket", new NotifyingBucketProps
{
Prefix = "/images"
});
images.topic.AddSubscription(new SqsSubscription(queue));
```
```
queue := awssqs.NewQueue(stack, jsii.String("NewImagesQueue"), nil)
images := NewNotifyingBucket(stack, jsii.String("MyNotifyingBucket"), &NotifyingBucketProps{
Prefix: jsii.String("/images"),
})
images.topic.AddSubscription(awssnssubscriptions.NewSqsSubscription(queue, nil))
```
## Learn more
The following video provides a comprehensive overview of CDK constructs, and explains how you can use them in your CDK apps.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/PzU-i0rJPGw?rel=0)
# Mixins
Mixins are reusable features that you apply to constructs using the `.with()` method. They add features to both L1 (CloudFormation-level) and L2 (intent-based) constructs, such as versioning, auto-deleting objects, or blocking public access. Each mixin works on a single resource. To connect two resources, use [Facades](facades.md) instead.
Each mixin targets a specific resource type and is named after that resource. For example, `BucketVersioning` targets Amazon S3 buckets. You access mixins through the `mixins` namespace of each service module, such as `s3.mixins`.
## Apply Mixins
You apply mixins using the `.with()` method, which is available on all constructs. You can chain multiple mixins together:
**Example**
```
import * as s3 from 'aws-cdk-lib/aws-s3';
const bucket = new s3.CfnBucket(this, 'MyBucket')
.with(new s3.mixins.BucketVersioning())
.with(new s3.mixins.BucketBlockPublicAccess());
```
```
const s3 = require('aws-cdk-lib/aws-s3');
const bucket = new s3.CfnBucket(this, 'MyBucket')
.with(new s3.mixins.BucketVersioning())
.with(new s3.mixins.BucketBlockPublicAccess());
```
```
import aws_cdk.aws_s3 as s3
bucket = s3.CfnBucket(self, "MyBucket") \
.with_(s3.mixins.BucketVersioning()) \
.with_(s3.mixins.BucketBlockPublicAccess())
```
```
import software.amazon.awscdk.services.s3.*;
CfnBucket bucket = new CfnBucket(this, "MyBucket");
bucket.with(new BucketVersioning());
bucket.with(new BucketBlockPublicAccess());
```
```
using Amazon.CDK.AWS.S3;
var bucket = new CfnBucket(this, "MyBucket");
bucket.With(new BucketVersioning());
bucket.With(new BucketBlockPublicAccess());
```
```
bucket := awss3.NewCfnBucket(stack, jsii.String("MyBucket"), nil)
bucket.With(awss3.NewBucketVersioning())
bucket.With(awss3.NewBucketBlockPublicAccess())
```
Each mixin declares which resource types it supports. If you apply a mixin to a construct it does not support, it is silently skipped. This means you can safely apply mixins broadly without worrying about type mismatches. If you need to ensure a mixin is applied, use [`requireAll()` or `requireAny()`](#mixins-advanced).
## Use Mixins with L1 and L2 constructs
Mixins work with both L1 and L2 constructs. When you apply a mixin to an L2 construct, it also applies to the L1 resource behind it.
The following example shows how to apply mixins to both L1 and L2 constructs:
**Example**
```
import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
// Using a mixin with an L1 construct
new s3.CfnBucket(this, 'L1Bucket')
.with(new s3.mixins.BucketVersioning());
// Using a mixin with an L2 construct
new s3.Bucket(this, 'L2Bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
}).with(new s3.mixins.BucketAutoDeleteObjects());
```
```
const cdk = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
// Using a mixin with an L1 construct
new s3.CfnBucket(this, 'L1Bucket')
.with(new s3.mixins.BucketVersioning());
// Using a mixin with an L2 construct
new s3.Bucket(this, 'L2Bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
}).with(new s3.mixins.BucketAutoDeleteObjects());
```
```
import aws_cdk as cdk
import aws_cdk.aws_s3 as s3
# Using a mixin with an L1 construct
s3.CfnBucket(self, "L1Bucket") \
.with_(s3.mixins.BucketVersioning())
# Using a mixin with an L2 construct
s3.Bucket(self, "L2Bucket",
removal_policy=cdk.RemovalPolicy.DESTROY,
).with_(s3.mixins.BucketAutoDeleteObjects())
```
```
import software.amazon.awscdk.*;
import software.amazon.awscdk.services.s3.*;
// Using a mixin with an L1 construct
CfnBucket l1Bucket = new CfnBucket(this, "L1Bucket");
l1Bucket.with(new BucketVersioning());
// Using a mixin with an L2 construct
Bucket l2Bucket = Bucket.Builder.create(this, "L2Bucket")
.removalPolicy(RemovalPolicy.DESTROY)
.build();
l2Bucket.with(new BucketAutoDeleteObjects());
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.S3;
// Using a mixin with an L1 construct
var l1Bucket = new CfnBucket(this, "L1Bucket");
l1Bucket.With(new BucketVersioning());
// Using a mixin with an L2 construct
var l2Bucket = new Bucket(this, "L2Bucket", new BucketProps
{
RemovalPolicy = RemovalPolicy.DESTROY
});
l2Bucket.With(new BucketAutoDeleteObjects());
```
```
l1Bucket := awss3.NewCfnBucket(stack, jsii.String("L1Bucket"), nil)
l1Bucket.With(awss3.NewBucketVersioning())
l2Bucket := awss3.NewBucket(stack, jsii.String("L2Bucket"), &awss3.BucketProps{
RemovalPolicy: awscdk.RemovalPolicy_DESTROY,
})
l2Bucket.With(awss3.NewBucketAutoDeleteObjects())
```
## Mixins vs. construct properties
Mixins and construct properties work together. L2 construct properties set up a resource when you create it. Mixins can be applied at any time.
Use L2 construct properties when
You are using an L2 construct and the property you need is available. This is the simplest approach.
Use Mixins when
+ You are working with an L1 construct and want L2-like features.
+ You want to add a feature to an L2 construct that is not available as a property.
+ You want to apply the same feature across multiple constructs of different types.
Mixins do not replace construct properties. They cannot make a required property optional or change default values.
## Apply Mixins to multiple constructs
The `Mixins.of()` API provides more control over how mixins are applied across a scope. Instead of calling `.with()` on individual constructs, you can apply a mixin to all matching constructs in a stack or scope at once:
**Example**
```
import { Mixins } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
// Apply to all supported constructs in the stack
Mixins.of(stack).apply(new s3.mixins.BucketVersioning());
```
```
const { Mixins } = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
// Apply to all supported constructs in the stack
Mixins.of(stack).apply(new s3.mixins.BucketVersioning());
```
```
from aws_cdk import Mixins
import aws_cdk.aws_s3 as s3
# Apply to all supported constructs in the stack
Mixins.of(stack).apply(s3.mixins.BucketVersioning())
```
```
import software.amazon.awscdk.Mixins;
import software.amazon.awscdk.services.s3.*;
// Apply to all supported constructs in the stack
Mixins.of(stack).apply(new BucketVersioning());
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.S3;
// Apply to all supported constructs in the stack
Mixins.Of(stack).Apply(new BucketVersioning());
```
```
awscdk.Mixins_Of(stack, nil).Apply(awss3.NewBucketVersioning())
```
By default, constructs that don’t support the mixin are silently skipped. Use `requireAll()` to assert that the mixin is applied to every construct in the selection, or `requireAny()` to assert it is applied to at least one. This is useful for enforcing that resources have a required configuration:
**Example**
```
// Throws an error if any construct in the scope doesn't support the mixin
Mixins.of(stack)
.requireAll()
.apply(new s3.mixins.BucketVersioning());
```
```
// Throws an error if any construct in the scope doesn't support the mixin
Mixins.of(stack)
.requireAll()
.apply(new s3.mixins.BucketVersioning());
```
```
# Throws an error if any construct in the scope doesn't support the mixin
Mixins.of(stack) \
.require_all() \
.apply(s3.mixins.BucketVersioning())
```
```
// Throws an error if any construct in the scope doesn't support the mixin
Mixins.of(stack)
.requireAll()
.apply(new BucketVersioning());
```
```
// Throws an error if any construct in the scope doesn't support the mixin
Mixins.Of(stack)
.RequireAll()
.Apply(new BucketVersioning());
```
```
awscdk.Mixins_Of(stack, nil).RequireAll().Apply(awss3.NewBucketVersioning())
```
## Mixins and Aspects
Mixins and [Aspects](aspects.md) are related but serve different purposes:
+ **Mixins** are applied immediately when you call `.with()`. You choose exactly which constructs to apply them to.
+ **Aspects** apply during synthesis to all constructs in a scope. Use them for broad policies and checks.
Use Mixins to add a feature to specific constructs. Use Aspects to enforce rules or apply changes across your entire application.
## Related resources
+ [Facades](facades.md) – Connect resources with IAM principals and other services.
+ [Aspects](aspects.md) – Apply changes or validate constructs across your entire application.
+ [Constructs](constructs.md) – Learn about L1, L2, and L3 constructs.
+ [Customize constructs](cfn-layer.md) – Customize constructs with escape hatches and raw overrides.
# Facades
Facades are classes that connect a resource with other parts of your application. Each Facade targets one resource type. For example, the class is named `BucketGrants` because it grants access to Amazon S3 buckets. Facades work with both L1 (CloudFormation-level) and L2 (intent-based) constructs.
Some Facades are generated and ready to use for most resources, such as metrics and reflections classes. Others are authored manually for resources that need custom logic, such as Grants classes.
## Grants classes
The most widely used Facades are Grants classes. They let you grant access to AWS resources using simple methods. For example, you can use `BucketGrants` for Amazon S3 buckets and `TopicGrants` for Amazon SNS topics.
L2 constructs have a `grants` property for easy access. You can also create a Grants class from an L1 construct using its factory method. The following example shows both approaches:
**Example**
```
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as iam from 'aws-cdk-lib/aws-iam';
// myRole is an IAM role defined elsewhere in your app
// Using grants on an L2 construct (via the grants property)
const l2Bucket = new s3.Bucket(this, 'L2Bucket');
l2Bucket.grants.read(myRole);
// Using grants on an L1 construct (via the factory method)
const l1Bucket = new s3.CfnBucket(this, 'L1Bucket');
s3.BucketGrants.fromBucket(l1Bucket).read(myRole);
```
```
const s3 = require('aws-cdk-lib/aws-s3');
const iam = require('aws-cdk-lib/aws-iam');
// myRole is an IAM role defined elsewhere in your app
// Using grants on an L2 construct (via the grants property)
const l2Bucket = new s3.Bucket(this, 'L2Bucket');
l2Bucket.grants.read(myRole);
// Using grants on an L1 construct (via the factory method)
const l1Bucket = new s3.CfnBucket(this, 'L1Bucket');
s3.BucketGrants.fromBucket(l1Bucket).read(myRole);
```
```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_iam as iam
# my_role is an IAM role defined elsewhere in your app
# Using grants on an L2 construct (via the grants property)
l2_bucket = s3.Bucket(self, "L2Bucket")
l2_bucket.grants.read(my_role)
# Using grants on an L1 construct (via the factory method)
l1_bucket = s3.CfnBucket(self, "L1Bucket")
s3.BucketGrants.from_bucket(l1_bucket).read(my_role)
```
```
import software.amazon.awscdk.services.s3.*;
import software.amazon.awscdk.services.iam.*;
// myRole is an IAM role defined elsewhere in your app
// Using grants on an L2 construct (via the grants property)
Bucket l2Bucket = new Bucket(this, "L2Bucket");
l2Bucket.getGrants().read(myRole);
// Using grants on an L1 construct (via the factory method)
CfnBucket l1Bucket = new CfnBucket(this, "L1Bucket");
BucketGrants.fromBucket(l1Bucket).read(myRole);
```
```
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.IAM;
// myRole is an IAM role defined elsewhere in your app
// Using grants on an L2 construct (via the grants property)
var l2Bucket = new Bucket(this, "L2Bucket");
l2Bucket.Grants.Read(myRole);
// Using grants on an L1 construct (via the factory method)
var l1Bucket = new CfnBucket(this, "L1Bucket");
BucketGrants.FromBucket(l1Bucket).Read(myRole);
```
```
import (
"github.com/aws/jsii-runtime-go"
awss3 "github.com/aws/aws-cdk-go/awscdk/v2/awss3"
)
// myRole is an IAM role defined elsewhere in your app
l2Bucket := awss3.NewBucket(stack, jsii.String("L2Bucket"), nil)
l2Bucket.Grants().Read(myRole, nil)
l1Bucket := awss3.NewCfnBucket(stack, jsii.String("L1Bucket"), nil)
awss3.BucketGrants_FromBucket(l1Bucket).Read(myRole, nil)
```
For more information about grants and permissions, see [Grants](permissions.md#permissions-grants).
## Use Facades with Mixins
You can combine Facades with [Mixins](mixins.md) to get a full L2-like experience on L1 constructs. Use Mixins to set up the resource, and Facades to grant access:
**Example**
```
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as iam from 'aws-cdk-lib/aws-iam';
// Configure the resource with Mixins
const bucket = new s3.CfnBucket(this, 'MyBucket')
.with(new s3.mixins.BucketVersioning())
.with(new s3.mixins.BucketBlockPublicAccess());
// Grant permissions using a Facade
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
});
s3.BucketGrants.fromBucket(bucket).read(role);
```
```
const s3 = require('aws-cdk-lib/aws-s3');
const iam = require('aws-cdk-lib/aws-iam');
// Configure the resource with Mixins
const bucket = new s3.CfnBucket(this, 'MyBucket')
.with(new s3.mixins.BucketVersioning())
.with(new s3.mixins.BucketBlockPublicAccess());
// Grant permissions using a Facade
const role = new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
});
s3.BucketGrants.fromBucket(bucket).read(role);
```
```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_iam as iam
# Configure the resource with Mixins
bucket = s3.CfnBucket(self, "MyBucket") \
.with_(s3.mixins.BucketVersioning()) \
.with_(s3.mixins.BucketBlockPublicAccess())
# Grant permissions using a Facade
role = iam.Role(self, "MyRole",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
)
s3.BucketGrants.from_bucket(bucket).read(role)
```
```
import software.amazon.awscdk.services.s3.*;
import software.amazon.awscdk.services.iam.*;
// Configure the resource with Mixins
CfnBucket bucket = new CfnBucket(this, "MyBucket");
bucket.with(new BucketVersioning());
bucket.with(new BucketBlockPublicAccess());
// Grant permissions using a Facade
Role role = Role.Builder.create(this, "MyRole")
.assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
.build();
BucketGrants.fromBucket(bucket).read(role);
```
```
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.IAM;
// Configure the resource with Mixins
var bucket = new CfnBucket(this, "MyBucket");
bucket.With(new BucketVersioning());
bucket.With(new BucketBlockPublicAccess());
// Grant permissions using a Facade
var role = new Role(this, "MyRole", new RoleProps
{
AssumedBy = new ServicePrincipal("lambda.amazonaws.com")
});
BucketGrants.FromBucket(bucket).Read(role);
```
```
bucket := awss3.NewCfnBucket(stack, jsii.String("MyBucket"), nil)
bucket.With(awss3.NewBucketVersioning())
bucket.With(awss3.NewBucketBlockPublicAccess())
role := awsiam.NewRole(stack, jsii.String("MyRole"), &awsiam.RoleProps{
AssumedBy: awsiam.NewServicePrincipal(jsii.String("lambda.amazonaws.com"), nil),
})
awss3.BucketGrants_FromBucket(bucket).Read(role, nil)
```
## Related resources
+ [Mixins](mixins.md) – Add reusable features to L1 and L2 constructs.
+ [Grants](permissions.md#permissions-grants) – Grant permissions between resources.
+ [Constructs](constructs.md) – Learn about L1, L2, and L3 constructs.
# Environments for the AWS CDK
An environment consists of the AWS account and AWS Region that you deploy an AWS Cloud Development Kit (AWS CDK) stack to.
** AWS account**
When you create an AWS account, you receive an account ID. This ID is a 12-digit number, such as **012345678901**, that uniquely identifies your account. To learn more, see [View AWS account identifiers](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html) in the * AWS Account Management Reference Guide*.
** AWS Region**
AWS Regions are named by using a combination of geographical location and a number that represents an Availability Zone in the Region. For example, ** us-east-1 ** represents an Availability Zone in the US East (N. Virginia) Region. To learn more about AWS Regions, see [Regions and Availability Zones](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/). For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) in the * AWS General Reference* Reference Guide.
The AWS CDK can determine environments from your credentials and configuration files. These files can be created and managed with the AWS Command Line Interface (AWS CLI). The following is a basic example of these files:
**Credentials file**
```
[default]
aws_access_key_id=ASIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
[user1]
aws_access_key_id=ASIAI44QH8DHBEXAMPLE
aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
aws_session_token = fcZib3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
```
**Configuration file**
```
[default]
region=us-west-2
output=json
[profile user1]
region=us-east-1
output=text
```
You can pass environment information from these files in your CDK code through environment variables that are provided by the CDK. When you run a CDK CLI command, such as `cdk deploy`, you then provide the profile from your credentials and configuration files to gather environment information from.
The following is an example of specifying these environment variables in your CDK code:
```
new MyDevStack(app, 'dev', {
env: {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION
}});
```
The following is an example of passing values associated with the `user1` profile from your credentials and configuration files to the CDK CLI using the `--profile` option. Values from these files will be passed to your environment variables:
```
$ cdk deploy --profile
```
Instead of using values from the credentials and configuration files, you can also hard-code environment values in your CDK code. The following is an example:
```
const envEU = { account: '238383838383', region: 'eu-west-1' };
const envUSA = { account: '837873873873', region: 'us-west-2' };
new MyFirstStack(app, 'first-stack-us', { env: envUSA });
new MyFirstStack(app, 'first-stack-eu', { env: envEU });
```
## Learn more
To get started with using environments with the AWS CDK, see [Configure environments to use with the AWS CDK](configure-env.md).
# AWS CDK bootstrapping
*Bootstrapping* is the process of preparing your AWS environment for usage with the AWS Cloud Development Kit (AWS CDK). Before you deploy a CDK stack into an AWS environment, the environment must first be bootstrapped.
## What is bootstrapping?
Bootstrapping prepares your AWS environment by provisioning specific AWS resources in your environment that are used by the AWS CDK. These resources are commonly referred to as your *bootstrap resources*. They include the following:
+ **Amazon Simple Storage Service (Amazon S3) bucket** – Used to store your CDK project files, such as AWS Lambda function code and assets.
+ **Amazon Elastic Container Registry (Amazon ECR) repository** – Used primarily to store Docker images.
+ ** AWS Identity and Access Management (IAM) roles** – Configured to grant permissions needed by the AWS CDK to perform deployments. For more information about the IAM roles created during bootstrapping, see [IAM roles created during bootstrapping](bootstrapping-env.md#bootstrapping-env-roles).
## How does bootstrapping work?
Resources and their configuration that are used by the CDK are defined in an AWS CloudFormation template. This template is created and managed by the CDK team. For the latest version of this template, see [https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml) in the *aws-cdk-cli GitHub repository*.
To bootstrap an environment, you use the AWS CDK Command Line Interface (AWS CDK CLI) `cdk bootstrap` command. The CDK CLI retrieves the template and deploys it to AWS CloudFormation as a stack, known as the *bootstrap stack*. By default, the stack name is `CDKToolkit`. By deploying this template, CloudFormation provisions the resources in your environment. After deployment, the bootstrap stack will appear in the AWS CloudFormation console of your environment.
You can also customize bootstrapping by modifying the template or by using CDK CLI options with the `cdk bootstrap` command.
AWS environments are independent. Each environment that you want to use with the AWS CDK must first be bootstrapped.
## Learn more
For instructions on bootstrapping your environment, see [Bootstrap your environment for use with the AWS CDK](bootstrapping-env.md).
# Resources and the AWS CDK
*Resources* are what you configure to use AWS services in your applications. Resources are a feature of AWS CloudFormation. By configuring resources and their properties in a AWS CloudFormation template, you can deploy to AWS CloudFormation to provision your resources. With the AWS Cloud Development Kit (AWS CDK), you can configure resources through constructs. You then deploy your CDK app, which involves synthesizing a AWS CloudFormation template and deploying to AWS CloudFormation to provision your resources.
## Configuring resources using constructs
As described in [AWS CDK Constructs](constructs.md), the AWS CDK provides a rich class library of constructs, called *constructs*, that represent all AWS resources.
To create an instance of a resource using its corresponding construct, pass in the scope as the first argument, the logical ID of the construct, and a set of configuration properties (props). For example, here’s how to create an Amazon SQS queue with AWS KMS encryption using the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html) construct from the AWS Construct Library.
**Example**
```
import * as sqs from '@aws-cdk/aws-sqs';
new sqs.Queue(this, 'MyQueue', {
encryption: sqs.QueueEncryption.KMS_MANAGED
});
```
```
const sqs = require('@aws-cdk/aws-sqs');
new sqs.Queue(this, 'MyQueue', {
encryption: sqs.QueueEncryption.KMS_MANAGED
});
```
```
import aws_cdk.aws_sqs as sqs
sqs.Queue(self, "MyQueue", encryption=sqs.QueueEncryption.KMS_MANAGED)
```
```
import software.amazon.awscdk.services.sqs.*;
Queue.Builder.create(this, "MyQueue").encryption(
QueueEncryption.KMS_MANAGED).build();
```
```
using Amazon.CDK.AWS.SQS;
new Queue(this, "MyQueue", new QueueProps
{
Encryption = QueueEncryption.KMS_MANAGED
});
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/jsii-runtime-go"
sqs "github.com/aws/aws-cdk-go/awscdk/v2/awssqs"
)
sqs.NewQueue(stack, jsii.String("MyQueue"), &sqs.QueueProps{
Encryption: sqs.QueueEncryption_KMS_MANAGED,
})
```
Some configuration props are optional, and in many cases have default values. In some cases, all props are optional, and the last argument can be omitted entirely.
### Resource attributes
Most resources in the AWS Construct Library expose attributes, which are resolved at deployment time by AWS CloudFormation. Attributes are exposed in the form of properties on the resource classes with the type name as a prefix. The following example shows how to get the URL of an Amazon SQS queue using the `queueUrl` (Python: `queue_url`) property.
**Example**
```
import * as sqs from '@aws-cdk/aws-sqs';
const queue = new sqs.Queue(this, 'MyQueue');
const url = queue.queueUrl; // => A string representing a deploy-time value
```
```
const sqs = require('@aws-cdk/aws-sqs');
const queue = new sqs.Queue(this, 'MyQueue');
const url = queue.queueUrl; // => A string representing a deploy-time value
```
```
import aws_cdk.aws_sqs as sqs
queue = sqs.Queue(self, "MyQueue")
url = queue.queue_url # => A string representing a deploy-time value
```
```
Queue queue = new Queue(this, "MyQueue");
String url = queue.getQueueUrl(); // => A string representing a deploy-time value
```
```
var queue = new Queue(this, "MyQueue");
var url = queue.QueueUrl; // => A string representing a deploy-time value
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/jsii-runtime-go"
sqs "github.com/aws/aws-cdk-go/awscdk/v2/awssqs"
)
queue := sqs.NewQueue(stack, jsii.String("MyQueue"), &sqs.QueueProps{})
url := queue.QueueUrl() // => A string representing a deploy-time value
```
See [Tokens and the AWS CDK](tokens.md) for information about how the AWS CDK encodes deploy-time attributes as strings.
## Referencing resources
When configuring resources, you will often have to reference properties of another resource. The following are examples:
+ An Amazon Elastic Container Service (Amazon ECS) resource requires a reference to the cluster on which it runs.
+ An Amazon CloudFront distribution requires a reference to the Amazon Simple Storage Service (Amazon S3) bucket containing the source code.
You can reference resources in any of the following ways:
+ By passing a resource defined in your CDK app, either in the same stack or in a different one
+ By passing a proxy object referencing a resource defined in your AWS account, created from a unique identifier of the resource (such as an ARN)
If the property of a construct represents a construct for another resource, its type is that of the interface type of the construct. For example, the Amazon ECS construct takes a property `cluster` of type `ecs.ICluster`. Another example, is the CloudFront distribution construct that takes a property `sourceBucket` (Python: `source_bucket`) of type `s3.IBucket`.
You can directly pass any resource object of the proper type defined in the same AWS CDK app. The following example defines an Amazon ECS cluster and then uses it to define an Amazon ECS service.
**Example**
```
const cluster = new ecs.Cluster(this, 'Cluster', { /*...*/ });
const service = new ecs.Ec2Service(this, 'Service', { cluster: cluster });
```
```
const cluster = new ecs.Cluster(this, 'Cluster', { /*...*/ });
const service = new ecs.Ec2Service(this, 'Service', { cluster: cluster });
```
```
cluster = ecs.Cluster(self, "Cluster")
service = ecs.Ec2Service(self, "Service", cluster=cluster)
```
```
Cluster cluster = new Cluster(this, "Cluster");
Ec2Service service = new Ec2Service(this, "Service",
new Ec2ServiceProps.Builder().cluster(cluster).build());
```
```
var cluster = new Cluster(this, "Cluster");
var service = new Ec2Service(this, "Service", new Ec2ServiceProps { Cluster = cluster });
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/jsii-runtime-go"
ecs "github.com/aws/aws-cdk-go/awscdk/v2/awsecs"
)
cluster := ecs.NewCluster(stack, jsii.String("MyCluster"), &ecs.ClusterProps{})
service := ecs.NewEc2Service(stack, jsii.String("MyService"), &ecs.Ec2ServiceProps{
Cluster: cluster,
})
```
### Referencing resources in a different stack
You can refer to resources in a different stack as long as they are defined in the same app and are in the same AWS environment. The following pattern is generally used:
+ Store a reference to the construct as an attribute of the stack that produces the resource. (To get a reference to the current construct’s stack, use `Stack.of(this)`.)
+ Pass this reference to the constructor of the stack that consumes the resource as a parameter or a property. The consuming stack then passes it as a property to any construct that needs it.
The following example defines a stack `stack1`. This stack defines an Amazon S3 bucket and stores a reference to the bucket construct as an attribute of the stack. Then the app defines a second stack, `stack2`, which accepts a bucket at instantiation. `stack2` might, for example, define an AWS Glue Table that uses the bucket for data storage.
**Example**
```
const prod = { account: '123456789012', region: 'us-east-1' };
const stack1 = new StackThatProvidesABucket(app, 'Stack1', { env: prod });
// stack2 will take a property { bucket: IBucket }
const stack2 = new StackThatExpectsABucket(app, 'Stack2', {
bucket: stack1.bucket,
env: prod
});
```
```
const prod = { account: '123456789012', region: 'us-east-1' };
const stack1 = new StackThatProvidesABucket(app, 'Stack1', { env: prod });
// stack2 will take a property { bucket: IBucket }
const stack2 = new StackThatExpectsABucket(app, 'Stack2', {
bucket: stack1.bucket,
env: prod
});
```
```
prod = core.Environment(account="123456789012", region="us-east-1")
stack1 = StackThatProvidesABucket(app, "Stack1", env=prod)
# stack2 will take a property "bucket"
stack2 = StackThatExpectsABucket(app, "Stack2", bucket=stack1.bucket, env=prod)
```
```
// Helper method to build an environment
static Environment makeEnv(String account, String region) {
return Environment.builder().account(account).region(region)
.build();
}
App app = new App();
Environment prod = makeEnv("123456789012", "us-east-1");
StackThatProvidesABucket stack1 = new StackThatProvidesABucket(app, "Stack1",
StackProps.builder().env(prod).build());
// stack2 will take an argument "bucket"
StackThatExpectsABucket stack2 = new StackThatExpectsABucket(app, "Stack,",
StackProps.builder().env(prod).build(), stack1.bucket);
```
```
Amazon.CDK.Environment makeEnv(string account, string region)
{
return new Amazon.CDK.Environment { Account = account, Region = region };
}
var prod = makeEnv(account: "123456789012", region: "us-east-1");
var stack1 = new StackThatProvidesABucket(app, "Stack1", new StackProps { Env = prod });
// stack2 will take a property "bucket"
var stack2 = new StackThatExpectsABucket(app, "Stack2", new StackProps { Env = prod,
bucket = stack1.Bucket});
```
If the AWS CDK determines that the resource is in the same environment, but in a different stack, it automatically synthesizes AWS CloudFormation [exports](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html) in the producing stack and an [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html) in the consuming stack to transfer that information from one stack to the other.
#### Resolving dependency deadlocks
Referencing a resource from one stack in a different stack creates a dependency between the two stacks. This makes sure that they’re deployed in the right order. After the stacks are deployed, this dependency is concrete. After that, removing the use of the shared resource from the consuming stack can cause an unexpected deployment failure. This happens if there is another dependency between the two stacks that force them to be deployed in the same order. It can also happen without a dependency if the producing stack is simply chosen by the CDK Toolkit to be deployed first. The AWS CloudFormation export is removed from the producing stack because it’s no longer needed, but the exported resource is still being used in the consuming stack because its update is not yet deployed. Therefore, deploying the producer stack fails.
To break this deadlock, remove the use of the shared resource from the consuming stack. (This removes the automatic export from the producing stack.) Next, manually add the same export to the producing stack using exactly the same logical ID as the automatically generated export. Remove the use of the shared resource in the consuming stack and deploy both stacks. Then, remove the manual export (and the shared resource if it’s no longer needed) and deploy both stacks again. The stack’s [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#exportwbrvalueexportedvalue-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#exportwbrvalueexportedvalue-options) method is a convenient way to create the manual export for this purpose. (See the example in the linked method reference.)
### Referencing resources in your AWS account
Suppose you want to use a resource already available in your AWS account in your AWS CDK app. This might be a resource that was defined through the console, an AWS SDK, directly with AWS CloudFormation, or in a different AWS CDK application. You can turn the resource’s ARN (or another identifying attribute, or group of attributes) into a proxy object. The proxy object serves as a reference to the resource by calling a static factory method on the resource’s class.
When you create such a proxy, the external resource **does not** become a part of your AWS CDK app. Therefore, changes you make to the proxy in your AWS CDK app do not affect the deployed resource. The proxy can, however, be passed to any AWS CDK method that requires a resource of that type.
The following example shows how to reference a bucket based on an existing bucket with the ARN `arn:aws:s3:::amzn-s3-demo-bucket1`, and an Amazon Virtual Private Cloud based on an existing VPC having a specific ID.
**Example**
```
// Construct a proxy for a bucket by its name (must be same account)
s3.Bucket.fromBucketName(this, 'MyBucket', 'amzn-s3-demo-bucket1');
// Construct a proxy for a bucket by its full ARN (can be another account)
s3.Bucket.fromBucketArn(this, 'MyBucket', 'arn:aws:s3:::amzn-s3-demo-bucket1');
// Construct a proxy for an existing VPC from its attribute(s)
ec2.Vpc.fromVpcAttributes(this, 'MyVpc', {
vpcId: 'vpc-1234567890abcde',
});
```
```
// Construct a proxy for a bucket by its name (must be same account)
s3.Bucket.fromBucketName(this, 'MyBucket', 'amzn-s3-demo-bucket1');
// Construct a proxy for a bucket by its full ARN (can be another account)
s3.Bucket.fromBucketArn(this, 'MyBucket', 'arn:aws:s3:::amzn-s3-demo-bucket1');
// Construct a proxy for an existing VPC from its attribute(s)
ec2.Vpc.fromVpcAttributes(this, 'MyVpc', {
vpcId: 'vpc-1234567890abcde'
});
```
```
# Construct a proxy for a bucket by its name (must be same account)
s3.Bucket.from_bucket_name(self, "MyBucket", "amzn-s3-demo-bucket1")
# Construct a proxy for a bucket by its full ARN (can be another account)
s3.Bucket.from_bucket_arn(self, "MyBucket", "arn:aws:s3:::amzn-s3-demo-bucket1")
# Construct a proxy for an existing VPC from its attribute(s)
ec2.Vpc.from_vpc_attributes(self, "MyVpc", vpc_id="vpc-1234567890abcdef")
```
```
// Construct a proxy for a bucket by its name (must be same account)
Bucket.fromBucketName(this, "MyBucket", "amzn-s3-demo-bucket1");
// Construct a proxy for a bucket by its full ARN (can be another account)
Bucket.fromBucketArn(this, "MyBucket",
"arn:aws:s3:::amzn-s3-demo-bucket1");
// Construct a proxy for an existing VPC from its attribute(s)
Vpc.fromVpcAttributes(this, "MyVpc", VpcAttributes.builder()
.vpcId("vpc-1234567890abcdef").build());
```
```
// Construct a proxy for a bucket by its name (must be same account)
Bucket.FromBucketName(this, "MyBucket", "amzn-s3-demo-bucket1");
// Construct a proxy for a bucket by its full ARN (can be another account)
Bucket.FromBucketArn(this, "MyBucket", "arn:aws:s3:::amzn-s3-demo-bucket1");
// Construct a proxy for an existing VPC from its attribute(s)
Vpc.FromVpcAttributes(this, "MyVpc", new VpcAttributes
{
VpcId = "vpc-1234567890abcdef"
});
```
```
// Define a proxy for a bucket by its name (must be same account)
s3.Bucket_FromBucketName(stack, jsii.String("MyBucket"), jsii.String("amzn-s3-demo-bucket1"))
// Define a proxy for a bucket by its full ARN (can be another account)
s3.Bucket_FromBucketArn(stack, jsii.String("MyBucket"), jsii.String("arn:aws:s3:::amzn-s3-demo-bucket1"))
// Define a proxy for an existing VPC from its attributes
ec2.Vpc_FromVpcAttributes(stack, jsii.String("MyVpc"), &ec2.VpcAttributes{
VpcId: jsii.String("vpc-1234567890abcde"),
})
```
Let’s take a closer look at the [https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-ec2.Vpc.html#static-fromwbrlookupscope-id-options](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-ec2.Vpc.html#static-fromwbrlookupscope-id-options) method. Because the `ec2.Vpc` construct is complex, there are many ways you might want to select the VPC to be used with your CDK app. To address this, the VPC construct has a `fromLookup` static method (Python: `from_lookup`) that lets you look up the desired Amazon VPC by querying your AWS account at synthesis time.
To use `Vpc.fromLookup()`, the system that synthesizes the stack must have access to the account that owns the Amazon VPC. This is because the CDK Toolkit queries the account to find the right Amazon VPC at synthesis time.
Furthermore, `Vpc.fromLookup()` works only in stacks that are defined with an explicit **account** and **region** (see [Environments for the AWS CDK](environments.md)). If the AWS CDK tries to look up an Amazon VPC from an [environment-agnostic stack](stacks.md#stack-api), the CDK Toolkit doesn’t know which environment to query to find the VPC.
You must provide `Vpc.fromLookup()` attributes sufficient to uniquely identify a VPC in your AWS account. For example, there can only ever be one default VPC, so it’s sufficient to specify the VPC as the default.
**Example**
```
ec2.Vpc.fromLookup(this, 'DefaultVpc', {
isDefault: true
});
```
```
ec2.Vpc.fromLookup(this, 'DefaultVpc', {
isDefault: true
});
```
```
ec2.Vpc.from_lookup(self, "DefaultVpc", is_default=True)
```
```
Vpc.fromLookup(this, "DefaultVpc", VpcLookupOptions.builder()
.isDefault(true).build());
```
```
Vpc.FromLookup(this, id = "DefaultVpc", new VpcLookupOptions { IsDefault = true });
```
```
ec2.Vpc_FromLookup(this, jsii.String("DefaultVpc"), &ec2.VpcLookupOptions{
IsDefault: jsii.Bool(true),
})
```
You can also use the `tags` property to query for VPCs by tag. You can add tags to the Amazon VPC at the time of its creation by using AWS CloudFormation or the AWS CDK. You can edit tags at any time after creation by using the AWS Management Console, the AWS CLI, or an AWS SDK. In addition to any tags you add yourself, the AWS CDK automatically adds the following tags to all VPCs it creates.
+ **Name** – The name of the VPC.
+ **aws-cdk:subnet-name** – The name of the subnet.
+ **aws-cdk:subnet-type** – The type of the subnet: Public, Private, or Isolated.
**Example**
```
ec2.Vpc.fromLookup(this, 'PublicVpc',
{tags: {'aws-cdk:subnet-type': "Public"}});
```
```
ec2.Vpc.fromLookup(this, 'PublicVpc',
{tags: {'aws-cdk:subnet-type': "Public"}});
```
```
ec2.Vpc.from_lookup(self, "PublicVpc",
tags={"aws-cdk:subnet-type": "Public"})
```
```
Vpc.fromLookup(this, "PublicVpc", VpcLookupOptions.builder()
.tags(java.util.Map.of("aws-cdk:subnet-type", "Public")) // Java 9 or later
.build());
```
```
Vpc.FromLookup(this, id: "PublicVpc", new VpcLookupOptions
{
Tags = new Dictionary { ["aws-cdk:subnet-type"] = "Public" }
});
```
```
ec2.Vpc_FromLookup(this, jsii.String("DefaultVpc"), &ec2.VpcLookupOptions{
Tags: &map[string]*string{"aws-cdk:subnet-type": jsii.String("Public")},
})
```
Results of `Vpc.fromLookup()` are cached in the project’s `cdk.context.json` file. (See [Context values and the AWS CDK](context.md).) Commit this file to version control so that your app will continue to refer to the same Amazon VPC. This works even if you later change the attributes of your VPCs in a way that would result in a different VPC being selected. This is particularly important if you’re deploying the stack in an environment that doesn’t have access to the AWS account that defines the VPC, such as [CDK Pipelines](cdk-pipeline.md).
Although you can use an external resource anywhere you’d use a similar resource defined in your AWS CDK app, you cannot modify it. For example, calling `addToResourcePolicy` (Python: `add_to_resource_policy`) on an external `s3.Bucket` does nothing.
## Resource physical names
The logical names of resources in AWS CloudFormation are different from the names of resources that are shown in the AWS Management Console after they’re deployed by AWS CloudFormation. The AWS CDK calls these final names *physical names*.
For example, AWS CloudFormation might create the Amazon S3 bucket with the logical ID `Stack2MyBucket4DD88B4F` and the physical name `stack2MyBucket4dd88b4f-iuv1rbv9z3to`.
You can specify a physical name when creating constructs that represent resources by using the property `Name`. The following example creates an Amazon S3 bucket with the physical name `amzn-s3-demo-bucket`.
**Example**
```
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: 'amzn-s3-demo-bucket',
});
```
```
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: 'amzn-s3-demo-bucket'
});
```
```
bucket = s3.Bucket(self, "MyBucket", bucket_name="amzn-s3-demo-bucket")
```
```
Bucket bucket = Bucket.Builder.create(this, "MyBucket")
.bucketName("amzn-s3-demo-bucket").build();
```
```
var bucket = new Bucket(this, "MyBucket", new BucketProps { BucketName = "amzn-s3-demo-bucket" });
```
```
bucket := s3.NewBucket(this, jsii.String("MyBucket"), &s3.BucketProps{
BucketName: jsii.String("amzn-s3-demo-bucket"),
})
```
Assigning physical names to resources has some disadvantages in AWS CloudFormation. Most importantly, any changes to deployed resources that require a resource replacement, such as changes to a resource’s properties that are immutable after creation, will fail if a resource has a physical name assigned. If you end up in that state, the only solution is to delete the AWS CloudFormation stack, then deploy the AWS CDK app again. See the [AWS CloudFormation documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html) for details.
In some cases, such as when creating an AWS CDK app with cross-environment references, physical names are required for the AWS CDK to function correctly. In those cases, if you don’t want to bother with coming up with a physical name yourself, you can let the AWS CDK name it for you. To do so, use the special value `PhysicalName.GENERATE_IF_NEEDED`, as follows.
**Example**
```
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: core.PhysicalName.GENERATE_IF_NEEDED,
});
```
```
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: core.PhysicalName.GENERATE_IF_NEEDED
});
```
```
bucket = s3.Bucket(self, "MyBucket",
bucket_name=core.PhysicalName.GENERATE_IF_NEEDED)
```
```
Bucket bucket = Bucket.Builder.create(this, "MyBucket")
.bucketName(PhysicalName.GENERATE_IF_NEEDED).build();
```
```
var bucket = new Bucket(this, "MyBucket", new BucketProps
{ BucketName = PhysicalName.GENERATE_IF_NEEDED });
```
```
bucket := s3.NewBucket(this, jsii.String("MyBucket"), &s3.BucketProps{
BucketName: awscdk.PhysicalName_GENERATE_IF_NEEDED(),
})
```
## Passing unique resource identifiers
Whenever possible, you should pass resources by reference, as described in the previous section. However, there are cases where you have no other choice but to refer to a resource by one of its attributes. Example use cases include the following:
+ When you are using low-level AWS CloudFormation resources.
+ When you need to expose resources to the runtime components of an AWS CDK application, such as when referring to Lambda functions through environment variables.
These identifiers are available as attributes on the resources, such as the following.
**Example**
```
bucket.bucketName
lambdaFunc.functionArn
securityGroup.groupArn
```
```
bucket.bucketName
lambdaFunc.functionArn
securityGroup.groupArn
```
```
bucket.bucket_name
lambda_func.function_arn
security_group_arn
```
The Java AWS CDK binding uses getter methods for attributes.
```
bucket.getBucketName()
lambdaFunc.getFunctionArn()
securityGroup.getGroupArn()
```
```
bucket.BucketName
lambdaFunc.FunctionArn
securityGroup.GroupArn
```
```
bucket.BucketName()
fn.FunctionArn()
```
The following example shows how to pass a generated bucket name to an AWS Lambda function.
**Example**
```
const bucket = new s3.Bucket(this, 'Bucket');
new lambda.Function(this, 'MyLambda', {
// ...
environment: {
BUCKET_NAME: bucket.bucketName,
},
});
```
```
const bucket = new s3.Bucket(this, 'Bucket');
new lambda.Function(this, 'MyLambda', {
// ...
environment: {
BUCKET_NAME: bucket.bucketName
}
});
```
```
bucket = s3.Bucket(self, "Bucket")
lambda.Function(self, "MyLambda", environment=dict(BUCKET_NAME=bucket.bucket_name))
```
```
final Bucket bucket = new Bucket(this, "Bucket");
Function.Builder.create(this, "MyLambda")
.environment(java.util.Map.of( // Java 9 or later
"BUCKET_NAME", bucket.getBucketName()))
.build();
```
```
var bucket = new Bucket(this, "Bucket");
new Function(this, "MyLambda", new FunctionProps
{
Environment = new Dictionary
{
["BUCKET_NAME"] = bucket.BucketName
}
});
```
```
bucket := s3.NewBucket(this, jsii.String("Bucket"), &s3.BucketProps{})
lambda.NewFunction(this, jsii.String("MyLambda"), &lambda.FunctionProps{
Environment: &map[string]*string{"BUCKET_NAME": bucket.BucketName()},
})
```
## Granting permissions between resources
Higher-level constructs make least-privilege permissions achievable by offering simple, intent-based APIs to express permission requirements. For example, many constructs offer grant methods that you can use to grant an entity (such as an IAM role or user) permission to work with the resource, without having to manually create IAM permission statements.
Grant methods are available through Grants classes (such as `BucketGrants` for Amazon S3 buckets). These classes work with both L1 and L2 constructs. L2 constructs expose a `grants` property for convenience, but you can also create a Grants class directly from an L1 construct. You can combine Grants classes with [Mixins](mixins.md) to get L2-like convenience on L1 constructs.
The following example creates the permissions to allow a Lambda function’s execution role to read and write objects to a particular Amazon S3 bucket. If the Amazon S3 bucket is encrypted with an AWS KMS key, this method also grants permissions to the Lambda function’s execution role to decrypt with the key.
**Example**
```
if (bucket.grants.readWrite(func).success) {
// ...
}
```
```
if ( bucket.grants.readWrite(func).success) {
// ...
}
```
```
if bucket.grants.read_write(func).success:
# ...
```
```
if (bucket.getGrants().readWrite(func).getSuccess()) {
// ...
}
```
```
if (bucket.Grants.ReadWrite(func).Success)
{
// ...
}
```
```
if *bucket.Grants().ReadWrite(function, nil).Success() {
// ...
}
```
The grant methods return an `iam.Grant` object. Use the `success` attribute of the `Grant` object to determine whether the grant was effectively applied (for example, it may not have been applied on [external resources](#resources-referencing)). You can also use the `assertSuccess` (Python: `assert_success`) method of the `Grant` object to enforce that the grant was successfully applied.
If a specific grant method isn’t available for the particular use case, you can use a generic grant method to define a new grant with a specified list of actions.
The following example shows how to grant a Lambda function access to the Amazon DynamoDB `CreateBackup` action.
**Example**
```
table.grants.actions(func, 'dynamodb:CreateBackup');
```
```
table.grants.actions(func, 'dynamodb:CreateBackup');
```
```
table.grants.actions(func, "dynamodb:CreateBackup")
```
```
table.getGrants().actions(func, "dynamodb:CreateBackup");
```
```
table.Grants.Actions(func, "dynamodb:CreateBackup");
```
```
table := dynamodb.NewTable(this, jsii.String("MyTable"), &dynamodb.TableProps{})
table.Grants().Actions(function, jsii.String("dynamodb:CreateBackup"))
```
Many resources, such as Lambda functions, require a role to be assumed when executing code. A configuration property enables you to specify an `iam.IRole`. If no role is specified, the function automatically creates a role specifically for this use. You can then use grant methods on the resources to add statements to the role.
The grant methods are built using lower-level APIs for handling with IAM policies. Policies are modeled as [PolicyDocument](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyDocument.html) objects. Add statements directly to roles (or a construct’s attached role) using the `addToRolePolicy` method (Python: `add_to_role_policy`), or to a resource’s policy (such as a `Bucket` policy) using the `addToResourcePolicy` (Python: `add_to_resource_policy`) method.
## Resource metrics and alarms
Many resources emit CloudWatch metrics that can be used to set up monitoring dashboards and alarms. Higher-level constructs have metric methods that let you access the metrics without looking up the correct name to use.
The following example shows how to define an alarm when the `ApproximateNumberOfMessagesNotVisible` of an Amazon SQS queue exceeds 100.
**Example**
```
import * as cw from '@aws-cdk/aws-cloudwatch';
import * as sqs from '@aws-cdk/aws-sqs';
import { Duration } from '@aws-cdk/core';
const queue = new sqs.Queue(this, 'MyQueue');
const metric = queue.metricApproximateNumberOfMessagesNotVisible({
label: 'Messages Visible (Approx)',
period: Duration.minutes(5),
// ...
});
metric.createAlarm(this, 'TooManyMessagesAlarm', {
comparisonOperator: cw.ComparisonOperator.GREATER_THAN_THRESHOLD,
threshold: 100,
// ...
});
```
```
const cw = require('@aws-cdk/aws-cloudwatch');
const sqs = require('@aws-cdk/aws-sqs');
const { Duration } = require('@aws-cdk/core');
const queue = new sqs.Queue(this, 'MyQueue');
const metric = queue.metricApproximateNumberOfMessagesNotVisible({
label: 'Messages Visible (Approx)',
period: Duration.minutes(5)
// ...
});
metric.createAlarm(this, 'TooManyMessagesAlarm', {
comparisonOperator: cw.ComparisonOperator.GREATER_THAN_THRESHOLD,
threshold: 100
// ...
});
```
```
import aws_cdk.aws_cloudwatch as cw
import aws_cdk.aws_sqs as sqs
from aws_cdk.core import Duration
queue = sqs.Queue(self, "MyQueue")
metric = queue.metric_approximate_number_of_messages_not_visible(
label="Messages Visible (Approx)",
period=Duration.minutes(5),
# ...
)
metric.create_alarm(self, "TooManyMessagesAlarm",
comparison_operator=cw.ComparisonOperator.GREATER_THAN_THRESHOLD,
threshold=100,
# ...
)
```
```
import software.amazon.awscdk.core.Duration;
import software.amazon.awscdk.services.sqs.Queue;
import software.amazon.awscdk.services.cloudwatch.Metric;
import software.amazon.awscdk.services.cloudwatch.MetricOptions;
import software.amazon.awscdk.services.cloudwatch.CreateAlarmOptions;
import software.amazon.awscdk.services.cloudwatch.ComparisonOperator;
Queue queue = new Queue(this, "MyQueue");
Metric metric = queue
.metricApproximateNumberOfMessagesNotVisible(MetricOptions.builder()
.label("Messages Visible (Approx)")
.period(Duration.minutes(5)).build());
metric.createAlarm(this, "TooManyMessagesAlarm", CreateAlarmOptions.builder()
.comparisonOperator(ComparisonOperator.GREATER_THAN_THRESHOLD)
.threshold(100)
// ...
.build());
```
```
using cdk = Amazon.CDK;
using cw = Amazon.CDK.AWS.CloudWatch;
using sqs = Amazon.CDK.AWS.SQS;
var queue = new sqs.Queue(this, "MyQueue");
var metric = queue.MetricApproximateNumberOfMessagesNotVisible(new cw.MetricOptions
{
Label = "Messages Visible (Approx)",
Period = cdk.Duration.Minutes(5),
// ...
});
metric.CreateAlarm(this, "TooManyMessagesAlarm", new cw.CreateAlarmOptions
{
ComparisonOperator = cw.ComparisonOperator.GREATER_THAN_THRESHOLD,
Threshold = 100,
// ..
});
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/jsii-runtime-go"
cw "github.com/aws/aws-cdk-go/awscdk/v2/awscloudwatch"
sqs "github.com/aws/aws-cdk-go/awscdk/v2/awssqs"
)
queue := sqs.NewQueue(this, jsii.String("MyQueue"), &sqs.QueueProps{})
metric := queue.MetricApproximateNumberOfMessagesNotVisible(&cw.MetricOptions{
Label: jsii.String("Messages Visible (Approx)"),
Period: awscdk.Duration_Minutes(jsii.Number(5)),
})
metric.CreateAlarm(this, jsii.String("TooManyMessagesAlarm"), &cw.CreateAlarmOptions{
ComparisonOperator: cw.ComparisonOperator_GREATER_THAN_THRESHOLD,
Threshold: jsii.Number(100),
})
```
If there is no method for a particular metric, you can use the general metric method to specify the metric name manually.
Metrics can also be added to CloudWatch dashboards. See [CloudWatch](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch-readme.html).
## Network traffic
In many cases, you must enable permissions on a network for an application to work, such as when the compute infrastructure needs to access the persistence layer. Resources that establish or listen for connections expose methods that enable traffic flows, including setting security group rules or network ACLs.
[IConnectable](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IConnectable.html) resources have a `connections` property that is the gateway to network traffic rules configuration.
You enable data to flow on a given network path by using `allow` methods. The following example enables HTTPS connections to the web and incoming connections from the Amazon EC2 Auto Scaling group `fleet2`.
**Example**
```
import * as asg from '@aws-cdk/aws-autoscaling';
import * as ec2 from '@aws-cdk/aws-ec2';
const fleet1: asg.AutoScalingGroup = asg.AutoScalingGroup(/*...*/);
// Allow surfing the (secure) web
fleet1.connections.allowTo(new ec2.Peer.anyIpv4(), new ec2.Port({ fromPort: 443, toPort: 443 }));
const fleet2: asg.AutoScalingGroup = asg.AutoScalingGroup(/*...*/);
fleet1.connections.allowFrom(fleet2, ec2.Port.AllTraffic());
```
```
const asg = require('@aws-cdk/aws-autoscaling');
const ec2 = require('@aws-cdk/aws-ec2');
const fleet1 = asg.AutoScalingGroup();
// Allow surfing the (secure) web
fleet1.connections.allowTo(new ec2.Peer.anyIpv4(), new ec2.Port({ fromPort: 443, toPort: 443 }));
const fleet2 = asg.AutoScalingGroup();
fleet1.connections.allowFrom(fleet2, ec2.Port.AllTraffic());
```
```
import aws_cdk.aws_autoscaling as asg
import aws_cdk.aws_ec2 as ec2
fleet1 = asg.AutoScalingGroup( ... )
# Allow surfing the (secure) web
fleet1.connections.allow_to(ec2.Peer.any_ipv4(),
ec2.Port(PortProps(from_port=443, to_port=443)))
fleet2 = asg.AutoScalingGroup( ... )
fleet1.connections.allow_from(fleet2, ec2.Port.all_traffic())
```
```
import software.amazon.awscdk.services.autoscaling.AutoScalingGroup;
import software.amazon.awscdk.services.ec2.Peer;
import software.amazon.awscdk.services.ec2.Port;
AutoScalingGroup fleet1 = AutoScalingGroup.Builder.create(this, "MyFleet")
/* ... */.build();
// Allow surfing the (secure) Web
fleet1.getConnections().allowTo(Peer.anyIpv4(),
Port.Builder.create().fromPort(443).toPort(443).build());
AutoScalingGroup fleet2 = AutoScalingGroup.Builder.create(this, "MyFleet2")
/* ... */.build();
fleet1.getConnections().allowFrom(fleet2, Port.allTraffic());
```
```
using cdk = Amazon.CDK;
using asg = Amazon.CDK.AWS.AutoScaling;
using ec2 = Amazon.CDK.AWS.EC2;
// Allow surfing the (secure) Web
var fleet1 = new asg.AutoScalingGroup(this, "MyFleet", new asg.AutoScalingGroupProps { /* ... */ });
fleet1.Connections.AllowTo(ec2.Peer.AnyIpv4(), new ec2.Port(new ec2.PortProps
{ FromPort = 443, ToPort = 443 }));
var fleet2 = new asg.AutoScalingGroup(this, "MyFleet2", new asg.AutoScalingGroupProps { /* ... */ });
fleet1.Connections.AllowFrom(fleet2, ec2.Port.AllTraffic());
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/jsii-runtime-go"
autoscaling "github.com/aws/aws-cdk-go/awscdk/v2/awsautoscaling"
ec2 "github.com/aws/aws-cdk-go/awscdk/v2/awsec2"
)
fleet1 := autoscaling.NewAutoScalingGroup(this, jsii.String("MyFleet1"), &autoscaling.AutoScalingGroupProps{})
fleet1.Connections().AllowTo(ec2.Peer_AnyIpv4(),ec2.NewPort(&ec2.PortProps{ FromPort: jsii.Number(443), ToPort: jsii.Number(443) }),jsii.String("secure web"))
fleet2 := autoscaling.NewAutoScalingGroup(this, jsii.String("MyFleet2"), &autoscaling.AutoScalingGroupProps{})
fleet1.Connections().AllowFrom(fleet2, ec2.Port_AllTraffic(),jsii.String("all traffic"))
```
Certain resources have default ports associated with them. Examples include the listener of a load balancer on the public port, and the ports on which the database engine accepts connections for instances of an Amazon RDS database. In such cases, you can enforce tight network control without having to manually specify the port. To do so, use the `allowDefaultPortFrom` and `allowToDefaultPort` methods (Python: `allow_default_port_from`, `allow_to_default_port`).
The following example shows how to enable connections from any IPV4 address, and a connection from an Auto Scaling group to access a database.
**Example**
```
listener.connections.allowDefaultPortFromAnyIpv4('Allow public access');
fleet.connections.allowToDefaultPort(rdsDatabase, 'Fleet can access database');
```
```
listener.connections.allowDefaultPortFromAnyIpv4('Allow public access');
fleet.connections.allowToDefaultPort(rdsDatabase, 'Fleet can access database');
```
```
listener.connections.allow_default_port_from_any_ipv4("Allow public access")
fleet.connections.allow_to_default_port(rds_database, "Fleet can access database")
```
```
listener.getConnections().allowDefaultPortFromAnyIpv4("Allow public access");
fleet.getConnections().AllowToDefaultPort(rdsDatabase, "Fleet can access database");
```
```
listener.Connections.AllowDefaultPortFromAnyIpv4("Allow public access");
fleet.Connections.AllowToDefaultPort(rdsDatabase, "Fleet can access database");
```
```
listener.Connections().AllowDefaultPortFromAnyIpv4(jsii.String("Allow public Access"))
fleet.Connections().AllowToDefaultPort(rdsDatabase, jsii.String("Fleet can access database"))
```
## Event handling
Some resources can act as event sources. Use the `addEventNotification` method (Python: `add_event_notification`) to register an event target to a particular event type emitted by the resource. In addition to this, `addXxxNotification` methods offer a simple way to register a handler for common event types.
The following example shows how to trigger a Lambda function when an object is added to an Amazon S3 bucket.
**Example**
```
import * as s3nots from '@aws-cdk/aws-s3-notifications';
const handler = new lambda.Function(this, 'Handler', { /*…*/ });
const bucket = new s3.Bucket(this, 'Bucket');
bucket.addObjectCreatedNotification(new s3nots.LambdaDestination(handler));
```
```
const s3nots = require('@aws-cdk/aws-s3-notifications');
const handler = new lambda.Function(this, 'Handler', { /*…*/ });
const bucket = new s3.Bucket(this, 'Bucket');
bucket.addObjectCreatedNotification(new s3nots.LambdaDestination(handler));
```
```
import aws_cdk.aws_s3_notifications as s3_nots
handler = lambda_.Function(self, "Handler", ...)
bucket = s3.Bucket(self, "Bucket")
bucket.add_object_created_notification(s3_nots.LambdaDestination(handler))
```
```
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Function;
import software.amazon.awscdk.services.s3.notifications.LambdaDestination;
Function handler = Function.Builder.create(this, "Handler")/* ... */.build();
Bucket bucket = new Bucket(this, "Bucket");
bucket.addObjectCreatedNotification(new LambdaDestination(handler));
```
```
using lambda = Amazon.CDK.AWS.Lambda;
using s3 = Amazon.CDK.AWS.S3;
using s3Nots = Amazon.CDK.AWS.S3.Notifications;
var handler = new lambda.Function(this, "Handler", new lambda.FunctionProps { .. });
var bucket = new s3.Bucket(this, "Bucket");
bucket.AddObjectCreatedNotification(new s3Nots.LambdaDestination(handler));
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/jsii-runtime-go"
s3 "github.com/aws/aws-cdk-go/awscdk/v2/awss3"
s3nots "github.com/aws/aws-cdk-go/awscdk/v2/awss3notifications"
)
handler := lambda.NewFunction(this, jsii.String("MyFunction"), &lambda.FunctionProps{})
bucket := s3.NewBucket(this, jsii.String("Bucket"), &s3.BucketProps{})
bucket.AddObjectCreatedNotification(s3nots.NewLambdaDestination(handler), nil)
```
## Removal policies
Resources that maintain persistent data, such as databases, Amazon S3 buckets, and Amazon ECR registries, have a *removal policy*. The removal policy indicates whether to delete persistent objects when the AWS CDK stack that contains them is destroyed. The values specifying the removal policy are available through the `RemovalPolicy` enumeration in the AWS CDK `core` module.
**Note**
Resources besides those that store data persistently might also have a `removalPolicy` that is used for a different purpose. For example, a Lambda function version uses a `removalPolicy` attribute to determine whether a given version is retained when a new version is deployed. These have different meanings and defaults compared to the removal policy on an Amazon S3 bucket or DynamoDB table.
| Value | Meaning |
| --- | --- |
| `RemovalPolicy.RETAIN` | Keep the contents of the resource when destroying the stack (default). The resource is orphaned from the stack and must be deleted manually. If you attempt to re-deploy the stack while the resource still exists, you will receive an error message due to a name conflict. |
| `RemovalPolicy.DESTROY` | The resource will be destroyed along with the stack. |
AWS CloudFormation does not remove Amazon S3 buckets that contain files even if their removal policy is set to `DESTROY`. Attempting to do so is an AWS CloudFormation error. To have the AWS CDK delete all files from the bucket before destroying it, set the bucket’s `autoDeleteObjects` property to `true`.
Following is an example of creating an Amazon S3 bucket with `RemovalPolicy` of `DESTROY` and `autoDeleteOjbects` set to `true`.
**Example**
```
import * as cdk from '@aws-cdk/core';
import * as s3 from '@aws-cdk/aws-s3';
export class CdkTestStack extends cdk.Stack {
constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const bucket = new s3.Bucket(this, 'Bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
autoDeleteObjects: true
});
}
}
```
```
const cdk = require('@aws-cdk/core');
const s3 = require('@aws-cdk/aws-s3');
class CdkTestStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
const bucket = new s3.Bucket(this, 'Bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
autoDeleteObjects: true
});
}
}
module.exports = { CdkTestStack }
```
```
import aws_cdk.core as cdk
import aws_cdk.aws_s3 as s3
class CdkTestStack(cdk.stack):
def __init__(self, scope: cdk.Construct, id: str, **kwargs):
super().__init__(scope, id, **kwargs)
bucket = s3.Bucket(self, "Bucket",
removal_policy=cdk.RemovalPolicy.DESTROY,
auto_delete_objects=True)
```
```
software.amazon.awscdk.core.*;
import software.amazon.awscdk.services.s3.*;
public class CdkTestStack extends Stack {
public CdkTestStack(final Construct scope, final String id) {
this(scope, id, null);
}
public CdkTestStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
Bucket.Builder.create(this, "Bucket")
.removalPolicy(RemovalPolicy.DESTROY)
.autoDeleteObjects(true).build();
}
}
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.S3;
public CdkTestStack(Construct scope, string id, IStackProps props) : base(scope, id, props)
{
new Bucket(this, "Bucket", new BucketProps {
RemovalPolicy = RemovalPolicy.DESTROY,
AutoDeleteObjects = true
});
}
```
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/jsii-runtime-go"
s3 "github.com/aws/aws-cdk-go/awscdk/v2/awss3"
)
s3.NewBucket(this, jsii.String("Bucket"), &s3.BucketProps{
RemovalPolicy: awscdk.RemovalPolicy_DESTROY,
AutoDeleteObjects: jsii.Bool(true),
})
```
You can also apply a removal policy directly to the underlying AWS CloudFormation resource via the `applyRemovalPolicy()` method. This method is available on some stateful resources that do not have a `removalPolicy` property in their L2 resource’s props. Examples include the following:
+ AWS CloudFormation stacks
+ Amazon Cognito user pools
+ Amazon DocumentDB database instances
+ Amazon EC2 volumes
+ Amazon OpenSearch Service domains
+ Amazon FSx file systems
+ Amazon SQS queues
**Example**
```
const resource = bucket.node.findChild('Resource') as cdk.CfnResource;
resource.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);
```
```
const resource = bucket.node.findChild('Resource');
resource.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);
```
```
resource = bucket.node.find_child('Resource')
resource.apply_removal_policy(cdk.RemovalPolicy.DESTROY);
```
```
CfnResource resource = (CfnResource)bucket.node.findChild("Resource");
resource.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);
```
```
var resource = (CfnResource)bucket.node.findChild('Resource');
resource.ApplyRemovalPolicy(cdk.RemovalPolicy.DESTROY);
```
**Note**
The AWS CDK’s `RemovalPolicy` translates to AWS CloudFormation’s `DeletionPolicy`. However, the default in AWS CDK is to retain the data, which is the opposite of the AWS CloudFormation default.
# Identifiers and the AWS CDK
When building AWS Cloud Development Kit (AWS CDK) apps, you will use many types of identifiers and names. To use the AWS CDK effectively and avoid errors, it is important to understand the types of identifiers.
Identifiers must be unique within the scope in which they are created; they do not need to be globally unique in your AWS CDK application.
If you attempt to create an identifier with the same value within the same scope, the AWS CDK throws an exception.
## Construct IDs
The most common identifier, `id`, is the identifier passed as the second argument when instantiating a construct object. This identifier, like all identifiers, only needs to be unique within the scope in which it is created, which is the first argument when instantiating a construct object.
**Note**
The `id` of a stack is also the identifier that you use to refer to it in the [AWS CDK CLI reference](cli.md).
Let’s look at an example where we have two constructs with the identifier `MyBucket` in our app. The first is defined in the scope of the stack with the identifier `Stack1`. The second is defined in the scope of a stack with the identifier `Stack2`. Because they’re defined in different scopes, this doesn’t cause any conflict, and they can coexist in the same app without issues.
**Example**
```
import { App, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
class MyStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps = {}) {
super(scope, id, props);
new s3.Bucket(this, 'MyBucket');
}
}
const app = new App();
new MyStack(app, 'Stack1');
new MyStack(app, 'Stack2');
```
```
const { App , Stack } = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
class MyStack extends Stack {
constructor(scope, id, props = {}) {
super(scope, id, props);
new s3.Bucket(this, 'MyBucket');
}
}
const app = new App();
new MyStack(app, 'Stack1');
new MyStack(app, 'Stack2');
```
```
from aws_cdk import App, Construct, Stack, StackProps
from constructs import Construct
from aws_cdk import aws_s3 as s3
class MyStack(Stack):
def __init__(self, scope: Construct, id: str, **kwargs):
super().__init__(scope, id, **kwargs)
s3.Bucket(self, "MyBucket")
app = App()
MyStack(app, 'Stack1')
MyStack(app, 'Stack2')
```
```
// MyStack.java
package com.myorg;
import software.amazon.awscdk.App;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.constructs.Construct;
import software.amazon.awscdk.services.s3.Bucket;
public class MyStack extends Stack {
public MyStack(final Construct scope, final String id) {
this(scope, id, null);
}
public MyStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
new Bucket(this, "MyBucket");
}
}
// Main.java
package com.myorg;
import software.amazon.awscdk.App;
public class Main {
public static void main(String[] args) {
App app = new App();
new MyStack(app, "Stack1");
new MyStack(app, "Stack2");
}
}
```
```
using Amazon.CDK;
using constructs;
using Amazon.CDK.AWS.S3;
public class MyStack : Stack
{
public MyStack(Construct scope, string id, IStackProps props) : base(scope, id, props)
{
new Bucket(this, "MyBucket");
}
}
class Program
{
static void Main(string[] args)
{
var app = new App();
new MyStack(app, "Stack1");
new MyStack(app, "Stack2");
}
}
```
## Paths
The constructs in an AWS CDK application form a hierarchy rooted in the `App` class. We refer to the collection of IDs from a given construct, its parent construct, its grandparent, and so on to the root of the construct tree, as a *path*.
The AWS CDK typically displays paths in your templates as a string. The IDs from the levels are separated by slashes, starting at the node immediately under the root `App` instance, which is usually a stack. For example, the paths of the two Amazon S3 bucket resources in the previous code example are `Stack1/MyBucket` and `Stack2/MyBucket`.
You can access the path of any construct programmatically, as shown in the following example. This gets the path of `myConstruct` (or `my_construct`, as Python developers would write it). Since IDs must be unique within the scope they are created, their paths are always unique within an AWS CDK application.
**Example**
```
const path: string = myConstruct.node.path;
```
```
const path = myConstruct.node.path;
```
```
path = my_construct.node.path
```
```
String path = myConstruct.getNode().getPath();
```
```
string path = myConstruct.Node.Path;
```
## Unique IDs
AWS CloudFormation requires that all logical IDs in a template be unique. Because of this, the AWS CDK must be able to generate a unique identifier for each construct in an application. Resources have paths that are globally unique (the names of all scopes from the stack to a specific resource). Therefore, the AWS CDK generates the necessary unique identifiers by concatenating the elements of the path and adding an 8-digit hash. (The hash is necessary to distinguish distinct paths, such as `A/B/C` and `A/BC`, that would result in the same AWS CloudFormation identifier. AWS CloudFormation identifiers are alphanumeric and cannot contain slashes or other separator characters.) The AWS CDK calls this string the *unique ID* of the construct.
In general, your AWS CDK app should not need to know about unique IDs. You can, however, access the unique ID of any construct programmatically, as shown in the following example.
**Example**
```
const uid: string = Names.uniqueId(myConstruct);
```
```
const uid = Names.uniqueId(myConstruct);
```
```
uid = Names.unique_id(my_construct)
```
```
String uid = Names.uniqueId(myConstruct);
```
```
string uid = Names.Uniqueid(myConstruct);
```
The *address* is another kind of unique identifier that uniquely distinguishes CDK resources. Derived from the SHA-1 hash of the path, it is not human-readable. However, its constant, relatively short length (always 42 hexadecimal characters) makes it useful in situations where the "traditional" unique ID might be too long. Some constructs may use the address in the synthesized AWS CloudFormation template instead of the unique ID. Again, your app generally should not need to know about its constructs' addresses, but you can retrieve a construct’s address as follows.
**Example**
```
const addr: string = myConstruct.node.addr;
```
```
const addr = myConstruct.node.addr;
```
```
addr = my_construct.node.addr
```
```
String addr = myConstruct.getNode().getAddr();
```
```
string addr = myConstruct.Node.Addr;
```
## Logical IDs
When the AWS CDK synthesizes your app into an AWS CloudFormation template, it generates a *logical ID* for each resource. AWS CloudFormation uses logical IDs to identify resources within a template and to track them across deployments. Understanding how logical IDs are generated helps you avoid unintended resource replacements when you refactor your CDK code.
### How logical IDs are generated
The AWS CDK generates logical IDs from the construct path by using the following algorithm:
1. Concatenate the path components from the construct tree, excluding the stack itself.
1. Apply heuristics to improve readability (see [Logical ID path component heuristics](#identifiers-logical-id-heuristics)).
1. Append an 8-character hash of the full path to ensure uniqueness.
The resulting format is:
```
<8-character-hash>
```
For example, a VPC private subnet route table might produce the logical ID `VPCPrivateSubnet2RouteTable0A19E10E`.
The following rules apply to logical ID generation:
+ The maximum length is 255 characters. The human-readable portion is capped at 240 characters.
+ The 8-character hash ensures that paths like `A/B/C` and `A/BC` — which concatenate to the same string — produce different logical IDs.
+ Resources that are direct children of the stack (single-component paths) use their name directly without a hash, as long as the name is 255 characters or fewer.
### Logical ID path component heuristics
The AWS CDK applies the following heuristics to path components when it generates the human-readable portion of logical IDs.
`Default` — removed entirely
If a path component is `Default`, the CDK removes it from both the human-readable portion and the hash input. This means that wrapping an existing construct inside a new construct — and naming the inner construct `Default` — produces the exact same logical ID as the original unwrapped construct. This is the key mechanism for safely refactoring flat code into higher-level constructs without changing deployed resource identities.
`Resource` — hidden from human-readable portion only
If a path component is `Resource`, the CDK omits it from the human-readable portion but still includes it in the hash calculation. L1 (CloudFormation) constructs use `Resource` as their construct ID by convention. This keeps logical IDs shorter without losing uniqueness.
Duplicate consecutive components — deduplicated
If the preceding path component name ends with the current component name, the CDK skips the current component. This prevents redundant repetition in logical IDs.
### Use `Default` to preserve logical IDs when you refactor
When you refactor a flat stack into higher-level constructs, you can use `Default` as the construct ID for the primary resource to preserve its logical ID. This prevents AWS CloudFormation from replacing the resource during deployment.
The following example shows a stack with resources that are defined directly:
**Example**
```
export class MyStack extends cdk.Stack {
constructor(scope: Construct, id: string) {
super(scope, id);
new s3.Bucket(this, 'DataBucket');
new lambda.Function(this, 'ProcessFunction', { /* ... */ });
}
}
```
```
class MyStack extends cdk.Stack {
constructor(scope, id) {
super(scope, id);
new s3.Bucket(this, 'DataBucket');
new lambda.Function(this, 'ProcessFunction', { /* ... */ });
}
}
```
```
from aws_cdk import (
Stack,
aws_s3 as s3,
aws_lambda as _lambda,
)
from constructs import Construct
class MyStack(Stack):
def __init__(self, scope: Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
s3.Bucket(self, "DataBucket")
_lambda.Function(self, "ProcessFunction", # ...
)
```
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Function;
public class MyStack extends Stack {
public MyStack(final Construct scope, final String id) {
this(scope, id, null);
}
public MyStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
new Bucket(this, "DataBucket");
Function.Builder.create(this, "ProcessFunction")
// ...
.build();
}
}
```
```
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;
namespace MyApp
{
public class MyStack : Stack
{
public MyStack(Construct scope, string id, StackProps props = null) : base(scope, id, props)
{
new Bucket(this, "DataBucket");
new Function(this, "ProcessFunction", new FunctionProps
{
// ...
});
}
}
}
```
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type MyStackProps struct {
awscdk.StackProps
}
func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack {
stack := awscdk.NewStack(scope, &id, &props.StackProps)
awss3.NewBucket(stack, jsii.String("DataBucket"), &awss3.BucketProps{})
awslambda.NewFunction(stack, jsii.String("ProcessFunction"), &awslambda.FunctionProps{
// ...
})
return stack
}
```
The bucket’s path is `MyStack/DataBucket/Resource`, which produces a logical ID of `DataBucket`.
You can extract the bucket into a higher-level construct and preserve the same logical ID by naming the inner construct `Default`:
**Example**
```
class DataPipeline extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
new s3.Bucket(this, 'Default'); // 'Default' is hidden from logical ID
new lambda.Function(this, 'ProcessFunction', { /* ... */ });
}
}
export class MyStack extends cdk.Stack {
constructor(scope: Construct, id: string) {
super(scope, id);
new DataPipeline(this, 'DataBucket');
}
}
```
```
class DataPipeline extends Construct {
constructor(scope, id) {
super(scope, id);
new s3.Bucket(this, 'Default'); // 'Default' is hidden from logical ID
new lambda.Function(this, 'ProcessFunction', { /* ... */ });
}
}
class MyStack extends cdk.Stack {
constructor(scope, id) {
super(scope, id);
new DataPipeline(this, 'DataBucket');
}
}
```
```
from aws_cdk import (
Stack,
aws_s3 as s3,
aws_lambda as _lambda,
)
from constructs import Construct
class DataPipeline(Construct):
def __init__(self, scope: Construct, id: str) -> None:
super().__init__(scope, id)
s3.Bucket(self, "Default") # 'Default' is hidden from logical ID
_lambda.Function(self, "ProcessFunction", # ...
)
class MyStack(Stack):
def __init__(self, scope: Construct, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
DataPipeline(self, "DataBucket")
```
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Function;
public class DataPipeline extends Construct {
public DataPipeline(final Construct scope, final String id) {
super(scope, id);
new Bucket(this, "Default"); // 'Default' is hidden from logical ID
Function.Builder.create(this, "ProcessFunction")
// ...
.build();
}
}
public class MyStack extends Stack {
public MyStack(final Construct scope, final String id) {
this(scope, id, null);
}
public MyStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
new DataPipeline(this, "DataBucket");
}
}
```
```
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;
namespace MyApp
{
public class DataPipeline : Construct
{
public DataPipeline(Construct scope, string id) : base(scope, id)
{
new Bucket(this, "Default"); // 'Default' is hidden from logical ID
new Function(this, "ProcessFunction", new FunctionProps
{
// ...
});
}
}
public class MyStack : Stack
{
public MyStack(Construct scope, string id, StackProps props = null) : base(scope, id, props)
{
new DataPipeline(this, "DataBucket");
}
}
}
```
```
package main
import (
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type DataPipeline struct {
constructs.Construct
}
func NewDataPipeline(scope constructs.Construct, id string) constructs.Construct {
this := constructs.NewConstruct(scope, &id)
// 'Default' is hidden from logical ID
awss3.NewBucket(this, jsii.String("Default"), &awss3.BucketProps{})
awslambda.NewFunction(this, jsii.String("ProcessFunction"), &awslambda.FunctionProps{
// ...
})
return this
}
type MyStackProps struct {
awscdk.StackProps
}
func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack {
stack := awscdk.NewStack(scope, &id, &props.StackProps)
NewDataPipeline(stack, "DataBucket")
return stack
}
```
The bucket’s path is now `MyStack/DataBucket/Default/Resource`. Because `Default` is removed from both the human-readable portion and the hash input, the logical ID remains `DataBucket` — identical to the original.
**Important**
You can have only one child with the ID `Default` per construct scope. If you need multiple resources at the same level, give them descriptive IDs. The `Default` pattern works best with single-responsibility constructs that have one primary resource.
### Limitations and considerations
Keep the following in mind when you work with logical IDs:
+ You can assign only one child per scope the `Default` construct ID.
+ If you change a construct ID after deployment, the logical ID changes, which causes AWS CloudFormation to replace the resource. Use `cdk diff` to verify changes before you deploy.
+ For cases where logical IDs have already changed, you can use the `cdk refactor` command to map old logical IDs to new ones. For more information, see [Preserve deployed resources when refactoring CDK code](refactor.md).
+ For more information about how logical IDs appear in synthesized templates, see [Generated logical IDs in your AWS CloudFormation template](configure-synth.md#how-synth-default-logical-ids).
### Logical ID stability
Avoid changing the logical ID of a resource after it has been created. AWS CloudFormation identifies resources by their logical ID. Therefore, if you change the logical ID of a resource, AWS CloudFormation creates a new resource with the new logical ID, then deletes the existing one. Depending on the type of resource, this might cause service interruption, data loss, or both.
# Tokens and the AWS CDK
In the AWS Cloud Development Kit (AWS CDK), *tokens* are placeholders for values that aren’t known when defining constructs or synthesizing stacks. These values will be fully resolved at deployment, when your actual infrastructure is created. When developing AWS CDK applications, you will work with tokens to manage these values across your application.
## Token example
The following is an example of a CDK stack that defines a construct for an Amazon Simple Storage Service (Amazon S3) bucket. Since the name of our bucket is not yet known, the value for `bucketName` is stored as a token:
**Example**
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// Store value of the S3 bucket name
const myBucketName = myBucket.bucketName;
// Print the current value for the S3 bucket name at synthesis
console.log("myBucketName: " + myBucketName);
}
}
```
```
const { Stack, Duration } = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
class CdkDemoAppStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// Store value of the S3 bucket name
const myBucketName = myBucket.bucketName;
// Print the current value for the S3 bucket name at synthesis
console.log("myBucketName: " + myBucketName);
}
}
module.exports = { CdkDemoAppStack }
```
```
from aws_cdk import (
Stack
)
from constructs import Construct
from aws_cdk import aws_s3 as s3
class CdkDemoAppStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define an S3 bucket
my_bucket = s3.Bucket(self, "myBucket")
# Store the value of the S3 bucket name
my_bucket_name = my_bucket.bucket_name
# Print the current value for the S3 bucket name at synthesis
print(f"myBucketName: {my_bucket_name}")
```
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import java.util.Map;
public class CdkDemoAppStack extends Stack {
public CdkDemoAppStack(final Construct scope, final String id) {
this(scope, id, null);
}
public CdkDemoAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Define an S3 bucket
Bucket myBucket = Bucket.Builder.create(this, "myBucket")
.build();
// Store the token for the bucket name
String myBucketName = myBucket.getBucketName();
// Print the token at synthesis
System.out.println("myBucketName: " + myBucketName);
}
}
```
```
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
namespace CdkDemoApp
{
public class CdkDemoAppStack : Stack
{
internal CdkDemoAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Define an S3 bucket
var myBucket = new Bucket(this, "myBucket");
// Store the token for the bucket name
var myBucketName = myBucket.BucketName;
// Print the token at synthesis
System.Console.WriteLine($"myBucketName: {myBucketName}");
}
}
}
```
```
package main
import (
"fmt"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type CdkDemoAppStackProps struct {
awscdk.StackProps
}
func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// Define an S3 bucket
myBucket := awss3.NewBucket(stack, jsii.String("myBucket"), &awss3.BucketProps{})
// Store the token for the bucket name
myBucketName := myBucket.BucketName()
// Print the token at synthesis
fmt.Println("myBucketName: ", *myBucketName)
return stack
}
// ...
```
When we run `cdk synth` to synthesize our stack, the value for `myBucketName` will be displayed in the token format of `${Token[TOKEN.<1234>]}`. This token format is a result of how the AWS CDK encodes tokens. In this example, the token is encoded as a string:
```
$ cdk synth --quiet
myBucketName: ${Token[TOKEN.21]}
```
Since the value for our bucket name is not known at synthesis, the token is rendered as `myBucket`. Our AWS CloudFormation template uses the `Ref` intrinsic function to reference its value, which will be known at deployment:
```
Resources:
myBucket<5AF9C99B>:
# ...
Outputs:
bucketNameOutput:
Description: The name of the S3 bucket
Value:
Ref: myBucket<5AF9C99B>
```
For more information on how the unique hash is generated, see [Generated logical IDs in your AWS CloudFormation template](configure-synth.md#how-synth-default-logical-ids).
## Passing tokens
Tokens can be passed around as if they were the actual value they represent. The following is an example that passes the token for our bucket name to a construct for an AWS Lambda function:
**Example**
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Define a Lambda function
const myFunction = new lambda.Function(this, "myFunction", {
runtime: lambda.Runtime.NODEJS_20_X,
handler: "index.handler",
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
functionName: myBucketName + "Function", // Pass token for the S3 bucket name
environment: {
BUCKET_NAME: myBucketName, // Pass token for the S3 bucket name
}
});
}
}
```
```
const { Stack, Duration } = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');
const lambda = require('aws-cdk-lib/aws-lambda');
class CdkDemoAppStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Define a Lambda function
const myFunction = new lambda.Function(this, 'myFunction', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
functionName: myBucketName + 'Function', // Pass token for the S3 bucket name
environment: {
BUCKET_NAME: myBucketName, // Pass token for the S3 bucket name
}
});
}
}
module.exports = { CdkDemoAppStack }
```
```
from aws_cdk import (
Stack
)
from constructs import Construct
from aws_cdk import aws_s3 as s3
from aws_cdk import aws_lambda as _lambda
class CdkDemoAppStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define an S3 bucket
my_bucket = s3.Bucket(self, "myBucket")
# ...
# Define a Lambda function
my_function = _lambda.Function(self, "myFunction",
runtime=_lambda.Runtime.NODEJS_20_X,
handler="index.handler",
code=_lambda.Code.from_inline("""
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"""),
function_name=f"{my_bucket_name}Function", # Pass token for the S3 bucket name
environment={
"BUCKET_NAME": my_bucket_name # Pass token for the S3 bucket name
}
)
```
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Code;
import software.amazon.awscdk.services.lambda.Function;
import software.amazon.awscdk.services.lambda.Runtime;
import java.util.Map;
public class CdkDemoAppStack extends Stack {
public CdkDemoAppStack(final Construct scope, final String id) {
this(scope, id, null);
}
public CdkDemoAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Define an S3 bucket
Bucket myBucket = Bucket.Builder.create(this, "myBucket")
.build();
// ...
// Define a Lambda function
Function myFunction = Function.Builder.create(this, "myFunction")
.runtime(Runtime.NODEJS_20_X)
.handler("index.handler")
.code(Code.fromInline(
"exports.handler = async function(event) {" +
"return {" +
"statusCode: 200," +
"body: JSON.stringify('Hello World!')," +
"};" +
"};"
))
.functionName(myBucketName + "Function") // Pass the token for the s3 bucket to the function construct
.environment(Map.of("BUCKET_NAME", myBucketName)) // Pass the bucket name as environment variable
.build();
}
}
```
```
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;
using System;
using System.Collections.Generic;
namespace CdkDemoApp
{
public class CdkDemoAppStack : Stack
{
internal CdkDemoAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Define an S3 bucket
var myBucket = new Bucket(this, "myBucket");
// ...
// Define a Lambda function
var myFunction = new Function(this, "myFunction", new FunctionProps
{
Runtime = Runtime.NODEJS_20_X,
Handler = "index.handler",
Code = Code.FromInline(@"
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"),
// Pass the token for the S3 bucket name
Environment = new Dictionary
{
{ "BUCKET_NAME", myBucketName }
},
FunctionName = $"{myBucketName}Function" // Pass the token for the s3 bucket to the function construct
});
}
}
}
```
```
package main
import (
"fmt"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type CdkDemoAppStackProps struct {
awscdk.StackProps
}
func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// Define an S3 bucket
myBucket := awss3.NewBucket(stack, jsii.String("myBucket"), &awss3.BucketProps{})
// ...
// Define a Lambda function
myFunction := awslambda.NewFunction(stack, jsii.String("myFunction"), &awslambda.FunctionProps{
Runtime: awslambda.Runtime_NODEJS_20_X(),
Handler: jsii.String("index.handler"),
Code: awslambda.Code_FromInline(jsii.String(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`)),
FunctionName: jsii.String(fmt.Sprintf("%sFunction", *myBucketName)), // Pass the token for the S3 bucket to the function name
Environment: &map[string]*string{
"BUCKET_NAME": myBucketName,
},
})
return stack
}
// ...
```
When we synthesize our template, the `Ref` and `Fn::Join` intrinsic functions are used to specify the values, which will be known at deployment:
```
Resources:
myBucket<5AF9C99B>:
Type: AWS::S3::Bucket
# ...
myFunction<884E1557>:
Type: AWS::Lambda::Function
Properties:
# ...
Environment:
Variables:
BUCKET_NAME:
Ref: myBucket<5AF9C99B>
FunctionName:
Fn::Join:
- ""
- - Ref: myBucket<5AF9C99B>
- Function
# ...
```
## How token encodings work
Tokens are objects that implement the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IResolvable.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IResolvable.html) interface, which contains a single `resolve` method. During synthesis, the AWS CDK calls this method to produce the final value for tokens in your CloudFormation template.
**Note**
You’ll rarely work directly with the `IResolvable` interface. You will most likely only see string-encoded versions of tokens.
### Token encoding types
Tokens participate in the synthesis process to produce arbitrary values of any type. Other functions typically only accept arguments of basic types, such as `string` or `number`. To use tokens in these cases, you can encode them into one of three types by using static methods on the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html) class.
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-aswbrstringvalue-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-aswbrstringvalue-options) to generate a string encoding (or call `.toString()` on the token object).
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-aswbrlistvalue-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-aswbrlistvalue-options) to generate a list encoding.
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-aswbrnumbervalue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-aswbrnumbervalue) to generate a numeric encoding.
These take an arbitrary value, which can be an `IResolvable`, and encode them into a primitive value of the indicated type.
**Important**
Because any one of the previous types can potentially be an encoded token, be careful when you parse or try to read their contents. For example, if you attempt to parse a string to extract a value from it, and the string is an encoded token, your parsing fails. Similarly, if you try to query the length of an array or perform math operations with a number, you must first verify that they aren’t encoded tokens.
## How to check for tokens in your app
To check whether a value has an unresolved token in it, call the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-iswbrunresolvedobj](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-iswbrunresolvedobj) (Python: `is_unresolved`) method. The following is an example that checks if the value for our Amazon S3 bucket name is a token. If its not a token, we then validate the length of the bucket name:
**Example**
```
// ...
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Check if bucket name is a token. If not, check if length is less than 10 characters
if (cdk.Token.isUnresolved(myBucketName)) {
console.log("Token identified.");
} else if (!cdk.Token.isUnresolved(myBucketName) && myBucketName.length > 10) {
throw new Error('Maximum length for name is 10 characters.');
};
// ...
}
}
```
```
const { Stack, Duration, Token, CfnOutput } = require('aws-cdk-lib');
// ...
class CdkDemoAppStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Check if bucket name is a token. If not, check if length is less than 10 characters
if (Token.isUnresolved(myBucketName)) {
console.log("Token identified.");
} else if (!Token.isUnresolved(myBucketName) && myBucketName.length > 10) {
throw new Error('Maximum length for name is 10 characters.');
};
// ...
}
}
```
```
from aws_cdk import (
Stack,
Token
)
# ...
class CdkDemoAppStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define an S3 bucket
my_bucket = s3.Bucket(self, "myBucket")
# ...
# Check if bucket name is a token. If not, check if length is less than 10 characters
if Token.is_unresolved(my_bucket_name):
print("Token identified.")
elif not Token.is_unresolved(my_bucket_name) and len(my_bucket_name) < 10:
raise ValueError("Maximum length for name is 10 characters.")
# ...
```
```
// ...
import software.amazon.awscdk.Token;
import software.amazon.awscdk.services.s3.Bucket;
// ...
public class CdkDemoAppStack extends Stack {
public CdkDemoAppStack(final Construct scope, final String id) {
this(scope, id, null);
}
public CdkDemoAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Define an S3 bucket
Bucket myBucket = Bucket.Builder.create(this, "myBucket")
.build();
// ...
// Get the bucket name
String myBucketName = myBucket.getBucketName();
// Check if the bucket name is a token. If not, check if length is less than 10 characters
if (Token.isUnresolved(myBucketName)) {
System.out.println("Token identified.");
} else if (!Token.isUnresolved(myBucketName) && myBucketName.length() > 10) {
throw new IllegalArgumentException("Maximum length for name is 10 characters.");
}
// ...
}
}
}
```
```
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;
using System;
using System.Collections.Generic;
namespace CdkDemoApp
{
public class CdkDemoAppStack : Stack
{
internal CdkDemoAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Define an S3 bucket
var myBucket = new Bucket(this, "myBucket");
// ...
// Get the bucket name
var myBucketName = myBucket.BucketName;
// Check if bucket name is a token. If not, check if length is less than 10 characters
if (Token.IsUnresolved(myBucketName))
{
System.Console.WriteLine("Token identified.");
}
else if (!Token.IsUnresolved(myBucketName) && myBucketName.Length > 10)
{
throw new System.Exception("Maximum length for name is 10 characters.");
}
// ...
}
}
}
```
```
// ...
func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// Define an S3 bucket
myBucket := awss3.NewBucket(stack, jsii.String("myBucket"), &awss3.BucketProps{})
// ...
// Check if the bucket name is unresolved (a token)
if tokenUnresolved := awscdk.Token_IsUnresolved(myBucketName); tokenUnresolved != nil && *tokenUnresolved {
fmt.Println("Token identified.")
} else if tokenUnresolved != nil && !*tokenUnresolved && len(*myBucketName) > 10 {
panic("Maximum length for name is 10 characters.")
}
// ...
}
```
When we run `cdk synth`, `myBucketName` is identified as a token:
```
$ cdk synth --quiet
Token identified.
```
**Note**
You can use token encodings to escape the type system. For example, you could string-encode a token that produces a number value at synthesis time. If you use these functions, it’s your responsibility to make sure that your template resolves to a usable state after synthesis.
## Working with string-encoded tokens
String-encoded tokens look like the following.
```
${TOKEN[Bucket.Name.1234]}
```
They can be passed around like regular strings, and can be concatenated, as shown in the following example.
**Example**
```
const functionName = bucket.bucketName + 'Function';
```
```
const functionName = bucket.bucketName + 'Function';
```
```
function_name = bucket.bucket_name + "Function"
```
```
String functionName = bucket.getBucketName().concat("Function");
```
```
string functionName = bucket.BucketName + "Function";
```
```
functionName := *bucket.BucketName() + "Function"
```
You can also use string interpolation, if your language supports it, as shown in the following example.
**Example**
```
const functionName = `${bucket.bucketName}Function`;
```
```
const functionName = `${bucket.bucketName}Function`;
```
```
function_name = f"{bucket.bucket_name}Function"
```
```
String functionName = String.format("%sFunction". bucket.getBucketName());
```
```
string functionName = $"${bucket.bucketName}Function";
```
Use `fmt.Sprintf` for similar functionality:
```
functionName := fmt.Sprintf("%sFunction", *bucket.BucketName())
```
Avoid manipulating the string in other ways. For example, taking a substring of a string is likely to break the string token.
## Working with list-encoded tokens
List-encoded tokens look like the following:
```
["#{TOKEN[Stack.NotificationArns.1234]}"]
```
The only safe thing to do with these lists is pass them directly to other constructs. Tokens in string list form cannot be concatenated, nor can an element be taken from the token. The only safe way to manipulate them is by using AWS CloudFormation intrinsic functions like [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-select.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-select.html).
## Working with number-encoded tokens
Number-encoded tokens are a set of tiny negative floating-point numbers that look like the following.
```
-1.8881545897087626e+289
```
As with list tokens, you cannot modify the number value, as doing so is likely to break the number token.
The following is an example of a construct that contains a token encoded as a number:
**Example**
```
import { Stack, Duration, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as rds from 'aws-cdk-lib/aws-rds';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
const vpc = new ec2.Vpc(this, 'MyVpc', {
maxAzs: 3, // Maximum number of availability zones to use
});
// Define an RDS database cluster
const dbCluster = new rds.DatabaseCluster(this, 'MyRDSCluster', {
engine: rds.DatabaseClusterEngine.AURORA,
instanceProps: {
vpc,
},
});
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// Print the value for our token at synthesis
console.log("portToken: " + portToken);
}
}
```
```
const { Stack, Duration } = require('aws-cdk-lib');
const lambda = require('aws-cdk-lib/aws-lambda');
const rds = require('aws-cdk-lib/aws-rds');
const ec2 = require('aws-cdk-lib/aws-ec2');
class CdkDemoAppStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define a new VPC
const vpc = new ec2.Vpc(this, 'MyVpc', {
maxAzs: 3, // Maximum number of availability zones to use
});
// Define an RDS database cluster
const dbCluster = new rds.DatabaseCluster(this, 'MyRDSCluster', {
engine: rds.DatabaseClusterEngine.AURORA,
instanceProps: {
vpc,
},
});
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// Print the value for our token at synthesis
console.log("portToken: " + portToken);
}
}
module.exports = { CdkDemoAppStack }
```
```
from aws_cdk import (
Duration,
Stack,
)
from aws_cdk import aws_rds as rds
from aws_cdk import aws_ec2 as ec2
from constructs import Construct
class CdkDemoAppStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define a new VPC
vpc = ec2.Vpc(self, 'MyVpc',
max_azs=3 # Maximum number of availability zones to use
)
# Define an RDS database cluster
db_cluster = rds.DatabaseCluster(self, 'MyRDSCluster',
engine=rds.DatabaseClusterEngine.AURORA,
instance_props=rds.InstanceProps(
vpc=vpc
)
)
# Get the port token (this is a token encoded as a number)
port_token = db_cluster.cluster_endpoint.port
# Print the value for our token at synthesis
print(f"portToken: {port_token}")
```
```
package com.myorg;
import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.ec2.Vpc;
import software.amazon.awscdk.services.rds.DatabaseCluster;
import software.amazon.awscdk.services.rds.DatabaseClusterEngine;
import software.amazon.awscdk.services.rds.InstanceProps;
public class CdkDemoAppStack extends Stack {
public CdkDemoAppStack(final Construct scope, final String id) {
this(scope, id, null);
}
public CdkDemoAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Define a new VPC
Vpc vpc = Vpc.Builder.create(this, "MyVpc")
.maxAzs(3) // Maximum number of availability zones to use
.build();
// Define an RDS database cluster
DatabaseCluster dbCluster = DatabaseCluster.Builder.create(this, "MyRDSCluster")
.engine(DatabaseClusterEngine.AURORA)
.instanceProps(InstanceProps.builder()
.vpc(vpc)
.build())
.build();
// Get the port token (this is a token encoded as a number)
Number portToken = dbCluster.getClusterEndpoint().getPort();
// Print the value for our token at synthesis
System.out.println("portToken: " + portToken);
}
}
```
```
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.EC2;
using Amazon.CDK.AWS.RDS;
using System;
using System.Collections.Generic;
namespace CdkDemoApp
{
public class CdkDemoAppStack : Stack
{
internal CdkDemoAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Define a new VPC
var vpc = new Vpc(this, "MyVpc", new VpcProps
{
MaxAzs = 3 // Maximum number of availability zones to use
});
// Define an RDS database cluster
var dbCluster = new DatabaseCluster(this, "MyRDSCluster", new DatabaseClusterProps
{
Engine = DatabaseClusterEngine.AURORA, // Remove parentheses
InstanceProps = new Amazon.CDK.AWS.RDS.InstanceProps // Specify RDS InstanceProps
{
Vpc = vpc
}
});
// Get the port token (this is a token encoded as a number)
var portToken = dbCluster.ClusterEndpoint.Port;
// Print the value for our token at synthesis
System.Console.WriteLine($"portToken: {portToken}");
}
}
}
```
```
package main
import (
"fmt"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awsec2"
"github.com/aws/aws-cdk-go/awscdk/v2/awsrds"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
type CdkDemoAppStackProps struct {
awscdk.StackProps
}
func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// Define a new VPC
vpc := awsec2.NewVpc(stack, jsii.String("MyVpc"), &awsec2.VpcProps{
MaxAzs: jsii.Number(3), // Maximum number of availability zones to use
})
// Define an RDS database cluster
dbCluster := awsrds.NewDatabaseCluster(stack, jsii.String("MyRDSCluster"), &awsrds.DatabaseClusterProps{
Engine: awsrds.DatabaseClusterEngine_AURORA(),
InstanceProps: &awsrds.InstanceProps{
Vpc: vpc,
},
})
// Get the port token (this is a token encoded as a number)
portToken := dbCluster.ClusterEndpoint().Port()
// Print the value for our token at synthesis
fmt.Println("portToken: ", portToken)
return stack
}
// ...
```
When we run `cdk synth`, the value for `portToken` is displayed as a number-encoded token:
```
$ cdk synth --quiet
portToken: -1.8881545897087968e+289
```
### Pass number-encoded tokens
When you pass number-encoded tokens to other constructs, it may make sense to convert them to strings first. For example, if you want to use the value of a number-encoded string as part of a concatenated string, converting it helps with readability.
In the following example,`portToken` is a number-encoded token that we want to pass to our Lambda function as part of `connectionString`:
**Example**
```
import { Stack, Duration, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Example connection string with the port token as a number
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portToken}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}
```
```
const { Stack, Duration, CfnOutput } = require('aws-cdk-lib');
// ...
const lambda = require('aws-cdk-lib/aws-lambda');
class CdkDemoAppStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Example connection string with the port token as a number
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portToken}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}
module.exports = { CdkDemoAppStack }
```
```
from aws_cdk import (
Duration,
Stack,
CfnOutput,
)
from aws_cdk import aws_lambda as _lambda
# ...
class CdkDemoAppStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define a new VPC
# ...
# Define an RDS database cluster
# ...
# Get the port token (this is a token encoded as a number)
port_token = db_cluster.cluster_endpoint.port
# ...
# Example connection string with the port token as a number
connection_string = f"jdbc:mysql://mydb.cluster.amazonaws.com:{port_token}/mydatabase"
# Use the connection string as an environment variable in a Lambda function
my_function = _lambda.Function(self, 'MyLambdaFunction',
runtime=_lambda.Runtime.NODEJS_20_X,
handler='index.handler',
code=_lambda.Code.from_inline("""
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"""),
environment={
'DATABASE_CONNECTION_STRING': connection_string # Using the port token as part of the string
}
)
# Output the value of our connection string at synthesis
print(f"connectionString: {connection_string}")
# Output the connection string
CfnOutput(self, 'ConnectionString',
value=connection_string
)
```
```
// ...
import software.amazon.awscdk.CfnOutput;
import software.amazon.awscdk.services.lambda.Function;
import software.amazon.awscdk.services.lambda.Runtime;
import software.amazon.awscdk.services.lambda.Code;
import java.util.Map;
public class CdkDemoAppStack extends Stack {
public CdkDemoAppStack(final Construct scope, final String id) {
this(scope, id, null);
}
public CdkDemoAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
Number portToken = dbCluster.getClusterEndpoint().getPort();
// ...
// Example connection string with the port token as a number
String connectionString = "jdbc:mysql://mydb.cluster.amazonaws.com:" + portToken + "/mydatabase";
// Use the connection string as an environment variable in a Lambda function
Function myFunction = Function.Builder.create(this, "MyLambdaFunction")
.runtime(Runtime.NODEJS_20_X)
.handler("index.handler")
.code(Code.fromInline(
"exports.handler = async function(event) {\n" +
" return {\n" +
" statusCode: 200,\n" +
" body: JSON.stringify('Hello World!'),\n" +
" };\n" +
"};"))
.environment(Map.of(
"DATABASE_CONNECTION_STRING", connectionString // Using the port token as part of the string
))
.build();
// Output the value of our connection string at synthesis
System.out.println("connectionString: " + connectionString);
// Output the connection string
CfnOutput.Builder.create(this, "ConnectionString")
.value(connectionString)
.build();
}
}
```
```
// ...
using Amazon.CDK.AWS.Lambda;
using Amazon.CDK.AWS.RDS;
using Amazon.CDK;
using Constructs;
using System;
using System.Collections.Generic;
namespace CdkDemoApp
{
public class CdkDemoAppStack : Stack
{
internal CdkDemoAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Define a new VPC
// ...
// Define an RDS database cluster
var dbCluster = new DatabaseCluster(this, "MyRDSCluster", new DatabaseClusterProps
{
// ... properties would go here
});
// Get the port token (this is a token encoded as a number)
var portToken = dbCluster.ClusterEndpoint.Port;
// ...
// Example connection string with the port token as a number
var connectionString = $"jdbc:mysql://mydb.cluster.amazonaws.com:{portToken}/mydatabase";
// Use the connection string as an environment variable in a Lambda function
var myFunction = new Function(this, "MyLambdaFunction", new FunctionProps
{
Runtime = Runtime.NODEJS_20_X,
Handler = "index.handler",
Code = Code.FromInline(@"
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
"),
Environment = new Dictionary
{
{ "DATABASE_CONNECTION_STRING", connectionString } // Using the port token as part of the string
}
});
// Output the value of our connection string at synthesis
Console.WriteLine($"connectionString: {connectionString}");
// Output the connection string
new CfnOutput(this, "ConnectionString", new CfnOutputProps
{
Value = connectionString
});
}
}
}
```
```
// ...
"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
)
type CdkDemoAppStackProps struct {
awscdk.StackProps
}
func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
portToken := dbCluster.ClusterEndpoint().Port()
// ...
// Example connection string with the port token as a number
connectionString := fmt.Sprintf("jdbc:mysql://mydb.cluster.amazonaws.com:%s/mydatabase", portToken)
// Use the connection string as an environment variable in a Lambda function
myFunction := awslambda.NewFunction(stack, jsii.String("MyLambdaFunction"), &awslambda.FunctionProps{
Runtime: awslambda.Runtime_NODEJS_20_X(),
Handler: jsii.String("index.handler"),
Code: awslambda.Code_FromInline(jsii.String(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`)),
Environment: &map[string]*string{
"DATABASE_CONNECTION_STRING": jsii.String(connectionString), // Using the port token as part of the string
},
})
// Output the value of our connection string at synthesis
fmt.Println("connectionString: ", connectionString)
// Output the connection string
awscdk.NewCfnOutput(stack, jsii.String("ConnectionString"), &awscdk.CfnOutputProps{
Value: jsii.String(connectionString),
})
return stack
}
// ...
```
If we pass this value to `connectionString`, the output value when we run `cdk synth` may be confusing due to the number-encoded string:
```
$ cdk synth --quiet
connectionString: jdbc:mysql://mydb.cluster.amazonaws.com:-1.888154589708796e+289/mydatabase
```
To convert a number-encoded token to a string, use [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tokenization.html#static-stringifywbrnumberx](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tokenization.html#static-stringifywbrnumberx). In the following example, we convert the number-encoded token to a string before defining our connection string:
**Example**
```
import { Stack, Duration, Tokenization, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Convert the encoded number to an encoded string for use in the connection string
const portAsString = Tokenization.stringifyNumber(portToken);
// Example connection string with the port token as a string
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portAsString}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
// ...
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}
```
```
const { Stack, Duration, Tokenization, CfnOutput } = require('aws-cdk-lib');
// ...
class CdkDemoAppStack extends Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Convert the encoded number to an encoded string for use in the connection string
const portAsString = Tokenization.stringifyNumber(portToken);
// Example connection string with the port token as a string
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portAsString}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
// ...
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}
module.exports = { CdkDemoAppStack }
```
```
from aws_cdk import (
Duration,
Stack,
Tokenization,
CfnOutput,
)
# ...
class CdkDemoAppStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define a new VPC
# ...
# Define an RDS database cluster
# ...
# Get the port token (this is a token encoded as a number)
port_token = db_cluster.cluster_endpoint.port
# Convert the encoded number to an encoded string for use in the connection string
port_as_string = Tokenization.stringify_number(port_token)
# Example connection string with the port token as a string
connection_string = f"jdbc:mysql://mydb.cluster.amazonaws.com:{port_as_string}/mydatabase"
# Use the connection string as an environment variable in a Lambda function
my_function = _lambda.Function(self, 'MyLambdaFunction',
# ...
environment={
'DATABASE_CONNECTION_STRING': connection_string # Using the port token as part of the string
}
)
# Output the value of our connection string at synthesis
print(f"connectionString: {connection_string}")
# Output the connection string
CfnOutput(self, 'ConnectionString',
value=connection_string
)
```
```
// ...
import software.amazon.awscdk.Tokenization;
public class CdkDemoAppStack extends Stack {
public CdkDemoAppStack(final Construct scope, final String id) {
this(scope, id, null);
}
public CdkDemoAppStack(final Construct scope, final String id, final StackProps props) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
Number portToken = dbCluster.getClusterEndpoint().getPort();
// ...
// Convert the encoded number to an encoded string for use in the connection string
String portAsString = Tokenization.stringifyNumber(portToken);
// Example connection string with the port token as a string
String connectionString = "jdbc:mysql://mydb.cluster.amazonaws.com:" + portAsString + "/mydatabase";
// Use the connection string as an environment variable in a Lambda function
Function myFunction = Function.Builder.create(this, "MyLambdaFunction")
// ...
.environment(Map.of(
"DATABASE_CONNECTION_STRING", connectionString // Using the port token as part of the string
))
.build();
// Output the value of our connection string at synthesis
System.out.println("connectionString: " + connectionString);
// Output the connection string
CfnOutput.Builder.create(this, "ConnectionString")
.value(connectionString)
.build();
}
}
```
```
// ...
namespace CdkDemoApp
{
public class CdkDemoAppStack : Stack
{
internal CdkDemoAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props)
{
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
var portToken = dbCluster.ClusterEndpoint.Port;
// ...
// Convert the encoded number to an encoded string for use in the connection string
var portAsString = Tokenization.StringifyNumber(portToken);
// Example connection string with the port token as a string
var connectionString = $"jdbc:mysql://mydb.cluster.amazonaws.com:{portAsString}/mydatabase";
// Use the connection string as an environment variable in a Lambda function
var myFunction = new Function(this, "MyLambdaFunction", new FunctionProps
{
// ...
Environment = new Dictionary
{
{ "DATABASE_CONNECTION_STRING", connectionString } // Using the port token as part of the string
}
});
// Output the value of our connection string at synthesis
Console.WriteLine($"connectionString: {connectionString}");
// Output the connection string
new CfnOutput(this, "ConnectionString", new CfnOutputProps
{
Value = connectionString
});
}
}
}
```
```
// ...
func NewCdkDemoAppStack(scope constructs.Construct, id string, props *CdkDemoAppStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, &id, &sprops)
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
portToken := dbCluster.ClusterEndpoint().Port()
// ...
// Convert the encoded number to an encoded string for use in the connection string
portAsString := awscdk.Tokenization_StringifyNumber(portToken)
// Example connection string with the port token as a string
connectionString := fmt.Sprintf("jdbc:mysql://mydb.cluster.amazonaws.com:%s/mydatabase", portAsString)
// Use the connection string as an environment variable in a Lambda function
myFunction := awslambda.NewFunction(stack, jsii.String("MyLambdaFunction"), &awslambda.FunctionProps{
// ...
Environment: &map[string]*string{
"DATABASE_CONNECTION_STRING": jsii.String(connectionString), // Using the port token as part of the string
},
})
// Output the value of our connection string at synthesis
fmt.Println("connectionString: ", connectionString)
// Output the connection string
awscdk.NewCfnOutput(stack, jsii.String("ConnectionString"), &awscdk.CfnOutputProps{
Value: jsii.String(connectionString),
})
fmt.Println(myFunction)
return stack
}
// ...
```
When we run `cdk synth`, the value for our connection string is represented in a cleaner and clearer format:
```
$ cdk synth --quiet
connectionString: jdbc:mysql://mydb.cluster.amazonaws.com:${Token[TOKEN.242]}/mydatabase
```
## Lazy values
In addition to representing deploy-time values, such as AWS CloudFormation [parameters](parameters.md), tokens are also commonly used to represent synthesis-time lazy values. These are values for which the final value will be determined before synthesis has completed, but not at the point where the value is constructed. Use tokens to pass a literal string or number value to another construct, while the actual value at synthesis time might depend on some calculation that has yet to occur.
You can construct tokens representing synth-time lazy values using static methods on the `Lazy` class, such as [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-stringproducer-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-stringproducer-options) and [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-numberproducer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-numberproducer). These methods accept an object whose `produce` property is a function that accepts a context argument and returns the final value when called.
The following example creates an Auto Scaling group whose capacity is determined after its creation.
**Example**
```
let actualValue: number;
new AutoScalingGroup(this, 'Group', {
desiredCapacity: Lazy.numberValue({
produce(context) {
return actualValue;
}
})
});
// At some later point
actualValue = 10;
```
```
let actualValue;
new AutoScalingGroup(this, 'Group', {
desiredCapacity: Lazy.numberValue({
produce(context) {
return (actualValue);
}
})
});
// At some later point
actualValue = 10;
```
```
class Producer:
def __init__(self, func):
self.produce = func
actual_value = None
AutoScalingGroup(self, "Group",
desired_capacity=Lazy.number_value(Producer(lambda context: actual_value))
)
# At some later point
actual_value = 10
```
```
double actualValue = 0;
class ProduceActualValue implements INumberProducer {
@Override
public Number produce(IResolveContext context) {
return actualValue;
}
}
AutoScalingGroup.Builder.create(this, "Group")
.desiredCapacity(Lazy.numberValue(new ProduceActualValue())).build();
// At some later point
actualValue = 10;
```
```
public class NumberProducer : INumberProducer
{
Func function;
public NumberProducer(Func function)
{
this.function = function;
}
public Double Produce(IResolveContext context)
{
return function();
}
}
double actualValue = 0;
new AutoScalingGroup(this, "Group", new AutoScalingGroupProps
{
DesiredCapacity = Lazy.NumberValue(new NumberProducer(() => actualValue))
});
// At some later point
actualValue = 10;
```
## Converting to JSON
Sometimes you want to produce a JSON string of arbitrary data, and you may not know whether the data contains tokens. To properly JSON-encode any data structure, regardless of whether it contains tokens, use the method [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#towbrjsonwbrstringobj-space](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#towbrjsonwbrstringobj-space), as shown in the following example.
**Example**
```
const stack = Stack.of(this);
const str = stack.toJsonString({
value: bucket.bucketName
});
```
```
const stack = Stack.of(this);
const str = stack.toJsonString({
value: bucket.bucketName
});
```
```
stack = Stack.of(self)
string = stack.to_json_string(dict(value=bucket.bucket_name))
```
```
Stack stack = Stack.of(this);
String stringVal = stack.toJsonString(java.util.Map.of( // Map.of requires Java 9+
put("value", bucket.getBucketName())));
```
```
var stack = Stack.Of(this);
var stringVal = stack.ToJsonString(new Dictionary
{
["value"] = bucket.BucketName
});
```
# Parameters and the AWS CDK
*Parameters* are custom values that are supplied at deployment time. [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) are a feature of AWS CloudFormation. Since the AWS Cloud Development Kit (AWS CDK) synthesizes AWS CloudFormation templates, it also offers support for deployment-time parameters.
## About parameters
Using the AWS CDK, you can define parameters, which can then be used in the properties of constructs you create. You can also deploy stacks that contain parameters.
When deploying the AWS CloudFormation template using the AWS CDK CLI, you provide the parameter values on the command line. If you deploy the template through the AWS CloudFormation console, you are prompted for the parameter values.
In general, we recommend against using AWS CloudFormation parameters with the AWS CDK. The usual ways to pass values into AWS CDK apps are [context values](context.md) and environment variables. Because they are not available at synthesis time, parameter values cannot be easily used for flow control and other purposes in your CDK app.
**Note**
To do control flow with parameters, you can use [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnCondition.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnCondition.html) constructs, although this is awkward compared to native `if` statements.
Using parameters requires you to be mindful of how the code you’re writing behaves at deployment time, and also at synthesis time. This makes it harder to understand and reason about your AWS CDK application, in many cases for little benefit.
Generally, it’s better to have your CDK app accept necessary information in a well-defined way and use it directly to declare constructs in your CDK app. An ideal AWS CDK–generated AWS CloudFormation template is concrete, with no values remaining to be specified at deployment time.
There are, however, use cases to which AWS CloudFormation parameters are uniquely suited. If you have separate teams defining and deploying infrastructure, for example, you can use parameters to make the generated templates more widely useful. Also, because the AWS CDK supports AWS CloudFormation parameters, you can use the AWS CDK with AWS services that use AWS CloudFormation templates (such as Service Catalog). These AWS services use parameters to configure the template that’s being deployed.
## Learn more
For instructions on developing CDK apps with parameters, see [Use CloudFormation parameters to get a CloudFormation value](get-cfn-param.md).
# Tags and the AWS CDK
Tags are informational key-value elements that you can add to constructs in your AWS CDK app. A tag applied to a given construct also applies to all of its taggable children. Tags are included in the AWS CloudFormation template synthesized from your app and are applied to the AWS resources it deploys. You can use tags to identify and categorize resources for the following purposes:
+ Simplifying management
+ Cost allocation
+ Access control
+ Any other purposes that you devise
**Tip**
For more information about how you can use tags with your AWS resources, see [Best Practices for Tagging AWS Resources](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html) in the * AWS Whitepaper*.
## Using tags
The [Tags](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html) class includes the static method `of()`, through which you can add tags to, or remove tags from, the specified construct.
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#addkey-value-props](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#addkey-value-props) applies a new tag to the given construct and all of its children.
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#removekey-props](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tags.html#removekey-props) removes a tag from the given construct and any of its children, including tags a child construct may have applied to itself.
**Note**
Tagging is implemented using [Aspects and the AWS CDK](aspects.md). Aspects are a way to apply an operation (such as tagging) to all constructs in a given scope.
The following example applies the tag **key** with the value **value** to a construct.
**Example**
```
Tags.of(myConstruct).add('key', 'value');
```
```
Tags.of(myConstruct).add('key', 'value');
```
```
Tags.of(my_construct).add("key", "value")
```
```
Tags.of(myConstruct).add("key", "value");
```
```
Tags.Of(myConstruct).Add("key", "value");
```
```
awscdk.Tags_Of(myConstruct).Add(jsii.String("key"), jsii.String("value"), &awscdk.TagProps{})
```
The following example deletes the tag **key** from a construct.
**Example**
```
Tags.of(myConstruct).remove('key');
```
```
Tags.of(myConstruct).remove('key');
```
```
Tags.of(my_construct).remove("key")
```
```
Tags.of(myConstruct).remove("key");
```
```
Tags.Of(myConstruct).Remove("key");
```
```
awscdk.Tags_Of(myConstruct).Remove(jsii.String("key"), &awscdk.TagProps{})
```
If you are using `Stage` constructs, apply the tag at the `Stage` level or below. Tags are not applied across `Stage` boundaries.
## Tag priorities
The AWS CDK applies and removes tags recursively. If there are conflicts, the tagging operation with the highest priority wins. (Priorities are set using the optional `priority` property.) If the priorities of two operations are the same, the tagging operation closest to the bottom of the construct tree wins. By default, applying a tag has a priority of 100 (except for tags added directly to an AWS CloudFormation resource, which has a priority of 50). The default priority for removing a tag is 200.
The following applies a tag with a priority of 300 to a construct.
**Example**
```
Tags.of(myConstruct).add('key', 'value', {
priority: 300
});
```
```
Tags.of(myConstruct).add('key', 'value', {
priority: 300
});
```
```
Tags.of(my_construct).add("key", "value", priority=300)
```
```
Tags.of(myConstruct).add("key", "value", TagProps.builder()
.priority(300).build());
```
```
Tags.Of(myConstruct).Add("key", "value", new TagProps { Priority = 300 });
```
```
awscdk.Tags_Of(myConstruct).Add(jsii.String("key"), jsii.String("value"), &awscdk.TagProps{
Priority: jsii.Number(300),
})
```
## Optional properties
Tags support [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.TagProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.TagProps.html) that fine-tune how tags are applied to, or removed from, resources. All properties are optional.
`applyToLaunchedInstances` (Python: `apply_to_launched_instances`)
Available for add() only. By default, tags are applied to instances launched in an Auto Scaling group. Set this property to **false** to ignore instances launched in an Auto Scaling group.
`includeResourceTypes`/`excludeResourceTypes` (Python: `include_resource_types`/`exclude_resource_types`)
Use these to manipulate tags only on a subset of resources, based on AWS CloudFormation resource types. By default, the operation is applied to all resources in the construct subtree, but this can be changed by including or excluding certain resource types. Exclude takes precedence over include, if both are specified.
`priority`
Use this to set the priority of this operation with respect to other `Tags.add()` and `Tags.remove()` operations. Higher values take precedence over lower values. The default is 100 for add operations (50 for tags applied directly to AWS CloudFormation resources) and 200 for remove operations.
The following example applies the tag **tagname** with the value **value** and priority **100** to resources of type ** AWS::Xxx::Yyy** in the construct. It doesn’t apply the tag to instances launched in an Amazon EC2 Auto Scaling group or to resources of type ** AWS::Xxx::Zzz**. (These are placeholders for two arbitrary but different AWS CloudFormation resource types.)
**Example**
```
Tags.of(myConstruct).add('tagname', 'value', {
applyToLaunchedInstances: false,
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 100,
});
```
```
Tags.of(myConstruct).add('tagname', 'value', {
applyToLaunchedInstances: false,
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 100
});
```
```
Tags.of(my_construct).add("tagname", "value",
apply_to_launched_instances=False,
include_resource_types=["AWS::Xxx::Yyy"],
exclude_resource_types=["AWS::Xxx::Zzz"],
priority=100)
```
```
Tags.of(myConstruct).add("tagname", "value", TagProps.builder()
.applyToLaunchedInstances(false)
.includeResourceTypes(Arrays.asList("AWS::Xxx::Yyy"))
.excludeResourceTypes(Arrays.asList("AWS::Xxx::Zzz"))
.priority(100).build());
```
```
Tags.Of(myConstruct).Add("tagname", "value", new TagProps
{
ApplyToLaunchedInstances = false,
IncludeResourceTypes = ["AWS::Xxx::Yyy"],
ExcludeResourceTypes = ["AWS::Xxx::Zzz"],
Priority = 100
});
```
```
awscdk.Tags_Of(myConstruct).Add(jsii.String("tagname"), jsii.String("value"), &awscdk.TagProps{
ApplyToLaunchedInstances: jsii.Bool(false),
IncludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Yyy")},
ExcludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Zzz")},
Priority: jsii.Number(100),
})
```
The following example removes the tag **tagname** with priority **200** from resources of type ** AWS::Xxx::Yyy** in the construct, but not from resources of type ** AWS::Xxx::Zzz**.
**Example**
```
Tags.of(myConstruct).remove('tagname', {
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 200,
});
```
```
Tags.of(myConstruct).remove('tagname', {
includeResourceTypes: ['AWS::Xxx::Yyy'],
excludeResourceTypes: ['AWS::Xxx::Zzz'],
priority: 200
});
```
```
Tags.of(my_construct).remove("tagname",
include_resource_types=["AWS::Xxx::Yyy"],
exclude_resource_types=["AWS::Xxx::Zzz"],
priority=200,)
```
```
Tags.of((myConstruct).remove("tagname", TagProps.builder()
.includeResourceTypes(Arrays.asList("AWS::Xxx::Yyy"))
.excludeResourceTypes(Arrays.asList("AWS::Xxx::Zzz"))
.priority(100).build());
)
```
```
Tags.Of(myConstruct).Remove("tagname", new TagProps
{
IncludeResourceTypes = ["AWS::Xxx::Yyy"],
ExcludeResourceTypes = ["AWS::Xxx::Zzz"],
Priority = 100
});
```
```
awscdk.Tags_Of(myConstruct).Remove(jsii.String("tagname"), &awscdk.TagProps{
IncludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Yyy")},
ExcludeResourceTypes: &[]*string{jsii.String("AWS::Xxx:Zzz")},
Priority: jsii.Number(200),
})
```
## Example
The following example adds the tag key **StackType** with value **TheBest** to any resource created within the `Stack` named `MarketingSystem`. Then it removes it again from all resources except Amazon EC2 VPC subnets. The result is that only the subnets have the tag applied.
**Example**
```
import { App, Stack, Tags } from 'aws-cdk-lib';
const app = new App();
const theBestStack = new Stack(app, 'MarketingSystem');
// Add a tag to all constructs in the stack
Tags.of(theBestStack).add('StackType', 'TheBest');
// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove('StackType', {
excludeResourceTypes: ['AWS::EC2::Subnet']
});
```
```
const { App, Stack, Tags } = require('aws-cdk-lib');
const app = new App();
const theBestStack = new Stack(app, 'MarketingSystem');
// Add a tag to all constructs in the stack
Tags.of(theBestStack).add('StackType', 'TheBest');
// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove('StackType', {
excludeResourceTypes: ['AWS::EC2::Subnet']
});
```
```
from aws_cdk import App, Stack, Tags
app = App();
the_best_stack = Stack(app, 'MarketingSystem')
# Add a tag to all constructs in the stack
Tags.of(the_best_stack).add("StackType", "TheBest")
# Remove the tag from all resources except subnet resources
Tags.of(the_best_stack).remove("StackType",
exclude_resource_types=["AWS::EC2::Subnet"])
```
```
import software.amazon.awscdk.App;
import software.amazon.awscdk.Tags;
// Add a tag to all constructs in the stack
Tags.of(theBestStack).add("StackType", "TheBest");
// Remove the tag from all resources except subnet resources
Tags.of(theBestStack).remove("StackType", TagProps.builder()
.excludeResourceTypes(Arrays.asList("AWS::EC2::Subnet"))
.build());
```
```
using Amazon.CDK;
var app = new App();
var theBestStack = new Stack(app, 'MarketingSystem');
// Add a tag to all constructs in the stack
Tags.Of(theBestStack).Add("StackType", "TheBest");
// Remove the tag from all resources except subnet resources
Tags.Of(theBestStack).Remove("StackType", new TagProps
{
ExcludeResourceTypes = ["AWS::EC2::Subnet"]
});
```
```
import "github.com/aws/aws-cdk-go/awscdk/v2"
app := awscdk.NewApp(nil)
theBestStack := awscdk.NewStack(app, jsii.String("MarketingSystem"), &awscdk.StackProps{})
// Add a tag to all constructs in the stack
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{})
// Remove the tag from all resources except subnet resources
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{
ExcludeResourceTypes: &[]*string{jsii.String("AWS::EC2::Subnet")},
})
```
The following code achieves the same result. Consider which approach (inclusion or exclusion) makes your intent clearer.
**Example**
```
Tags.of(theBestStack).add('StackType', 'TheBest',
{ includeResourceTypes: ['AWS::EC2::Subnet']});
```
```
Tags.of(theBestStack).add('StackType', 'TheBest',
{ includeResourceTypes: ['AWS::EC2::Subnet']});
```
```
Tags.of(the_best_stack).add("StackType", "TheBest",
include_resource_types=["AWS::EC2::Subnet"])
```
```
Tags.of(theBestStack).add("StackType", "TheBest", TagProps.builder()
.includeResourceTypes(Arrays.asList("AWS::EC2::Subnet"))
.build());
```
```
Tags.Of(theBestStack).Add("StackType", "TheBest", new TagProps {
IncludeResourceTypes = ["AWS::EC2::Subnet"]
});
```
```
awscdk.Tags_Of(theBestStack).Add(jsii.String("StackType"), jsii.String("TheBest"), &awscdk.TagProps{
IncludeResourceTypes: &[]*string{jsii.String("AWS::EC2::Subnet")},
})
```
## Tagging single constructs
`Tags.of(scope).add(key, value)` is the standard way to add tags to constructs in the AWS CDK. Its tree-walking behavior, which recursively tags all taggable resources under the given scope, is almost always what you want. Sometimes, however, you need to tag a specific, arbitrary construct (or constructs).
One such case involves applying tags whose value is derived from some property of the construct being tagged. The standard tagging approach recursively applies the same key and value to all matching resources in the scope. However, here the value could be different for each tagged construct.
Tags are implemented using [aspects](aspects.md), and the CDK calls the tag’s `visit()` method for each construct under the scope you specified using `Tags.of(scope)`. We can call `Tag.visit()` directly to apply a tag to a single construct.
**Example**
```
new cdk.Tag(key, value).visit(scope);
```
```
new cdk.Tag(key, value).visit(scope);
```
```
cdk.Tag(key, value).visit(scope)
```
```
Tag.Builder.create(key, value).build().visit(scope);
```
```
new Tag(key, value).Visit(scope);
```
```
awscdk.NewTag(key, value, &awscdk.TagProps{}).Visit(scope)
```
You can tag all constructs under a scope but let the values of the tags derive from properties of each construct. To do so, write an aspect and apply the tag in the aspect’s `visit()` method as shown in the preceding example. Then, add the aspect to the desired scope using `Aspects.of(scope).add(aspect)`.
The following example applies a tag to each resource in a stack containing the resource’s path.
**Example**
```
class PathTagger implements cdk.IAspect {
visit(node: IConstruct) {
new cdk.Tag("aws-cdk-path", node.node.path).visit(node);
}
}
stack = new MyStack(app);
cdk.Aspects.of(stack).add(new PathTagger())
```
```
class PathTagger {
visit(node) {
new cdk.Tag("aws-cdk-path", node.node.path).visit(node);
}
}
stack = new MyStack(app);
cdk.Aspects.of(stack).add(new PathTagger())
```
```
@jsii.implements(cdk.IAspect)
class PathTagger:
def visit(self, node: IConstruct):
cdk.Tag("aws-cdk-path", node.node.path).visit(node)
stack = MyStack(app)
cdk.Aspects.of(stack).add(PathTagger())
```
```
final class PathTagger implements IAspect {
public void visit(IConstruct node) {
Tag.Builder.create("aws-cdk-path", node.getNode().getPath()).build().visit(node);
}
}
stack stack = new MyStack(app);
Aspects.of(stack).add(new PathTagger());
```
```
public class PathTagger : IAspect
{
public void Visit(IConstruct node)
{
new Tag("aws-cdk-path", node.Node.Path).Visit(node);
}
}
var stack = new MyStack(app);
Aspects.Of(stack).Add(new PathTagger);
```
**Tip**
The logic of conditional tagging, including priorities, resource types, and so on, is built into the `Tag` class. You can use these features when applying tags to arbitrary resources; the tag is not applied if the conditions aren’t met. Also, the `Tag` class only tags taggable resources, so you don’t need to test whether a construct is taggable before applying a tag.
# Assets and the AWS CDK
Assets are local files, directories, or Docker images that can be bundled into AWS CDK libraries and apps. For example, an asset might be a directory that contains the handler code for an AWS Lambda function. Assets can represent any artifact that the app needs to operate.
The following tutorial video provides a comprehensive overview of CDK assets, and explains how you can use them in your infrastructure as code (IaC).
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/jHNtXQmkKfw?rel=0)
You add assets through APIs that are exposed by specific AWS constructs. For example, when you define a [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html) construct, the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html#code](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html#code) property lets you pass an [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options) (directory). `Function` uses assets to bundle the contents of the directory and use it for the function’s code. Similarly, [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrassetdirectory-props](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrassetdirectory-props) uses a Docker image built from a local directory when defining an Amazon ECS task definition.
## Assets in detail
When you refer to an asset in your app, the [cloud assembly](deploy.md#deploy-how-synth-assemblies) that’s synthesized from your application includes metadata information with instructions for the AWS CDK CLI. The instructions include where to find the asset on the local disk and what type of bundling to perform based on the asset type, such as a directory to compress (zip) or a Docker image to build.
The AWS CDK generates a source hash for assets. This can be used at construction time to determine whether the contents of an asset have changed.
By default, the AWS CDK creates a copy of the asset in the cloud assembly directory, which defaults to `cdk.out`, under the source hash. This way, the cloud assembly is self-contained, so if it moved over to a different host for deployment, it can still be deployed. See [Cloud assemblies](deploy.md#deploy-how-synth-assemblies) for details.
When the AWS CDK deploys an app that references assets (either directly by the app code or through a library), the AWS CDK CLI first prepares and publishes the assets to an Amazon S3 bucket or Amazon ECR repository. (The S3 bucket or repository is created during bootstrapping.) Only then are the resources defined in the stack deployed.
This section describes the low-level APIs available in the framework.
## Asset types
The AWS CDK supports the following types of assets:
Amazon S3 assets
These are local files and directories that the AWS CDK uploads to Amazon S3.
Docker Image
These are Docker images that the AWS CDK uploads to Amazon ECR.
These asset types are explained in the following sections.
## Amazon S3 assets
You can define local files and directories as assets, and the AWS CDK packages and uploads them to Amazon S3 through the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html) module.
The following example defines a local directory asset and a file asset.
**Example**
```
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
// Archived and uploaded to Amazon S3 as a .zip file
const directoryAsset = new Asset(this, "SampleZippedDirAsset", {
path: path.join(__dirname, "sample-asset-directory")
});
// Uploaded to Amazon S3 as-is
const fileAsset = new Asset(this, 'SampleSingleFileAsset', {
path: path.join(__dirname, 'file-asset.txt')
});
```
```
const { Asset } = require('aws-cdk-lib/aws-s3-assets');
// Archived and uploaded to Amazon S3 as a .zip file
const directoryAsset = new Asset(this, "SampleZippedDirAsset", {
path: path.join(__dirname, "sample-asset-directory")
});
// Uploaded to Amazon S3 as-is
const fileAsset = new Asset(this, 'SampleSingleFileAsset', {
path: path.join(__dirname, 'file-asset.txt')
});
```
```
import os.path
dirname = os.path.dirname(__file__)
from aws_cdk.aws_s3_assets import Asset
# Archived and uploaded to Amazon S3 as a .zip file
directory_asset = Asset(self, "SampleZippedDirAsset",
path=os.path.join(dirname, "sample-asset-directory")
)
# Uploaded to Amazon S3 as-is
file_asset = Asset(self, 'SampleSingleFileAsset',
path=os.path.join(dirname, 'file-asset.txt')
)
```
```
import java.io.File;
import software.amazon.awscdk.services.s3.assets.Asset;
// Directory where app was started
File startDir = new File(System.getProperty("user.dir"));
// Archived and uploaded to Amazon S3 as a .zip file
Asset directoryAsset = Asset.Builder.create(this, "SampleZippedDirAsset")
.path(new File(startDir, "sample-asset-directory").toString()).build();
// Uploaded to Amazon S3 as-is
Asset fileAsset = Asset.Builder.create(this, "SampleSingleFileAsset")
.path(new File(startDir, "file-asset.txt").toString()).build();
```
```
using System.IO;
using Amazon.CDK.AWS.S3.Assets;
// Archived and uploaded to Amazon S3 as a .zip file
var directoryAsset = new Asset(this, "SampleZippedDirAsset", new AssetProps
{
Path = Path.Combine(Directory.GetCurrentDirectory(), "sample-asset-directory")
});
// Uploaded to Amazon S3 as-is
var fileAsset = new Asset(this, "SampleSingleFileAsset", new AssetProps
{
Path = Path.Combine(Directory.GetCurrentDirectory(), "file-asset.txt")
});
```
```
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
awss3assets.NewAsset(stack, jsii.String("SampleZippedDirAsset"), awss3assets.AssetProps{
Path: jsii.String(path.Join(dirName, "sample-asset-directory")),
})
awss3assets.NewAsset(stack, jsii.String("SampleSingleFileAsset"), awss3assets.AssetProps{
Path: jsii.String(path.Join(dirName, "file-asset.txt")),
})
```
In most cases, you don’t need to directly use the APIs in the `aws-s3-assets` module. Modules that support assets, such as `aws-lambda`, have convenience methods so that you can use assets. For Lambda functions, the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options) static method enables you to specify a directory or a .zip file in the local file system.
### Lambda function example
A common use case is creating Lambda functions with the handler code as an Amazon S3 asset.
The following example uses an Amazon S3 asset to define a Python handler in the local directory `handler`. It also creates a Lambda function with the local directory asset as the `code` property. Following is the Python code for the handler.
```
def lambda_handler(event, context):
message = 'Hello World!'
return {
'message': message
}
```
The code for the main AWS CDK app should look like the following.
**Example**
```
import * as cdk from 'aws-cdk-lib';
import { Constructs } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';
export class HelloAssetStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
new lambda.Function(this, 'myLambdaFunction', {
code: lambda.Code.fromAsset(path.join(__dirname, 'handler')),
runtime: lambda.Runtime.PYTHON_3_6,
handler: 'index.lambda_handler'
});
}
}
```
```
const cdk = require('aws-cdk-lib');
const lambda = require('aws-cdk-lib/aws-lambda');
const path = require('path');
class HelloAssetStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
new lambda.Function(this, 'myLambdaFunction', {
code: lambda.Code.fromAsset(path.join(__dirname, 'handler')),
runtime: lambda.Runtime.PYTHON_3_6,
handler: 'index.lambda_handler'
});
}
}
module.exports = { HelloAssetStack }
```
```
from aws_cdk import Stack
from constructs import Construct
from aws_cdk import aws_lambda as lambda_
import os.path
dirname = os.path.dirname(__file__)
class HelloAssetStack(Stack):
def __init__(self, scope: Construct, id: str, **kwargs):
super().__init__(scope, id, **kwargs)
lambda_.Function(self, 'myLambdaFunction',
code=lambda_.Code.from_asset(os.path.join(dirname, 'handler')),
runtime=lambda_.Runtime.PYTHON_3_6,
handler="index.lambda_handler")
```
```
import java.io.File;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.lambda.Function;
import software.amazon.awscdk.services.lambda.Runtime;
public class HelloAssetStack extends Stack {
public HelloAssetStack(final App scope, final String id) {
this(scope, id, null);
}
public HelloAssetStack(final App scope, final String id, final StackProps props) {
super(scope, id, props);
File startDir = new File(System.getProperty("user.dir"));
Function.Builder.create(this, "myLambdaFunction")
.code(Code.fromAsset(new File(startDir, "handler").toString()))
.runtime(Runtime.PYTHON_3_6)
.handler("index.lambda_handler").build();
}
}
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.Lambda;
using System.IO;
public class HelloAssetStack : Stack
{
public HelloAssetStack(Construct scope, string id, StackProps props) : base(scope, id, props)
{
new Function(this, "myLambdaFunction", new FunctionProps
{
Code = Code.FromAsset(Path.Combine(Directory.GetCurrentDirectory(), "handler")),
Runtime = Runtime.PYTHON_3_6,
Handler = "index.lambda_handler"
});
}
}
```
```
import (
"os"
"path"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
"github.com/aws/aws-cdk-go/awscdk/v2/awss3assets"
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
)
func HelloAssetStack(scope constructs.Construct, id string, props *HelloAssetStackProps) awscdk.Stack {
var sprops awscdk.StackProps
if props != nil {
sprops = props.StackProps
}
stack := awscdk.NewStack(scope, id, sprops)
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
awslambda.NewFunction(stack, jsii.String("myLambdaFunction"), awslambda.FunctionProps{
Code: awslambda.AssetCode_FromAsset(jsii.String(path.Join(dirName, "handler")), awss3assets.AssetOptions{}),
Runtime: awslambda.Runtime_PYTHON_3_6(),
Handler: jsii.String("index.lambda_handler"),
})
return stack
}
```
The `Function` method uses assets to bundle the contents of the directory and use it for the function’s code.
**Tip**
Java `.jar` files are ZIP files with a different extension. These are uploaded as-is to Amazon S3, but when deployed as a Lambda function, the files they contain are extracted, which you might not want. To avoid this, place the `.jar` file in a directory and specify that directory as the asset.
### Deploy-time attributes example
Amazon S3 asset types also expose [deploy-time attributes](resources.md#resources-attributes) that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command `cdk synth` displays asset properties as AWS CloudFormation parameters.
The following example uses deploy-time attributes to pass the location of an image asset into a Lambda function as environment variables. (The kind of file doesn’t matter; the PNG image used here is only an example.)
**Example**
```
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
import * as path from 'path';
const imageAsset = new Asset(this, "SampleAsset", {
path: path.join(__dirname, "images/my-image.png")
});
new lambda.Function(this, "myLambdaFunction", {
code: lambda.Code.asset(path.join(__dirname, "handler")),
runtime: lambda.Runtime.PYTHON_3_6,
handler: "index.lambda_handler",
environment: {
'S3_BUCKET_NAME': imageAsset.s3BucketName,
'S3_OBJECT_KEY': imageAsset.s3ObjectKey,
'S3_OBJECT_URL': imageAsset.s3ObjectUrl
}
});
```
```
const { Asset } = require('aws-cdk-lib/aws-s3-assets');
const path = require('path');
const imageAsset = new Asset(this, "SampleAsset", {
path: path.join(__dirname, "images/my-image.png")
});
new lambda.Function(this, "myLambdaFunction", {
code: lambda.Code.asset(path.join(__dirname, "handler")),
runtime: lambda.Runtime.PYTHON_3_6,
handler: "index.lambda_handler",
environment: {
'S3_BUCKET_NAME': imageAsset.s3BucketName,
'S3_OBJECT_KEY': imageAsset.s3ObjectKey,
'S3_OBJECT_URL': imageAsset.s3ObjectUrl
}
});
```
```
import os.path
import aws_cdk.aws_lambda as lambda_
from aws_cdk.aws_s3_assets import Asset
dirname = os.path.dirname(__file__)
image_asset = Asset(self, "SampleAsset",
path=os.path.join(dirname, "images/my-image.png"))
lambda_.Function(self, "myLambdaFunction",
code=lambda_.Code.asset(os.path.join(dirname, "handler")),
runtime=lambda_.Runtime.PYTHON_3_6,
handler="index.lambda_handler",
environment=dict(
S3_BUCKET_NAME=image_asset.s3_bucket_name,
S3_OBJECT_KEY=image_asset.s3_object_key,
S3_OBJECT_URL=image_asset.s3_object_url))
```
```
import java.io.File;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.lambda.Function;
import software.amazon.awscdk.services.lambda.Runtime;
import software.amazon.awscdk.services.s3.assets.Asset;
public class FunctionStack extends Stack {
public FunctionStack(final App scope, final String id, final StackProps props) {
super(scope, id, props);
File startDir = new File(System.getProperty("user.dir"));
Asset imageAsset = Asset.Builder.create(this, "SampleAsset")
.path(new File(startDir, "images/my-image.png").toString()).build())
Function.Builder.create(this, "myLambdaFunction")
.code(Code.fromAsset(new File(startDir, "handler").toString()))
.runtime(Runtime.PYTHON_3_6)
.handler("index.lambda_handler")
.environment(java.util.Map.of( // Java 9 or later
"S3_BUCKET_NAME", imageAsset.getS3BucketName(),
"S3_OBJECT_KEY", imageAsset.getS3ObjectKey(),
"S3_OBJECT_URL", imageAsset.getS3ObjectUrl()))
.build();
}
}
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.Lambda;
using Amazon.CDK.AWS.S3.Assets;
using System.IO;
using System.Collections.Generic;
var imageAsset = new Asset(this, "SampleAsset", new AssetProps
{
Path = Path.Combine(Directory.GetCurrentDirectory(), @"images\my-image.png")
});
new Function(this, "myLambdaFunction", new FunctionProps
{
Code = Code.FromAsset(Path.Combine(Directory.GetCurrentDirectory(), "handler")),
Runtime = Runtime.PYTHON_3_6,
Handler = "index.lambda_handler",
Environment = new Dictionarystring, string
{
["S3_BUCKET_NAME"] = imageAsset.S3BucketName,
["S3_OBJECT_KEY"] = imageAsset.S3ObjectKey,
["S3_OBJECT_URL"] = imageAsset.S3ObjectUrl
}
});
```
```
import (
"os"
"path"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
"github.com/aws/aws-cdk-go/awscdk/v2/awss3assets"
)
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
imageAsset := awss3assets.NewAsset(stack, jsii.String("SampleAsset"), awss3assets.AssetProps{
Path: jsii.String(path.Join(dirName, "images/my-image.png")),
})
awslambda.NewFunction(stack, jsii.String("myLambdaFunction"), awslambda.FunctionProps{
Code: awslambda.AssetCode_FromAsset(jsii.String(path.Join(dirName, "handler"))),
Runtime: awslambda.Runtime_PYTHON_3_6(),
Handler: jsii.String("index.lambda_handler"),
Environment: map[string]*string{
"S3_BUCKET_NAME": imageAsset.S3BucketName(),
"S3_OBJECT_KEY": imageAsset.S3ObjectKey(),
"S3_URL": imageAsset.S3ObjectUrl(),
},
})
```
### Permissions
If you use Amazon S3 assets directly through the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html) module, IAM roles, users, or groups, and you need to read assets in runtime, then grant those assets IAM permissions through the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.Asset.html#grantwbrreadgrantee](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.Asset.html#grantwbrreadgrantee) method.
The following example grants an IAM group read permissions on a file asset.
**Example**
```
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
import * as path from 'path';
const asset = new Asset(this, 'MyFile', {
path: path.join(__dirname, 'my-image.png')
});
const group = new iam.Group(this, 'MyUserGroup');
asset.grantRead(group);
```
```
const { Asset } = require('aws-cdk-lib/aws-s3-assets');
const path = require('path');
const asset = new Asset(this, 'MyFile', {
path: path.join(__dirname, 'my-image.png')
});
const group = new iam.Group(this, 'MyUserGroup');
asset.grantRead(group);
```
```
from aws_cdk.aws_s3_assets import Asset
import aws_cdk.aws_iam as iam
import os.path
dirname = os.path.dirname(__file__)
asset = Asset(self, "MyFile",
path=os.path.join(dirname, "my-image.png"))
group = iam.Group(self, "MyUserGroup")
asset.grant_read(group)
```
```
import java.io.File;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.iam.Group;
import software.amazon.awscdk.services.s3.assets.Asset;
public class GrantStack extends Stack {
public GrantStack(final App scope, final String id, final StackProps props) {
super(scope, id, props);
File startDir = new File(System.getProperty("user.dir"));
Asset asset = Asset.Builder.create(this, "SampleAsset")
.path(new File(startDir, "images/my-image.png").toString()).build();
Group group = new Group(this, "MyUserGroup");
asset.grantRead(group); }
}
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.IAM;
using Amazon.CDK.AWS.S3.Assets;
using System.IO;
var asset = new Asset(this, "MyFile", new AssetProps {
Path = Path.Combine(Path.Combine(Directory.GetCurrentDirectory(), @"images\my-image.png"))
});
var group = new Group(this, "MyUserGroup");
asset.GrantRead(group);
```
```
import (
"os"
"path"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awsiam"
"github.com/aws/aws-cdk-go/awscdk/v2/awss3assets"
)
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
asset := awss3assets.NewAsset(stack, jsii.String("MyFile"), awss3assets.AssetProps{
Path: jsii.String(path.Join(dirName, "my-image.png")),
})
group := awsiam.NewGroup(stack, jsii.String("MyUserGroup"), awsiam.GroupProps{})
asset.GrantRead(group)
```
## Docker image assets
The AWS CDK supports bundling local Docker images as assets through the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr_assets-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr_assets-readme.html) module.
The following example defines a Docker image that is built locally and pushed to Amazon ECR. Images are built from a local Docker context directory (with a Dockerfile) and uploaded to Amazon ECR by the AWS CDK CLI or your app’s CI/CD pipeline. The images can be naturally referenced in your AWS CDK app.
**Example**
```
import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});
```
```
const { DockerImageAsset } = require('aws-cdk-lib/aws-ecr-assets');
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});
```
```
from aws_cdk.aws_ecr_assets import DockerImageAsset
import os.path
dirname = os.path.dirname(__file__)
asset = DockerImageAsset(self, 'MyBuildImage',
directory=os.path.join(dirname, 'my-image'))
```
```
import software.amazon.awscdk.services.ecr.assets.DockerImageAsset;
File startDir = new File(System.getProperty("user.dir"));
DockerImageAsset asset = DockerImageAsset.Builder.create(this, "MyBuildImage")
.directory(new File(startDir, "my-image").toString()).build();
```
```
using System.IO;
using Amazon.CDK.AWS.ECR.Assets;
var asset = new DockerImageAsset(this, "MyBuildImage", new DockerImageAssetProps
{
Directory = Path.Combine(Directory.GetCurrentDirectory(), "my-image")
});
```
```
import (
"os"
"path"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awsecrassets"
)
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), awsecrassets.DockerImageAssetProps{
Directory: jsii.String(path.Join(dirName, "my-image")),
})
```
The `my-image` directory must include a Dockerfile. The AWS CDK CLI builds a Docker image from `my-image`, pushes it to an Amazon ECR repository, and specifies the name of the repository as an AWS CloudFormation parameter to your stack. Docker image asset types expose [deploy-time attributes](resources.md#resources-attributes) that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command `cdk synth` displays asset properties as AWS CloudFormation parameters.
### Amazon ECS task definition example
A common use case is to create an Amazon ECS [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.TaskDefinition.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.TaskDefinition.html) to run Docker containers. The following example specifies the location of a Docker image asset that the AWS CDK builds locally and pushes to Amazon ECR.
**Example**
```
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ecr_assets from 'aws-cdk-lib/aws-ecr-assets';
import * as path from 'path';
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
const asset = new ecr_assets.DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromDockerImageAsset(asset)
});
```
```
const ecs = require('aws-cdk-lib/aws-ecs');
const ecr_assets = require('aws-cdk-lib/aws-ecr-assets');
const path = require('path');
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
const asset = new ecr_assets.DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromDockerImageAsset(asset)
});
```
```
import aws_cdk.aws_ecs as ecs
import aws_cdk.aws_ecr_assets as ecr_assets
import os.path
dirname = os.path.dirname(__file__)
task_definition = ecs.FargateTaskDefinition(self, "TaskDef",
memory_limit_mib=1024,
cpu=512)
asset = ecr_assets.DockerImageAsset(self, 'MyBuildImage',
directory=os.path.join(dirname, 'my-image'))
task_definition.add_container("my-other-container",
image=ecs.ContainerImage.from_docker_image_asset(asset))
```
```
import java.io.File;
import software.amazon.awscdk.services.ecs.FargateTaskDefinition;
import software.amazon.awscdk.services.ecs.ContainerDefinitionOptions;
import software.amazon.awscdk.services.ecs.ContainerImage;
import software.amazon.awscdk.services.ecr.assets.DockerImageAsset;
File startDir = new File(System.getProperty("user.dir"));
FargateTaskDefinition taskDefinition = FargateTaskDefinition.Builder.create(
this, "TaskDef").memoryLimitMiB(1024).cpu(512).build();
DockerImageAsset asset = DockerImageAsset.Builder.create(this, "MyBuildImage")
.directory(new File(startDir, "my-image").toString()).build();
taskDefinition.addContainer("my-other-container",
ContainerDefinitionOptions.builder()
.image(ContainerImage.fromDockerImageAsset(asset))
.build();
)
```
```
using System.IO;
using Amazon.CDK.AWS.ECS;
using Amazon.CDK.AWS.Ecr.Assets;
var taskDefinition = new FargateTaskDefinition(this, "TaskDef", new FargateTaskDefinitionProps
{
MemoryLimitMiB = 1024,
Cpu = 512
});
var asset = new DockerImageAsset(this, "MyBuildImage", new DockerImageAssetProps
{
Directory = Path.Combine(Directory.GetCurrentDirectory(), "my-image")
});
taskDefinition.AddContainer("my-other-container", new ContainerDefinitionOptions
{
Image = ContainerImage.FromDockerImageAsset(asset)
});
```
```
import (
"os"
"path"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awsecrassets"
"github.com/aws/aws-cdk-go/awscdk/v2/awsecs"
)
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
taskDefinition := awsecs.NewTaskDefinition(stack, jsii.String("TaskDef"), awsecs.TaskDefinitionProps{
MemoryMiB: jsii.String("1024"),
Cpu: jsii.String("512"),
})
asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), awsecrassets.DockerImageAssetProps{
Directory: jsii.String(path.Join(dirName, "my-image")),
})
taskDefinition.AddContainer(jsii.String("MyOtherContainer"), awsecs.ContainerDefinitionOptions{
Image: awsecs.ContainerImage_FromDockerImageAsset(asset),
})
```
### Deploy-time attributes example
The following example shows how to use the deploy-time attributes `repository` and `imageUri` to create an Amazon ECS task definition with the AWS Fargate launch type. Note that the Amazon ECR repo lookup requires the image’s tag, not its URI, so we snip it from the end of the asset’s URI.
**Example**
```
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as path from 'path';
import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';
const asset = new DockerImageAsset(this, 'my-image', {
directory: path.join(__dirname, "..", "demo-image")
});
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromEcrRepository(asset.repository, asset.imageUri.split(":").pop())
});
```
```
const ecs = require('aws-cdk-lib/aws-ecs');
const path = require('path');
const { DockerImageAsset } = require('aws-cdk-lib/aws-ecr-assets');
const asset = new DockerImageAsset(this, 'my-image', {
directory: path.join(__dirname, "..", "demo-image")
});
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromEcrRepository(asset.repository, asset.imageUri.split(":").pop())
});
```
```
import aws_cdk.aws_ecs as ecs
from aws_cdk.aws_ecr_assets import DockerImageAsset
import os.path
dirname = os.path.dirname(__file__)
asset = DockerImageAsset(self, 'my-image',
directory=os.path.join(dirname, "..", "demo-image"))
task_definition = ecs.FargateTaskDefinition(self, "TaskDef",
memory_limit_mib=1024, cpu=512)
task_definition.add_container("my-other-container",
image=ecs.ContainerImage.from_ecr_repository(
asset.repository, asset.image_uri.rpartition(":")[-1]))
```
```
import java.io.File;
import software.amazon.awscdk.services.ecr.assets.DockerImageAsset;
import software.amazon.awscdk.services.ecs.FargateTaskDefinition;
import software.amazon.awscdk.services.ecs.ContainerDefinitionOptions;
import software.amazon.awscdk.services.ecs.ContainerImage;
File startDir = new File(System.getProperty("user.dir"));
DockerImageAsset asset = DockerImageAsset.Builder.create(this, "my-image")
.directory(new File(startDir, "demo-image").toString()).build();
FargateTaskDefinition taskDefinition = FargateTaskDefinition.Builder.create(
this, "TaskDef").memoryLimitMiB(1024).cpu(512).build();
// extract the tag from the asset's image URI for use in ECR repo lookup
String imageUri = asset.getImageUri();
String imageTag = imageUri.substring(imageUri.lastIndexOf(":") + 1);
taskDefinition.addContainer("my-other-container",
ContainerDefinitionOptions.builder().image(ContainerImage.fromEcrRepository(
asset.getRepository(), imageTag)).build());
```
```
using System.IO;
using Amazon.CDK.AWS.ECS;
using Amazon.CDK.AWS.ECR.Assets;
var asset = new DockerImageAsset(this, "my-image", new DockerImageAssetProps {
Directory = Path.Combine(Directory.GetCurrentDirectory(), "demo-image")
});
var taskDefinition = new FargateTaskDefinition(this, "TaskDef", new FargateTaskDefinitionProps
{
MemoryLimitMiB = 1024,
Cpu = 512
});
taskDefinition.AddContainer("my-other-container", new ContainerDefinitionOptions
{
Image = ContainerImage.FromEcrRepository(asset.Repository, asset.ImageUri.Split(":").Last())
});
```
```
import (
"os"
"path"
"github.com/aws/aws-cdk-go/awscdk/v2"
"github.com/aws/aws-cdk-go/awscdk/v2/awsecrassets"
"github.com/aws/aws-cdk-go/awscdk/v2/awsecs"
)
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyImage"), awsecrassets.DockerImageAssetProps{
Directory: jsii.String(path.Join(dirName, "demo-image")),
})
taskDefinition := awsecs.NewFargateTaskDefinition(stack, jsii.String("TaskDef"), awsecs.FargateTaskDefinitionProps{
MemoryLimitMiB: jsii.Number(1024),
Cpu: jsii.Number(512),
})
taskDefinition.AddContainer(jsii.String("MyOtherContainer"), awsecs.ContainerDefinitionOptions{
Image: awsecs.ContainerImage_FromEcrRepository(asset.Repository(), asset.ImageTag()),
})
```
### Build arguments example
You can provide customized build arguments for the Docker build step through the `buildArgs` (Python: `build_args`) property option when the AWS CDK CLI builds the image during deployment.
**Example**
```
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image'),
buildArgs: {
HTTP_PROXY: 'http://10.20.30.2:1234'
}
});
```
```
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image'),
buildArgs: {
HTTP_PROXY: 'http://10.20.30.2:1234'
}
});
```
```
asset = DockerImageAsset(self, "MyBuildImage",
directory=os.path.join(dirname, "my-image"),
build_args=dict(HTTP_PROXY="http://10.20.30.2:1234"))
```
```
DockerImageAsset asset = DockerImageAsset.Builder.create(this, "my-image"),
.directory(new File(startDir, "my-image").toString())
.buildArgs(java.util.Map.of( // Java 9 or later
"HTTP_PROXY", "http://10.20.30.2:1234"))
.build();
```
```
var asset = new DockerImageAsset(this, "MyBuildImage", new DockerImageAssetProps {
Directory = Path.Combine(Directory.GetCurrentDirectory(), "my-image"),
BuildArgs = new Dictionarystring, string
{
["HTTP_PROXY"] = "http://10.20.30.2:1234"
}
});
```
```
dirName, err := os.Getwd()
if err != nil {
panic(err)
}
asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), awsecrassets.DockerImageAssetProps{
Directory: jsii.String(path.Join(dirName, "my-image")),
BuildArgs: map[string]*string{
"HTTP_PROXY": jsii.String("http://10.20.30.2:1234"),
},
})
```
### Permissions
If you use a module that supports Docker image assets, such as [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs-readme.html), the AWS CDK manages permissions for you when you use assets directly or through [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrecrwbrrepositoryrepository-tag](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrecrwbrrepositoryrepository-tag) (Python: `from_ecr_repository`). If you use Docker image assets directly, make sure that the consuming principal has permissions to pull the image.
In most cases, you should use [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#grantwbrpullgrantee](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#grantwbrpullgrantee) method (Python: `grant_pull`). This modifies the IAM policy of the principal to enable it to pull images from this repository. If the principal that is pulling the image is not in the same account, or if it’s an AWS service that doesn’t assume a role in your account (such as AWS CodeBuild), you must grant pull permissions on the resource policy and not on the principal’s policy. Use the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#addwbrtowbrresourcewbrpolicystatement](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#addwbrtowbrresourcewbrpolicystatement) method (Python: `add_to_resource_policy`) to grant the appropriate principal permissions.
## AWS CloudFormation resource metadata
**Note**
This section is relevant only for construct authors. In certain situations, tools need to know that a certain CFN resource is using a local asset. For example, you can use the AWS SAM CLI to invoke Lambda functions locally for debugging purposes. See [AWS SAM integration](tools.md#sam) for details.
To enable such use cases, external tools consult a set of metadata entries on AWS CloudFormation resources:
+ `aws:asset:path` – Points to the local path of the asset.
+ `aws:asset:property` – The name of the resource property where the asset is used.
Using these two metadata entries, tools can identify that assets are used by a certain resource, and enable advanced local experiences.
To add these metadata entries to a resource, use the `asset.addResourceMetadata` (Python: `add_resource_metadata`) method.
# Permissions and the AWS CDK
The AWS Construct Library uses a few common, widely implemented idioms to manage access and permissions. The IAM module provides you with the tools you need to use these idioms.
AWS CDK uses AWS CloudFormation to deploy changes. Every deployment involves an actor (either a developer, or an automated system) that starts a AWS CloudFormation deployment. In the course of doing this, the actor will assume one or more IAM Identities (user or roles) and optionally pass a role to AWS CloudFormation.
If you use AWS IAM Identity Center to authenticate as a user, then the single sign-on provider supplies short-lived session credentials that authorize you to act as a pre-defined IAM role. To learn how the AWS CDK obtains AWS credentials from IAM Identity Center authentication, see [Understand IAM Identity Center authentication](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) in the * AWS SDKs and Tools Reference Guide*.
## Principals
An IAM principal is an authenticated AWS entity representing a user, service, or application that can call AWS APIs. The AWS Construct Library supports specifying principals in several flexible ways to grant them access your AWS resources.
In security contexts, the term "principal" refers specifically to authenticated entities such as users. Objects like groups and roles do not *represent* users (and other authenticated entities) but rather *identify* them indirectly for the purpose of granting permissions.
For example, if you create an IAM group, you can grant the group (and thus its members) write access to an Amazon RDS table. However, the group itself is not a principal because it doesn’t represent a single entity (also, you cannot log in to a group).
In the CDK’s IAM library, classes that directly or indirectly identify principals implement the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) interface, allowing these objects to be used interchangeably in access policies. However, not all of them are principals in the security sense. These objects include:
1. IAM resources such as [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html), [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html), and [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html)
1. Service principals (`new iam.[ServicePrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ServicePrincipal.html)('service.amazonaws.com')`)
1. Federated principals (`new iam.[FederatedPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.FederatedPrincipal.html)('cognito-identity.amazonaws.com')`)
1. Account principals (`new iam.[AccountPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.AccountPrincipal.html)('0123456789012')`)
1. Canonical user principals (`new iam.[CanonicalUserPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.CanonicalUserPrincipal.html)('79a59d[…]7ef2be')`)
1. AWS Organizations principals (`new iam.[OrganizationPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.OrganizationPrincipal.html)('org-id')`)
1. Arbitrary ARN principals (`new iam.[ArnPrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ArnPrincipal.html)(res.arn)`)
1. An `iam.[CompositePrincipal](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.CompositePrincipal.html)(principal1, principal2, …)` to trust multiple principals
## Grants
Many constructs represent resources that can be accessed, such as an Amazon S3 bucket or an Amazon DynamoDB table. For those, you can grant access to another entity. There are two ways to do this, depending on the particular construct: using its corresponding Grants class (for instance, `BucketGrants` for Amazon S3 buckets) or using methods in the construct itself, which have names starting with **grant**. The former is preferred because they can be used to grant access to both L1 and L2 resources in the same way. To create an instance of a Grants class, use its factory method:
**Example**
```
BucketGrants.fromBucket(bucket); // bucket can be either a Bucket (L2) or a CfnBucket (L1)
```
```
BucketGrants.fromBucket(bucket); // bucket can be either a Bucket (L2) or a CfnBucket (L1)
```
```
BucketGrants.from_bucket(bucket) # bucket can be either a Bucket (L2) or a CfnBucket (L1)
```
```
BucketGrants.fromBucket(bucket); // bucket can be either a Bucket (L2) or a CfnBucket (L1)
```
```
BucketGrants.FromBucket(bucket); // bucket can be either a Bucket (L2) or a CfnBucket (L1)
```
Grants classes provide methods to give specific permissions to access their resource. For example, `BucketGrants` has methods `read` and `readWrite` (Python: `read`, `read_write`) to enable read and read/write access, respectively, from an entity to the bucket. The entity doesn’t have to know exactly which Amazon S3 IAM permissions are required to perform these operations.
The first argument of the methods in a Grants class (or the **grant** methods in the resources themselves) is always of type [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IGrantable.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IGrantable.html). This interface represents entities that can be granted permissions. That is, it represents resources with roles, such as the IAM objects [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html), [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html), and [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html).
Other entities can also be granted permissions. For example, later in this topic, we show how to grant a CodeBuild project access to an Amazon S3 bucket. Generally, the associated role is obtained via a `role` property on the entity being granted access.
Resources that use execution roles, such as [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html), also implement `IGrantable`, so you can grant them access directly instead of granting access to their role. For example, if `bucket` is an Amazon S3 bucket, and `function` is a Lambda function, the following code grants the function read access to the bucket.
For convenience, L2 constructs also offer a `grants` property that returns an instance of the corresponding Grants class.
**Example**
```
bucket.grants.read(function);
```
```
bucket.grants.read(function);
```
```
bucket.grants.read(function)
```
```
bucket.getGrants().read(function);
```
```
bucket.Grants.Read(function);
```
Sometimes permissions must be applied while your stack is being deployed. One such case is when you grant an AWS CloudFormation custom resource access to some other resource. The custom resource will be invoked during deployment, so it must have the specified permissions at deployment time.
Another case is when a service verifies that the role you pass to it has the right policies applied. (A number of AWS services do this to make sure that you didn’t forget to set the policies.) In those cases, the deployment might fail if the permissions are applied too late.
To force the grant’s permissions to be applied before another resource is created, you can add a dependency on the grant itself, as shown here. Though the return value of grant methods is commonly discarded, every grant method in fact returns an `iam.Grant` object.
**Example**
```
const grant = bucket.grants.read(lambda);
const custom = new CustomResource(...);
custom.node.addDependency(grant);
```
```
const grant = bucket.grants.read(lambda);
const custom = new CustomResource(...);
custom.node.addDependency(grant);
```
```
grant = bucket.grants.read(function)
custom = CustomResource(...)
custom.node.add_dependency(grant)
```
```
Grant grant = bucket.getGrants().read(function);
CustomResource custom = new CustomResource(...);
custom.node.addDependency(grant);
```
```
var grant = bucket.Grants.Read(function);
var custom = new CustomResource(...);
custom.node.AddDependency(grant);
```
## Roles
The IAM package contains a [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html) construct that represents IAM roles. The following code creates a new role, trusting the Amazon EC2 service.
**Example**
```
import * as iam from 'aws-cdk-lib/aws-iam';
const role = new iam.Role(this, 'Role', {
assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'), // required
});
```
```
const iam = require('aws-cdk-lib/aws-iam');
const role = new iam.Role(this, 'Role', {
assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com') // required
});
```
```
import aws_cdk.aws_iam as iam
role = iam.Role(self, "Role",
assumed_by=iam.ServicePrincipal("ec2.amazonaws.com")) # required
```
```
import software.amazon.awscdk.services.iam.Role;
import software.amazon.awscdk.services.iam.ServicePrincipal;
Role role = Role.Builder.create(this, "Role")
.assumedBy(new ServicePrincipal("ec2.amazonaws.com")).build();
```
```
using Amazon.CDK.AWS.IAM;
var role = new Role(this, "Role", new RoleProps
{
AssumedBy = new ServicePrincipal("ec2.amazonaws.com"), // required
});
```
You can add permissions to a role by calling the role’s [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement) method (Python: `add_to_policy`), passing in a [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) that defines the rule to be added. The statement is added to the role’s default policy; if it has none, one is created.
The following example adds a `Deny` policy statement to the role for the actions `ec2:SomeAction` and `s3:AnotherAction` on the resources `bucket` and `otherRole` (Python: `other_role`), under the condition that the authorized service is AWS CodeBuild.
**Example**
```
role.addToPolicy(new iam.PolicyStatement({
effect: iam.Effect.DENY,
resources: [bucket.bucketArn, otherRole.roleArn],
actions: ['ec2:SomeAction', 's3:AnotherAction'],
conditions: {StringEquals: {
'ec2:AuthorizedService': 'codebuild.amazonaws.com',
}}}));
```
```
role.addToPolicy(new iam.PolicyStatement({
effect: iam.Effect.DENY,
resources: [bucket.bucketArn, otherRole.roleArn],
actions: ['ec2:SomeAction', 's3:AnotherAction'],
conditions: {StringEquals: {
'ec2:AuthorizedService': 'codebuild.amazonaws.com'
}}}));
```
```
role.add_to_policy(iam.PolicyStatement(
effect=iam.Effect.DENY,
resources=[bucket.bucket_arn, other_role.role_arn],
actions=["ec2:SomeAction", "s3:AnotherAction"],
conditions={"StringEquals": {
"ec2:AuthorizedService": "codebuild.amazonaws.com"}}
))
```
```
role.addToPolicy(PolicyStatement.Builder.create()
.effect(Effect.DENY)
.resources(Arrays.asList(bucket.getBucketArn(), otherRole.getRoleArn()))
.actions(Arrays.asList("ec2:SomeAction", "s3:AnotherAction"))
.conditions(java.util.Map.of( // Map.of requires Java 9 or later
"StringEquals", java.util.Map.of(
"ec2:AuthorizedService", "codebuild.amazonaws.com")))
.build());
```
```
role.AddToPolicy(new PolicyStatement(new PolicyStatementProps
{
Effect = Effect.DENY,
Resources = new string[] { bucket.BucketArn, otherRole.RoleArn },
Actions = new string[] { "ec2:SomeAction", "s3:AnotherAction" },
Conditions = new Dictionary
{
["StringEquals"] = new Dictionary
{
["ec2:AuthorizedService"] = "codebuild.amazonaws.com"
}
}
}));
```
In the preceding example, we’ve created a new [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) inline with the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#addwbrtowbrpolicystatement) (Python: `add_to_policy`) call. You can also pass in an existing policy statement or one you’ve modified. The [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) object has [numerous methods](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html#methods) for adding principals, resources, conditions, and actions.
If you’re using a construct that requires a role to function correctly, you can do one of the following:
+ Pass in an existing role when instantiating the construct object.
+ Let the construct create a new role for you, trusting the appropriate service principal. The following example uses such a construct: a CodeBuild project.
**Example**
```
import * as codebuild from 'aws-cdk-lib/aws-codebuild';
// imagine roleOrUndefined is a function that might return a Role object
// under some conditions, and undefined under other conditions
const someRole: iam.IRole | undefined = roleOrUndefined();
const project = new codebuild.Project(this, 'Project', {
// if someRole is undefined, the Project creates a new default role,
// trusting the codebuild.amazonaws.com service principal
role: someRole,
});
```
```
const codebuild = require('aws-cdk-lib/aws-codebuild');
// imagine roleOrUndefined is a function that might return a Role object
// under some conditions, and undefined under other conditions
const someRole = roleOrUndefined();
const project = new codebuild.Project(this, 'Project', {
// if someRole is undefined, the Project creates a new default role,
// trusting the codebuild.amazonaws.com service principal
role: someRole
});
```
```
import aws_cdk.aws_codebuild as codebuild
# imagine role_or_none is a function that might return a Role object
# under some conditions, and None under other conditions
some_role = role_or_none();
project = codebuild.Project(self, "Project",
# if role is None, the Project creates a new default role,
# trusting the codebuild.amazonaws.com service principal
role=some_role)
```
```
import software.amazon.awscdk.services.iam.Role;
import software.amazon.awscdk.services.codebuild.Project;
// imagine roleOrNull is a function that might return a Role object
// under some conditions, and null under other conditions
Role someRole = roleOrNull();
// if someRole is null, the Project creates a new default role,
// trusting the codebuild.amazonaws.com service principal
Project project = Project.Builder.create(this, "Project")
.role(someRole).build();
```
```
using Amazon.CDK.AWS.CodeBuild;
// imagine roleOrNull is a function that might return a Role object
// under some conditions, and null under other conditions
var someRole = roleOrNull();
// if someRole is null, the Project creates a new default role,
// trusting the codebuild.amazonaws.com service principal
var project = new Project(this, "Project", new ProjectProps
{
Role = someRole
});
```
Once the object is created, the role (whether the role passed in or the default one created by the construct) is available as the property `role`. However, this property is not available on external resources. Therefore, these constructs have an `addToRolePolicy` (Python: `add_to_role_policy`) method.
The method does nothing if the construct is an external resource, and it calls the `addToPolicy` (Python: `add_to_policy`) method of the `role` property otherwise. This saves you the trouble of handling the undefined case explicitly.
The following example demonstrates:
**Example**
```
// project is imported into the CDK application
const project = codebuild.Project.fromProjectName(this, 'Project', 'ProjectName');
// project is imported, so project.role is undefined, and this call has no effect
project.addToRolePolicy(new iam.PolicyStatement({
effect: iam.Effect.ALLOW, // ... and so on defining the policy
}));
```
```
// project is imported into the CDK application
const project = codebuild.Project.fromProjectName(this, 'Project', 'ProjectName');
// project is imported, so project.role is undefined, and this call has no effect
project.addToRolePolicy(new iam.PolicyStatement({
effect: iam.Effect.ALLOW // ... and so on defining the policy
}));
```
```
# project is imported into the CDK application
project = codebuild.Project.from_project_name(self, 'Project', 'ProjectName')
# project is imported, so project.role is undefined, and this call has no effect
project.add_to_role_policy(iam.PolicyStatement(
effect=iam.Effect.ALLOW, # ... and so on defining the policy
)
)
```
```
// project is imported into the CDK application
Project project = Project.fromProjectName(this, "Project", "ProjectName");
// project is imported, so project.getRole() is null, and this call has no effect
project.addToRolePolicy(PolicyStatement.Builder.create()
.effect(Effect.ALLOW) // .. and so on defining the policy
.build();
)
```
```
// project is imported into the CDK application
var project = Project.FromProjectName(this, "Project", "ProjectName");
// project is imported, so project.role is null, and this call has no effect
project.AddToRolePolicy(new PolicyStatement(new PolicyStatementProps
{
Effect = Effect.ALLOW, // ... and so on defining the policy
}));
```
## Resource policies
A few resources in AWS, such as Amazon S3 buckets and IAM roles, also have a resource policy. These constructs have an `addToResourcePolicy` method (Python: `add_to_resource_policy`), which takes a [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyStatement.html) as its argument. Every policy statement added to a resource policy must specify at least one principal.
In the following example, the [Amazon S3 bucket](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) `bucket` grants a role with the `s3:SomeAction` permission to itself.
**Example**
```
bucket.addToResourcePolicy(new iam.PolicyStatement({
effect: iam.Effect.ALLOW,
actions: ['s3:SomeAction'],
resources: [bucket.bucketArn],
principals: [role]
}));
```
```
bucket.addToResourcePolicy(new iam.PolicyStatement({
effect: iam.Effect.ALLOW,
actions: ['s3:SomeAction'],
resources: [bucket.bucketArn],
principals: [role]
}));
```
```
bucket.add_to_resource_policy(iam.PolicyStatement(
effect=iam.Effect.ALLOW,
actions=["s3:SomeAction"],
resources=[bucket.bucket_arn],
principals=role))
```
```
bucket.addToResourcePolicy(PolicyStatement.Builder.create()
.effect(Effect.ALLOW)
.actions(Arrays.asList("s3:SomeAction"))
.resources(Arrays.asList(bucket.getBucketArn()))
.principals(Arrays.asList(role))
.build());
```
```
bucket.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps
{
Effect = Effect.ALLOW,
Actions = new string[] { "s3:SomeAction" },
Resources = new string[] { bucket.BucketArn },
Principals = new IPrincipal[] { role }
}));
```
## Using external IAM objects
If you have defined an IAM user, principal, group, or role outside your AWS CDK app, you can use that IAM object in your AWS CDK app. To do so, create a reference to it using its ARN or its name. (Use the name for users, groups, and roles.) The returned reference can then be used to grant permissions or to construct policy statements as explained previously.
+ For users, call [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrarnscope-id-userarn](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrarnscope-id-userarn) or [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrnamescope-id-username](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.User.html#static-fromwbruserwbrnamescope-id-username). `User.fromUserAttributes()` is also available, but currently provides the same functionality as `User.fromUserArn()`.
+ For principals, instantiate an [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ArnPrincipal.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ArnPrincipal.html) object.
+ For groups, call [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrarnscope-id-grouparn](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrarnscope-id-grouparn) or [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrnamescope-id-groupname](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Group.html#static-fromwbrgroupwbrnamescope-id-groupname).
+ For roles, call [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrarnscope-id-rolearn-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrarnscope-id-rolearn-options) or [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrnamescope-id-rolename](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html#static-fromwbrrolewbrnamescope-id-rolename).
Policies (including managed policies) can be used in similar fashion using the following methods. You can use references to these objects anywhere an IAM policy is required.
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Policy.html#static-fromwbrpolicywbrnamescope-id-policyname](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Policy.html#static-fromwbrpolicywbrnamescope-id-policyname)
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrarnscope-id-managedpolicyarn](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrarnscope-id-managedpolicyarn)
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrnamescope-id-managedpolicyname](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrnamescope-id-managedpolicyname)
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrawswbrmanagedwbrpolicywbrnamemanagedpolicyname](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.ManagedPolicy.html#static-fromwbrawswbrmanagedwbrpolicywbrnamemanagedpolicyname)
**Note**
As with all references to external AWS resources, you cannot modify external IAM objects in your CDK app.
# Context values and the AWS CDK
Context values are key-value pairs that can be associated with an app, stack, or construct. They may be supplied to your app from a file (usually either `cdk.json` or `cdk.context.json` in your project directory) or on the command line.
The CDK Toolkit uses context to cache values retrieved from your AWS account during synthesis. Values include the Availability Zones in your account or the Amazon Machine Image (AMI) IDs currently available for Amazon EC2 instances. Because these values are provided by your AWS account, they can change between runs of your CDK application. This makes them a potential source of unintended change. The CDK Toolkit’s caching behavior "freezes" these values for your CDK app until you decide to accept the new values.
Imagine the following scenario without context caching. Let’s say you specified "latest Amazon Linux" as the AMI for your Amazon EC2 instances, and a new version of this AMI was released. Then, the next time you deployed your CDK stack, your already-deployed instances would be using the outdated ("wrong") AMI and would need to be upgraded. Upgrading would result in replacing all your existing instances with new ones, which would probably be unexpected and undesired.
Instead, the CDK records your account’s available AMIs in your project’s `cdk.context.json` file, and uses the stored value for future synthesis operations. This way, the list of AMIs is no longer a potential source of change. You can also be sure that your stacks will always synthesize to the same AWS CloudFormation templates.
Not all context values are cached values from your AWS environment. [AWS CDK feature flags](featureflags.md) are also context values. You can also create your own context values for use by your apps or constructs.
Context keys are strings. Values may be any type supported by JSON: numbers, strings, arrays, or objects.
**Tip**
If your constructs create their own context values, incorporate your library’s package name in its keys so they won’t conflict with other packages' context values.
Many context values are associated with a particular AWS environment, and a given CDK app can be deployed in more than one environment. The key for such values includes the AWS account and Region so that values from different environments do not conflict.
The following context key illustrates the format used by the AWS CDK, including the account and Region.
```
availability-zones:account=123456789012:region=eu-central-1
```
**Important**
Cached context values are managed by the AWS CDK and its constructs, including constructs you may write. Do not add or change cached context values by manually editing files. It can be useful, however, to review `cdk.context.json` occasionally to see what values are being cached. Context values that don’t represent cached values should be stored under the `context` key of `cdk.json`. This way, they won’t be cleared when cached values are cleared.
## Sources of context values
Context values can be provided to your AWS CDK app in six different ways:
+ Automatically from the current AWS account.
+ Through the `--context` option to the `cdk` command. (These values are always strings.)
+ In the project’s `cdk.context.json` file.
+ In the `context` key of the project’s `cdk.json` file.
+ In the `context` key of your `~/.cdk.json` file.
+ In your AWS CDK app using the `construct.node.setContext()` method.
The project file `cdk.context.json` is where the AWS CDK caches context values retrieved from your AWS account. This practice avoids unexpected changes to your deployments when, for example, a new Availability Zone is introduced. The AWS CDK does not write context data to any of the other files listed.
**Important**
Because they’re part of your application’s state, `cdk.json` and `cdk.context.json` must be committed to source control along with the rest of your app’s source code. Otherwise, deployments in other environments (for example, a CI pipeline) might produce inconsistent results.
Context values are scoped to the construct that created them; they are visible to child constructs, but not to parents or siblings. Context values that are set by the AWS CDK Toolkit (the `cdk` command) can be set automatically, from a file, or from the `--context` option. Context values from these sources are implicitly set on the `App` construct. Therefore, they’re visible to every construct in every stack in the app.
Your app can read a context value using the `construct.node.tryGetContext` method. If the requested entry isn’t found on the current construct or any of its parents, the result is `undefined`. (Alternatively, the result could be your language’s equivalent, such as `None` in Python.)
## Context methods
The AWS CDK supports several context methods that enable AWS CDK apps to obtain contextual information from the AWS environment. For example, you can get a list of Availability Zones that are available in a given AWS account and Region, using the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones) method.
The following are the context methods:
[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_route53.HostedZone.html#static-fromwbrlookupscope-id-query](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_route53.HostedZone.html#static-fromwbrlookupscope-id-query)
Gets the hosted zones in your account.
[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones)
Gets the supported Availability Zones.
[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ssm.StringParameter.html#static-valuewbrfromwbrlookupscope-parametername](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ssm.StringParameter.html#static-valuewbrfromwbrlookupscope-parametername)
Gets a value from the current Region’s Amazon EC2 Systems Manager Parameter Store.
[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#static-fromwbrlookupscope-id-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#static-fromwbrlookupscope-id-options)
Gets the existing Amazon Virtual Private Clouds in your accounts.
[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.LookupMachineImage.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.LookupMachineImage.html)
Looks up a machine image for use with a NAT instance in an Amazon Virtual Private Cloud.
If a required context value isn’t available, the AWS CDK app notifies the CDK Toolkit that the context information is missing. Next, the CLI queries the current AWS account for the information and stores the resulting context information in the `cdk.context.json` file. Then, it executes the AWS CDK app again with the context values.
## Viewing and managing context
Use the `cdk context` command to view and manage the information in your `cdk.context.json` file. To see this information, use the `cdk context` command without any options. The output should be something like the following.
```
Context found in cdk.json:
┌───┬─────────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┐
│ # │ Key │ Value │
├───┼─────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ 1 │ availability-zones:account=123456789012:region=eu-central-1 │ [ "eu-central-1a", "eu-central-1b", "eu-central-1c" ] │
├───┼─────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ 2 │ availability-zones:account=123456789012:region=eu-west-1 │ [ "eu-west-1a", "eu-west-1b", "eu-west-1c" ] │
└───┴─────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────┘
Run
cdk context --reset KEY_OR_NUMBER
to remove a context key. If it is a cached value, it will be refreshed on the next
cdk synth
.
```
To remove a context value, run `cdk context --reset`, specifying the value’s corresponding key or number. The following example removes the value that corresponds to the second key in the preceding example. This value represents the list of Availability Zones in the Europe (Ireland) Region.
```
cdk context --reset 2
```
```
Context value
availability-zones:account=123456789012:region=eu-west-1
reset. It will be refreshed on the next SDK synthesis run.
```
Therefore, if you want to update to the latest version of the Amazon Linux AMI, use the preceding example to do a controlled update of the context value and reset it. Then, synthesize and deploy your app again.
```
$ cdk synth
```
To clear all of the stored context values for your app, run `cdk context --clear`, as follows.
```
$ cdk context --clear
```
Only context values stored in `cdk.context.json` can be reset or cleared. The AWS CDK does not touch other context values. Therefore, to protect a context value from being reset using these commands, you might copy the value to `cdk.json`.
## AWS CDK Toolkit `--context` flag
Use the `--context` (`-c` for short) option to pass runtime context values to your CDK app during synthesis or deployment.
```
$ cdk synth --context key=value MyStack
```
To specify multiple context values, repeat the `--context` option any number of times, providing one key-value pair each time.
```
$ cdk synth --context key1=value1 --context key2=value2 MyStack
```
When synthesizing multiple stacks, the specified context values are passed to all stacks. To provide different context values to individual stacks, either use different keys for the values, or use multiple `cdk synth` or `cdk deploy` commands.
Context values passed from the command line are always strings. If a value is usually of some other type, your code must be prepared to convert or parse the value. You might have non-string context values provided in other ways (for example, in `cdk.context.json`). To make sure this kind of value works as expected, confirm that the value is a string before converting it.
## Example
Following is an example of using an existing Amazon VPC using AWS CDK context.
**Example**
```
import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import { Construct } from 'constructs';
export class ExistsVpcStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const vpcid = this.node.tryGetContext('vpcid');
const vpc = ec2.Vpc.fromLookup(this, 'VPC', {
vpcId: vpcid,
});
const pubsubnets = vpc.selectSubnets({subnetType: ec2.SubnetType.PUBLIC});
new cdk.CfnOutput(this, 'publicsubnets', {
value: pubsubnets.subnetIds.toString(),
});
}
}
```
```
const cdk = require('aws-cdk-lib');
const ec2 = require('aws-cdk-lib/aws-ec2');
class ExistsVpcStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
const vpcid = this.node.tryGetContext('vpcid');
const vpc = ec2.Vpc.fromLookup(this, 'VPC', {
vpcId: vpcid
});
const pubsubnets = vpc.selectSubnets({subnetType: ec2.SubnetType.PUBLIC});
new cdk.CfnOutput(this, 'publicsubnets', {
value: pubsubnets.subnetIds.toString()
});
}
}
module.exports = { ExistsVpcStack }
```
```
import aws_cdk as cdk
import aws_cdk.aws_ec2 as ec2
from constructs import Construct
class ExistsVpcStack(cdk.Stack):
def __init__(scope: Construct, id: str, **kwargs):
super().__init__(scope, id, **kwargs)
vpcid = self.node.try_get_context("vpcid")
vpc = ec2.Vpc.from_lookup(self, "VPC", vpc_id=vpcid)
pubsubnets = vpc.select_subnets(subnetType=ec2.SubnetType.PUBLIC)
cdk.CfnOutput(self, "publicsubnets",
value=pubsubnets.subnet_ids.to_string())
```
```
import software.amazon.awscdk.CfnOutput;
import software.amazon.awscdk.services.ec2.Vpc;
import software.amazon.awscdk.services.ec2.VpcLookupOptions;
import software.amazon.awscdk.services.ec2.SelectedSubnets;
import software.amazon.awscdk.services.ec2.SubnetSelection;
import software.amazon.awscdk.services.ec2.SubnetType;
import software.constructs.Construct;
public class ExistsVpcStack extends Stack {
public ExistsVpcStack(Construct context, String id) {
this(context, id, null);
}
public ExistsVpcStack(Construct context, String id, StackProps props) {
super(context, id, props);
String vpcId = (String)this.getNode().tryGetContext("vpcid");
Vpc vpc = (Vpc)Vpc.fromLookup(this, "VPC", VpcLookupOptions.builder()
.vpcId(vpcId).build());
SelectedSubnets pubSubNets = vpc.selectSubnets(SubnetSelection.builder()
.subnetType(SubnetType.PUBLIC).build());
CfnOutput.Builder.create(this, "publicsubnets")
.value(pubSubNets.getSubnetIds().toString()).build();
}
}
```
```
using Amazon.CDK;
using Amazon.CDK.AWS.EC2;
using Constructs;
class ExistsVpcStack : Stack
{
public ExistsVpcStack(Construct scope, string id, StackProps props) : base(scope, id, props)
{
var vpcId = (string)this.Node.TryGetContext("vpcid");
var vpc = Vpc.FromLookup(this, "VPC", new VpcLookupOptions
{
VpcId = vpcId
});
SelectedSubnets pubSubNets = vpc.SelectSubnets([new SubnetSelection
{
SubnetType = SubnetType.PUBLIC
}]);
new CfnOutput(this, "publicsubnets", new CfnOutputProps {
Value = pubSubNets.SubnetIds.ToString()
});
}
}
```
You can use `cdk diff` to see the effects of passing in a context value on the command line:
```
$ cdk diff -c vpcid=vpc-0cb9c31031d0d3e22
```
```
Stack ExistsvpcStack
Outputs
[+] Output publicsubnets publicsubnets: {"Value":"subnet-06e0ea7dd302d3e8f,subnet-01fc0acfb58f3128f"}
```
The resulting context values can be viewed as shown here.
```
$ cdk context -j
```
```
{
"vpc-provider:account=123456789012:filter.vpc-id=vpc-0cb9c31031d0d3e22:region=us-east-1": {
"vpcId": "vpc-0cb9c31031d0d3e22",
"availabilityZones": [
"us-east-1a",
"us-east-1b"
],
"privateSubnetIds": [
"subnet-03ecfc033225be285",
"subnet-0cded5da53180ebfa"
],
"privateSubnetNames": [
"Private"
],
"privateSubnetRouteTableIds": [
"rtb-0e955393ced0ada04",
"rtb-05602e7b9f310e5b0"
],
"publicSubnetIds": [
"subnet-06e0ea7dd302d3e8f",
"subnet-01fc0acfb58f3128f"
],
"publicSubnetNames": [
"Public"
],
"publicSubnetRouteTableIds": [
"rtb-00d1fdfd823c82289",
"rtb-04bb1969b42969bcb"
]
}
}
```
# AWS CDK feature flags
The AWS CDK uses *feature flags* to enable potentially breaking behaviors in a release. Flags are stored as [Context values and the AWS CDK](context.md) values in `cdk.json` (or `~/.cdk.json`). They are not removed by the `cdk context --reset` or `cdk context --clear` commands.
Feature flags are disabled by default. Existing projects that do not specify the flag will continue to work as before with later AWS CDK releases. New projects created using `cdk init` include flags enabling all features available in the release that created the project. Edit `cdk.json` to disable any flags for which you prefer the earlier behavior. You can also add flags to enable new behaviors after upgrading the AWS CDK.
A list of all current feature flags can be found on the AWS CDK GitHub repository in [FEATURE\$1FLAGS.md](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md). See the `CHANGELOG` in a given release for a description of any new feature flags added in that release.
## Reverting to v1 behavior
In CDK v2, the defaults for some feature flags have been changed with respect to v1. You can set these back to `false` to revert to specific AWS CDK v1 behavior. Use the `cdk diff` command to inspect the changes to your synthesized template to see if any of these flags are needed.
`@aws-cdk/core:newStyleStackSynthesis`
Use the new stack synthesis method, which assumes bootstrap resources with well-known names. Requires [modern bootstrapping](bootstrapping.md), but in turn allows CI/CD via [CDK Pipelines](cdk-pipeline.md) and cross-account deployments out of the box.
`@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId`
If your application uses multiple Amazon API Gateway API keys and associates them to usage plans.
`@aws-cdk/aws-rds:lowercaseDbIdentifier`
If your application uses Amazon RDS database instance or database clusters, and explicitly specifies the identifier for these.
`@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021`
If your application uses the TLS\$1V1\$12\$12019 security policy with Amazon CloudFront distributions. CDK v2 uses security policy TLSv1.2\$12021 by default.
`@aws-cdk/core:stackRelativeExports`
If your application uses multiple stacks and you refer to resources from one stack in another, this determines whether absolute or relative path is used to construct AWS CloudFormation exports.
`@aws-cdk/aws-lambda:recognizeVersionProps`
If set to `false`, the CDK includes metadata when detecting whether a Lambda function has changed. This can cause deployment failures when only the metadata has changed, since duplicate versions are not allowed. There is no need to revert this flag if you’ve made at least one change to all Lambda Functions in your application.
The syntax for reverting these flags in `cdk.json` is shown here.
```
{
"context": {
"@aws-cdk/core:newStyleStackSynthesis": false,
"@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": false,
"@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": false,
"@aws-cdk/aws-rds:lowercaseDbIdentifier": false,
"@aws-cdk/core:stackRelativeExports": false,
"@aws-cdk/aws-lambda:recognizeVersionProps": false
}
}
```
# Aspects and the AWS CDK
Aspects are a way to apply an operation to all constructs in a given scope. The aspect could modify the constructs, such as by adding tags. Or it could verify something about the state of the constructs, such as making sure that all buckets are encrypted.
To apply an aspect to a construct and all constructs in the same scope, call ` [Aspects](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Aspects.html#static-ofscope).of().add()` with a new aspect, as shown in the following example.
**Example**
```
Aspects.of(myConstruct).add(new SomeAspect(...));
```
```
Aspects.of(myConstruct).add(new SomeAspect(...));
```
```
Aspects.of(my_construct).add(SomeAspect(...))
```
```
Aspects.of(myConstruct).add(new SomeAspect(...));
```
```
Aspects.Of(myConstruct).add(new SomeAspect(...));
```
```
awscdk.Aspects_Of(stack).Add(awscdk.NewTag(...))
```
The AWS CDK uses aspects to [tag resources](tagging.md), but the framework can also be used for other purposes. For example, you can use it to validate or change the AWS CloudFormation resources that are defined for you by higher-level constructs.
## Aspects vs. Mixins
Aspects and [Mixins](mixins.md) both modify constructs, but they differ in when and how they are applied:
| Feature | Aspects | Mixins |
| --- | --- | --- |
| **When applied** | During synthesis, after all other code has run. | Immediately when `.with()` is called. |
| **Scope** | All constructs in a given scope, including constructs added later. | Only the constructs you explicitly apply them to. |
| **Style** | Declarative — you set a rule and the CDK applies it. | Imperative — you choose what to apply and where. |
| **Best for** | Validation, compliance, tagging, broad policies. | Adding specific features to individual resources. |
Use Aspects when you want to enforce rules across your entire application or validate that constructs meet certain criteria. Use Mixins when you want to add a specific feature to a specific construct.
Aspects and Mixins can be used together. For example, you might use Mixins to configure individual resources and Aspects to validate that all resources in a stack meet your organization’s security requirements.
## Aspects in detail
Aspects employ the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern). An aspect is a class that implements the following interface.
**Example**
```
interface IAspect {
visit(node: IConstruct): void;}
```
JavaScript doesn’t have interfaces as a language feature. Therefore, an aspect is simply an instance of a class having a `visit` method that accepts the node to be operated on.
Python doesn’t have interfaces as a language feature. Therefore, an aspect is simply an instance of a class having a `visit` method that accepts the node to be operated on.
```
public interface IAspect {
public void visit(Construct node);
}
```
```
public interface IAspect
{
void Visit(IConstruct node);
}
```
```
type IAspect interface {
Visit(node constructs.IConstruct)
}
```
When you call `Aspects.of().add(…)`, the construct adds the aspect to an internal list of aspects. You can obtain the list with `Aspects.of()`.
During the [prepare phase](deploy.md#deploy-how-synth-app), the AWS CDK calls the `visit` method of the object for the construct and each of its children in top-down order.
The `visit` method is free to change anything in the construct. In strongly typed languages, cast the received construct to a more specific type before accessing construct-specific properties or methods.
Aspects don’t propagate across `Stage` construct boundaries, because `Stages` are self-contained and immutable after definition. Apply aspects on the `Stage` construct itself (or lower) if you want them to visit constructs inside the `Stage`.
## Example
The following example validates that all buckets created in the stack have versioning enabled. The aspect adds an error annotation to the constructs that fail the validation. This results in the `synth` operation failing and prevents deploying the resulting cloud assembly.
**Example**
```
class BucketVersioningChecker implements IAspect {
public visit(node: IConstruct): void {
// See that we're dealing with a CfnBucket
if (node instanceof s3.CfnBucket) {
// Check for versioning property, exclude the case where the property
// can be a token (IResolvable).
if (!node.versioningConfiguration
|| (!Tokenization.isResolvable(node.versioningConfiguration)
&& node.versioningConfiguration.status !== 'Enabled')) {
Annotations.of(node).addError('Bucket versioning is not enabled');
}
}
}
}
// Later, apply to the stack
Aspects.of(stack).add(new BucketVersioningChecker());
```
```
class BucketVersioningChecker {
visit(node) {
// See that we're dealing with a CfnBucket
if ( node instanceof s3.CfnBucket) {
// Check for versioning property, exclude the case where the property
// can be a token (IResolvable).
if (!node.versioningConfiguration
|| !Tokenization.isResolvable(node.versioningConfiguration)
&& node.versioningConfiguration.status !== 'Enabled')) {
Annotations.of(node).addError('Bucket versioning is not enabled');
}
}
}
}
// Later, apply to the stack
Aspects.of(stack).add(new BucketVersioningChecker());
```
```
@jsii.implements(cdk.IAspect)
class BucketVersioningChecker:
def visit(self, node):
# See that we're dealing with a CfnBucket
if isinstance(node, s3.CfnBucket):
# Check for versioning property, exclude the case where the property
# can be a token (IResolvable).
if (not node.versioning_configuration or
not Tokenization.is_resolvable(node.versioning_configuration)
and node.versioning_configuration.status != "Enabled"):
Annotations.of(node).add_error('Bucket versioning is not enabled')
# Later, apply to the stack
Aspects.of(stack).add(BucketVersioningChecker())
```
```
public class BucketVersioningChecker implements IAspect
{
@Override
public void visit(Construct node)
{
// See that we're dealing with a CfnBucket
if (node instanceof CfnBucket)
{
CfnBucket bucket = (CfnBucket)node;
Object versioningConfiguration = bucket.getVersioningConfiguration();
if (versioningConfiguration == null ||
!Tokenization.isResolvable(versioningConfiguration.toString()) &&
!versioningConfiguration.toString().contains("Enabled"))
Annotations.of(bucket.getNode()).addError("Bucket versioning is not enabled");
}
}
}
// Later, apply to the stack
Aspects.of(stack).add(new BucketVersioningChecker());
```
```
class BucketVersioningChecker : Amazon.Jsii.Runtime.Deputy.DeputyBase, IAspect
{
public void Visit(IConstruct node)
{
// See that we're dealing with a CfnBucket
if (node is CfnBucket)
{
var bucket = (CfnBucket)node;
if (bucket.VersioningConfiguration is null ||
!Tokenization.IsResolvable(bucket.VersioningConfiguration) &&
!bucket.VersioningConfiguration.ToString().Contains("Enabled"))
Annotations.Of(bucket.Node).AddError("Bucket versioning is not enabled");
}
}
}
// Later, apply to the stack
Aspects.Of(stack).add(new BucketVersioningChecker());
```