or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

docker-image-assets.md index.md tarball-image-assets.md

tile.json

Tarball Image Assets

Tarball Image Assets provide functionality for deploying pre-built Docker images from tarball files within AWS CDK applications. This approach is ideal for scenarios where Docker images are built externally, packaged as tarballs, or need to be included as binary assets in the deployment process.

import { TarballImageAsset, TarballImageAssetProps } from "@aws-cdk/aws-ecr-assets";
import { IAsset } from "@aws-cdk/assets";
import { Construct } from "constructs";
import { Construct as CoreConstruct } from "@aws-cdk/core";
import * as ecr from "@aws-cdk/aws-ecr";

Capabilities

TarballImageAsset Class

Main construct for creating Docker image assets from pre-built tarball files.

/**
 * An asset that represents a Docker image.
 * The image will loaded from an existing tarball and uploaded to an ECR repository.
 */
class TarballImageAsset extends CoreConstruct implements IAsset {
  /**
   * Creates a new tarball image asset
   * @param scope - The scope in which to define this construct
   * @param id - The scoped construct ID
   * @param props - Configuration properties for the tarball image asset
   */
  constructor(scope: Construct, id: string, props: TarballImageAssetProps);

  /** The full URI of the image (including a tag). Use this reference to pull the asset. */
  readonly imageUri: string;

  /** Repository where the image is stored */
  readonly repository: ecr.IRepository;

  /** A hash of this asset, which is available at construction time */
  readonly assetHash: string;

  /** @deprecated use assetHash - A hash of the source of this asset */
  readonly sourceHash: string;
}

Usage Examples:

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

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

    // Load image from tarball file
    const tarballAsset = new TarballImageAsset(this, "MyTarballImage", {
      tarballFile: path.join(__dirname, "images", "my-app.tar")
    });

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

    // Grant pull permissions to other resources
    tarballAsset.repository.grantPull(myRole);
  }
}

TarballImageAssetProps Interface

Configuration properties for TarballImageAsset construction.

/**
 * Options for TarballImageAsset
 */
interface TarballImageAssetProps {
  /**
   * Absolute path to the tarball.
   * 
   * It is recommended to to use the script running directory (e.g. `__dirname`
   * in Node.js projects or dirname of `__file__` in Python) if your tarball
   * is located as a resource inside your project.
   */
  readonly tarballFile: string;
}

Implementation Details

Tarball Processing

When a TarballImageAsset is created, the following process occurs:

File Validation: The specified tarball file is validated to ensure it exists
Asset Staging: The tarball is staged as a CDK asset using the AssetStaging construct
Hash Generation: A unique asset hash is generated based on the tarball contents
ECR Repository: An ECR repository is provisioned to store the image
Load Command: A shell command is generated to load the image from the tarball during deployment

Deployment Process

During deployment, the CDK toolkit:

Uploads the tarball to the CDK asset bucket
Executes the load command: docker load -i <tarball-path> | sed "s/Loaded image: //g"
Tags the loaded image with the asset hash
Pushes the image to the provisioned ECR repository

Asset Hashing

The asset hash for tarball assets is calculated based on:

The contents of the tarball file
The file modification time
The absolute path of the tarball (for uniqueness)

This ensures that changes to the tarball automatically trigger redeployment.

Use Cases

Pre-built Images

Ideal for deploying images that are built by external CI/CD systems:

// Deploy image built by external CI/CD
const preBuiltImage = new TarballImageAsset(this, "PreBuiltImage", {
  tarballFile: "/path/to/ci-built-image.tar"
});

Binary Asset Distribution

Useful when distributing Docker images as part of packaged applications:

// Image packaged with application
const packagedImage = new TarballImageAsset(this, "PackagedImage", {
  tarballFile: path.join(__dirname, "assets", "app-image.tar")
});

Offline Deployments

Suitable for air-gapped environments where images must be pre-packaged:

// Offline deployment scenario
const offlineImage = new TarballImageAsset(this, "OfflineImage", {
  tarballFile: path.resolve("./images/offline-app.tar")
});

Best Practices

File Path Recommendations

Use absolute paths or paths relative to your project structure:

// Recommended: Use __dirname for project-relative paths
const asset = new TarballImageAsset(this, "Asset", {
  tarballFile: path.join(__dirname, "images", "app.tar")
});

// Acceptable: Absolute paths
const asset2 = new TarballImageAsset(this, "Asset2", {
  tarballFile: "/absolute/path/to/image.tar"
});

Tarball Creation

When creating tarballs for use with TarballImageAsset:

# Save Docker image to tarball
docker save my-image:latest -o my-image.tar

# Verify tarball contents
docker load -i my-image.tar

Asset Organization

Organize tarball assets in your project structure:

my-cdk-app/
├── lib/
│   └── my-stack.ts
├── assets/
│   └── images/
│       ├── api-server.tar
│       └── worker.tar
└── package.json

Error Handling

Common errors and troubleshooting:

File not found: Ensure the tarball file exists at the specified path
Invalid tarball: Verify the tarball was created with docker save
Permission errors: Check file system permissions for the tarball file
Load failures: Ensure the tarball contains valid Docker image data

Comparison with DockerImageAsset

Feature	TarballImageAsset	DockerImageAsset
Source	Pre-built tarball	Dockerfile + context
Build time	No build required	Builds during synthesis
Customization	Limited to tarball contents	Full Docker build options
Use case	External builds, offline	Development, CI/CD integration
Dependencies	Docker tarball	Docker + build context

Version

Tile

Files