or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

docker-image-assets.mdindex.mdtarball-image-assets.md
tile.json

tessl/npm-aws-cdk--aws-ecr-assets

Docker image assets deployed to ECR for AWS CDK applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-cdk/aws-ecr-assets@1.204.x

To install, run

npx @tessl/cli install tessl/npm-aws-cdk--aws-ecr-assets@1.204.0

index.mddocs/

AWS CDK ECR Assets

AWS CDK ECR Assets provides constructs for bundling Docker images as assets within AWS CDK applications. It enables developers to build Docker images from local contexts or load them from tarballs, automatically upload them to Amazon Elastic Container Registry (ECR), and seamlessly reference them in CDK stacks. The package handles ECR repository lifecycle management, IAM permissions, and integrates with CDK's asset management system for consistent deployments across environments.

Package Information

  • Package Name: @aws-cdk/aws-ecr-assets
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-cdk/aws-ecr-assets
  • CDK Version: AWS CDK v1 (deprecated - migrate to AWS CDK v2)

Core Imports

import { DockerImageAsset, TarballImageAsset, NetworkMode, Platform } from "@aws-cdk/aws-ecr-assets";
import { Construct } from "constructs";
import { Construct as CoreConstruct } from "@aws-cdk/core";

For CommonJS:

const { DockerImageAsset, TarballImageAsset, NetworkMode, Platform } = require("@aws-cdk/aws-ecr-assets");
const { Construct } = require("constructs");
const { Construct: CoreConstruct } = require("@aws-cdk/core");

Basic Usage

import { DockerImageAsset } from "@aws-cdk/aws-ecr-assets";
import { Stack, Construct } from "@aws-cdk/core";
import * as path from "path";

export class MyStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // Build and deploy Docker image from local directory
    const imageAsset = new DockerImageAsset(this, "MyDockerImage", {
      directory: path.join(__dirname, "my-docker-app")
    });

    // Use the image URI in other resources
    console.log("Image URI:", imageAsset.imageUri);
    
    // Repository is automatically created and managed
    console.log("Repository:", imageAsset.repository.repositoryName);
  }
}

Architecture

AWS CDK ECR Assets is built around several key components:

  • Docker Image Assets: Build Docker images from local Dockerfile contexts with extensive build configuration
  • Tarball Assets: Load pre-built Docker images from tarball files for deployment
  • ECR Integration: Automatic ECR repository provisioning and image lifecycle management
  • Build Configuration: Support for build arguments, multi-stage builds, custom networking, and cross-platform builds
  • Asset Staging: Integration with CDK's asset staging system for consistent hashing and deployment
  • IAM Integration: Built-in permission management for cross-account and cross-service image access

Capabilities

Docker Image Assets

Build and deploy Docker images from local directories containing Dockerfiles. Supports advanced Docker features including build arguments, multi-stage builds, custom networking modes, and cross-platform compilation.

class DockerImageAsset extends CoreConstruct implements IAsset {
  constructor(scope: Construct, id: string, props: DockerImageAssetProps);
  readonly imageUri: string;
  readonly repository: ecr.IRepository;
  readonly assetHash: string;
  readonly sourceHash: string;
  addResourceMetadata(resource: CfnResource, resourceProperty: string): void;
}

interface DockerImageAssetOptions extends FingerprintOptions, FileFingerprintOptions {
  readonly repositoryName?: string;
  readonly buildArgs?: { [key: string]: string };
  readonly target?: string;
  readonly file?: string;
  readonly networkMode?: NetworkMode;
  readonly platform?: Platform;
  readonly invalidation?: DockerImageAssetInvalidationOptions;
}

interface DockerImageAssetProps extends DockerImageAssetOptions {
  readonly directory: string;
}

Docker Image Assets

Tarball Image Assets

Deploy Docker images from pre-built tarball files. Ideal for scenarios where images are built externally or need to be packaged as binary assets.

class TarballImageAsset extends CoreConstruct implements IAsset {
  constructor(scope: Construct, id: string, props: TarballImageAssetProps);
  readonly imageUri: string;
  readonly repository: ecr.IRepository;
  readonly assetHash: string;
  readonly sourceHash: string;
}

interface TarballImageAssetProps {
  readonly tarballFile: string;
}

Tarball Image Assets

Core Types

import { Construct } from "constructs";
import { Construct as CoreConstruct, CfnResource } from "@aws-cdk/core";
import * as ecr from "@aws-cdk/aws-ecr";

interface IAsset {
  readonly assetHash: string;
}

interface FingerprintOptions {
  readonly follow?: FollowMode;
  readonly exclude?: string[];
  readonly ignoreMode?: IgnoreMode;
  readonly extraHash?: string;
}

interface FileFingerprintOptions {
  readonly followSymlinks?: SymlinkFollowMode;
  readonly exclude?: string[];
  readonly ignoreMode?: IgnoreMode;
  readonly extraHash?: string;
}

enum IgnoreMode {
  GLOB = "glob",
  GIT = "git", 
  DOCKER = "docker"
}

enum SymlinkFollowMode {
  NEVER = "never",
  ALWAYS = "always",
  EXTERNAL = "external",
  BLOCK_EXTERNAL = "block-external"
}

enum FollowMode {
  NEVER = "never",
  ALWAYS = "always", 
  EXTERNAL = "external",
  BLOCK_EXTERNAL = "block-external"
}

class NetworkMode {
  static readonly DEFAULT: NetworkMode;
  static readonly HOST: NetworkMode;
  static readonly NONE: NetworkMode;
  static fromContainer(containerId: string): NetworkMode;
  static custom(mode: string): NetworkMode;
  readonly mode: string;
}

class Platform {
  static readonly LINUX_AMD64: Platform;
  static readonly LINUX_ARM64: Platform;
  static custom(platform: string): Platform;
  readonly platform: string;
}

interface DockerImageAssetInvalidationOptions {
  readonly extraHash?: boolean;
  readonly buildArgs?: boolean;
  readonly target?: boolean;
  readonly file?: boolean;
  readonly repositoryName?: boolean;
  readonly networkMode?: boolean;
  readonly platform?: boolean;
}