cdk-assets

What is cdk-assets?

The cdk-assets npm package is a tool used in the AWS Cloud Development Kit (CDK) ecosystem to manage assets. It helps in packaging, uploading, and managing assets such as files, Docker images, and other resources that are part of your CDK applications.

What are cdk-assets's main functionalities?

Packaging Assets

This feature allows you to package local files or directories as assets. The code sample demonstrates how to create an asset from a local directory.

const { Asset } = require('cdk-assets');
const asset = new Asset(this, 'MyAsset', {
  path: path.join(__dirname, 'my-asset-directory')
});

Uploading Assets

This feature enables you to upload packaged assets to an S3 bucket. The code sample shows how to upload an asset after it has been packaged.

const { Asset } = require('cdk-assets');
const asset = new Asset(this, 'MyAsset', {
  path: path.join(__dirname, 'my-asset-directory')
});
asset.upload();

Managing Docker Images

This feature allows you to manage Docker images as assets. The code sample demonstrates how to create a Docker image asset from a local directory containing a Dockerfile.

const { DockerImageAsset } = require('cdk-assets');
const dockerImage = new DockerImageAsset(this, 'MyDockerImage', {
  directory: path.join(__dirname, 'my-docker-directory')
});

Other packages similar to cdk-assets

aws-cdk-lib

The aws-cdk-lib package is the main library for the AWS CDK. It includes a wide range of constructs for defining AWS infrastructure, including asset management. It provides similar functionalities to cdk-assets but is more comprehensive, covering a broader range of AWS services and constructs.

serverless

The serverless package is a framework for building and deploying serverless applications. It includes features for managing assets, such as packaging and deploying files and Docker images. Compared to cdk-assets, it is more focused on serverless architectures and provides a higher-level abstraction for deploying serverless applications.

terraform

Terraform is an open-source infrastructure as code software tool that provides a consistent CLI workflow to manage hundreds of cloud services. It includes functionalities for managing assets, such as files and Docker images, through its providers. While it is not specific to AWS, it offers similar asset management capabilities as cdk-assets but with a broader multi-cloud focus.

README

cdk-assets

A tool for publishing CDK assets to AWS environments.

The AWS SDK for JavaScript v2 will enter maintenance mode on September 8, 2024 and will reach end-of-support on September 8, 2025.

The implementation of DefaultAwsClient in cdk-assets is tightly coupled to v2 of the AWS JavaScript SDK and, as such, will follow the same end-of-life schedule. Existing applications that use cdk-assets v2 will continue to function as intended, unless there is a fundamental change to any of the AWS services with client wrappers.

cdk-assets v2 will not be updated to support any new AWS services, new features, or any changes to existing services.

cdk-assets v3 now has an available release candidate that uses AWS SDK for JavaScript v3 and will be stabilized prior to v2 being put into maintenance mode.

The following table outlines the future level of support for v2:

Lifecycle Phase	Start Date	End Date	Support Level
Maintenance Mode	September 8, 2024	September 7, 2025	cdk-assets v2 will limit releases to address critical bug fixes, security issues, and dependency upgrades. No new features or non-critical bug fixes will be addressed.
End-Of-Support	September 8, 2025	N/A	cdk-assets v2 will no longer receive updates or releases. Previously published releases will continue to be available via npm and the code will remain on GitHub.

Overview

cdk-assets requires an asset manifest file called assets.json, in a CDK CloudAssembly (cdk.out/assets.json). It will take the assets listed in the manifest, prepare them as required and upload them to the locations indicated in the manifest.

Currently the following asset types are supported:

• Files and archives, uploaded to S3
• Docker Images, uploaded to ECR
• Files, archives, and Docker images built by external utilities

S3 buckets and ECR repositories to upload to are expected to exist already.

We expect assets to be immutable, and we expect that immutability to be reflected both in the asset ID and in the destination location. This reflects itself in the following behaviors:

• If the indicated asset already exists in the given destination location, it will not be packaged and uploaded.
• If some locally cached artifact (depending on the asset type a file or an image in the local Docker cache) already exists named after the asset's ID, it will not be packaged, but will be uploaded directly to the destination location.

For assets build by external utilities, the contract is such that cdk-assets expects the utility to manage dedupe detection as well as path/image tag generation. This means that cdk-assets will call the external utility every time generation is warranted, and it is up to the utility to a) determine whether to do a full rebuild; and b) to return only one thing on stdout: the path to the file/archive asset, or the name of the local Docker image.

Usage

The cdk-asset tool can be used programmatically and via the CLI. Use programmatic access if you need more control over authentication than the default aws-sdk implementation allows.

Command-line use looks like this:

$ cdk-assets /path/to/cdk.out [ASSET:DEST] [ASSET] [:DEST] [...]

Credentials will be taken from the AWS_ACCESS_KEY... environment variables or the default profile (or another profile if AWS_PROFILE is set).

A subset of the assets and destinations can be uploaded by specifying their asset IDs or destination IDs.

Manifest Example

An asset manifest looks like this:

{
  "version": "1.22.0",
  "files": {
    "7aac5b80b050e7e4e168f84feffa5893": {
      "source": {
        "path": "some_directory",
        "packaging": "zip"
      },
      "destinations": {
        "us-east-1": {
          "region": "us-east-1",
          "assumeRoleArn": "arn:aws:iam::12345789012:role/my-account",
          "bucketName": "MyBucket",
          "objectKey": "7aac5b80b050e7e4e168f84feffa5893.zip"
        }
      }
    },
    "3dfe2b80b050e7e4e168f84feff678d4": {
      "source": {
        "executable": ["myzip"]
      },
      "destinations": {
        "us-east-1": {
          "region": "us-east-1",
          "assumeRoleArn": "arn:aws:iam::12345789012:role/my-account",
          "bucketName": "MySpecialBucket",
          "objectKey": "3dfe2b80b050e7e4e168f84feff678d4.zip"
        }
      }
    }
  },
  "dockerImages": {
    "b48783c58a86f7b8c68a4591c4f9be31": {
      "source": {
        "directory": "dockerdir"
      },
      "destinations": {
        "us-east-1": {
          "region": "us-east-1",
          "assumeRoleArn": "arn:aws:iam::12345789012:role/my-account",
          "repositoryName": "MyRepository",
          "imageTag": "b48783c58a86f7b8c68a4591c4f9be31",
          "imageUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/MyRepository:1234567891b48783c58a86f7b8c68a4591c4f9be31"
        }
      }
    },
    "d92753c58a86f7b8c68a4591c4f9cf28": {
      "source": {
        "executable": ["mytool", "package", "dockerdir"]
      },
      "destinations": {
        "us-east-1": {
          "region": "us-east-1",
          "assumeRoleArn": "arn:aws:iam::12345789012:role/my-account",
          "repositoryName": "MyRepository2",
          "imageTag": "d92753c58a86f7b8c68a4591c4f9cf28",
          "imageUri": "123456789987.dkr.ecr.us-east-1.amazonaws.com/MyRepository2:1234567891b48783c58a86f7b8c68a4591c4f9be31"
        }
      }
    }
  }
}

Placeholders

The destination block of an asset manifest may contain the following region and account placeholders:

• ${AWS::Region}
• ${AWS::AccountId}

These will be substituted with the region and account IDs currently configured on the AWS SDK (through environment variables or ~/.aws/... config files).

• The ${AWS::AccountId} placeholder will not be re-evaluated after performing the AssumeRole call.
• If ${AWS::Region} is used, it will principally be replaced with the value in the region key. If the default region is intended, leave the region key out of the manifest at all.

Docker image credentials

For Docker image asset publishing, cdk-assets will docker login with credentials from ECR GetAuthorizationToken prior to building and publishing, so that the Dockerfile can reference images in the account's ECR repo.

cdk-assets can also be configured to read credentials from both ECR and SecretsManager prior to build by creating a credential configuration at '~/.cdk/cdk-docker-creds.json' (override this location by setting the CDK_DOCKER_CREDS_FILE environment variable). The credentials file has the following format:

{
  "version": "1.0",
  "domainCredentials": {
    "domain1.example.com": {
      "secretsManagerSecretId": "mySecret", // Can be the secret ID or full ARN
      "roleArn": "arn:aws:iam::0123456789012:role/my-role" // (Optional) role with permissions to the secret
    },
    "domain2.example.com": {
      "ecrRepository": true,
      "roleArn": "arn:aws:iam::0123456789012:role/my-role" // (Optional) role with permissions to the repo
    }
  }
}

If the credentials file is present, docker will be configured to use the docker-credential-cdk-assets credential helper for each of the domains listed in the file. This helper will assume the role provided (if present), and then fetch the login credentials from either SecretsManager or ECR.

Using Drop-in Docker Replacements

By default, the AWS CDK will build and publish Docker image assets using the docker command. However, by specifying the CDK_DOCKER environment variable, you can override the command that will be used to build and publish your assets.