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).

You add assets through APIs that are exposed by specific AWS constructs. For example, when you define a lambda.Function construct, the code property lets you pass an asset (directory). Function uses assets to bundle the contents of the directory and use it for the function’s code. Similarly, ecs.ContainerImage.fromAsset 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 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 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:

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 aws-s3-assets module.

The following example defines a local directory asset and a file asset.

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 fromAsset() 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.

The Function method uses assets to bundle the contents of the directory and use it for the function’s code.

Deploy-time attributes example

Amazon S3 asset types also expose deploy-time 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.)

Permissions

If you use Amazon S3 assets directly through the aws-s3-assets module, IAM roles, users, or groups, and you need to read assets in runtime, then grant those assets IAM permissions through the asset.grantRead method.

The following example grants an IAM group read permissions on a file asset.

Docker image assets

The AWS CDK supports bundling local Docker images as assets through the aws-ecr-assets 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.

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 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 TaskDefinition 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.

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.

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.

Permissions

If you use a module that supports Docker image assets, such as aws-ecs, the AWS CDK manages permissions for you when you use assets directly or through ContainerImage.fromEcrRepository (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 asset.repository.grantPull 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 asset.repository.addToResourcePolicy method (Python: add_to_resource_policy) to grant the appropriate principal permissions.

AWS CloudFormation resource metadata

To enable such use cases, external tools consult a set of metadata entries on AWS CloudFormation resources:

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.