CDK Docker Image Deployment

This module allows you to copy docker image assets to a repository you control. This can be necessary if you want to build a Docker image in one CDK app and consume it in a different app or outside the CDK, or if you want to apply a lifecycle policy to all images of a part of your application.

Getting Started

Below is a basic example for how to use the DockerImageDeployment API:

import * as ecr from 'aws-cdk-lib/aws-ecr';
import * as imagedeploy from 'cdk-docker-image-deployment';

const repo = new ecr.Repository.fromRepositoryName(this, 'MyRepository', 'myrepository');

new imagedeploy.DockerImageDeployment(this, 'ExampleImageDeploymentWithTag', {
  source: imagedeploy.Source.directory('path/to/directory'),
  destination: imagedeploy.Destination.ecr(repo, {
    tag: 'myspecialtag',
  }),
});

Currently Supported Sources

Source.directory(): Supply a path to a local docker image as source.

Don't see a source listed? See if there is an open issue or PR already. If not, please open an issue asking for it or better yet, submit a contribution!

Currently Supported Destinations

Destination.ecr(repo, options): Send your docker image to an ECR repository in your stack's account.

Don't see a destination listed? See if there is an open issue or PR already. If not, please open an issue asking for it or better yet, submit a contribution!

Under the Hood

When this stack is deployed (either via cdk deploy or via CI/CD), the contents of the local Docker image will be archived and uploaded to an intermediary assets ECR Repository using the cdk-assets mechanism.
The DockerImageDeployment construct synthesizes a CodeBuild Project which uses docker to pull the image from the intermediary repository, tag the image if a tag is provided, and push the image to the destination repository.
The deployment will wait until the CodeBuild Project completes successfully before finishing.

The architecture of this construct can be seen here:

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

API Reference

Constructs

DockerImageDeployment

DockerImageDeployment pushes an image from a local or external source to a specified external destination.

Initializers

import { DockerImageDeployment } from 'cdk-docker-image-deployment'

new DockerImageDeployment(scope: Construct, id: string, props: DockerImageDeploymentProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`DockerImageDeploymentProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: DockerImageDeploymentProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { DockerImageDeployment } from 'cdk-docker-image-deployment'

DockerImageDeployment.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

Structs

DestinationConfig

Destination information.

Initializer

import { DestinationConfig } from 'cdk-docker-image-deployment'

const destinationConfig: DestinationConfig = { ... }

Properties

Name	Type	Description
`destinationUri`	`string`	The URI of the destination repository to deploy to.
`loginConfig`	`LoginConfig`	The login command and region.
`destinationTag`	`string`	The tag of the deployed image.

`destinationUri`^Required

public readonly destinationUri: string;

Type: string

The URI of the destination repository to deploy to.

`loginConfig`^Required

public readonly loginConfig: LoginConfig;

Type: LoginConfig

The login command and region.

`destinationTag`^Optional

public readonly destinationTag: string;

Type: string
Default: the tag of the source

The tag of the deployed image.

DockerImageDeploymentProps

Initializer

import { DockerImageDeploymentProps } from 'cdk-docker-image-deployment'

const dockerImageDeploymentProps: DockerImageDeploymentProps = { ... }

Properties

Name	Type	Description
`destination`	`Destination`	Destination repository to deploy the image to.
`source`	`Source`	Source of the image to deploy.

`destination`^Required

public readonly destination: Destination;

Type: Destination

Destination repository to deploy the image to.

`source`^Required

public readonly source: Source;

Type: Source

Source of the image to deploy.

EcrSourceOptions

Properties needed for Source.ecr.

Initializer

import { EcrSourceOptions } from 'cdk-docker-image-deployment'

const ecrSourceOptions: EcrSourceOptions = { ... }

Properties

Name	Type	Description
`tag`	`string`	Tag of deployed image.

`tag`^Optional

public readonly tag: string;

Type: string
Default: tag of source

Tag of deployed image.

LoginConfig

Login commands for specified registry.

Initializer

import { LoginConfig } from 'cdk-docker-image-deployment'

const loginConfig: LoginConfig = { ... }

Properties

Name	Type	Description
`loginCommand`	`string`	Command to run in codebuild to login.
`region`	`string`	Region of ECR repository.

`loginCommand`^Required

public readonly loginCommand: string;

Type: string

Command to run in codebuild to login.

Formatted docker login ....

`region`^Optional

public readonly region: string;

Type: string
Default: undefined if not an ECR repository

Region of ECR repository.

SourceConfig

Source information.

Initializer

import { SourceConfig } from 'cdk-docker-image-deployment'

const sourceConfig: SourceConfig = { ... }

Properties

Name	Type	Description
`imageTag`	`string`	The source tag.
`imageUri`	`string`	The source image URI.
`loginConfig`	`LoginConfig`	The login command and region.

`imageTag`^Required

public readonly imageTag: string;

Type: string

The source tag.

`imageUri`^Required

public readonly imageUri: string;

Type: string

The source image URI.

`loginConfig`^Required

public readonly loginConfig: LoginConfig;

Type: LoginConfig

The login command and region.

SourceContext

Bind context for Source.

Initializer

import { SourceContext } from 'cdk-docker-image-deployment'

const sourceContext: SourceContext = { ... }

Properties

Name	Type	Description
`handlerRole`	`aws-cdk-lib.aws_iam.IRole`	The role for the handler.

`handlerRole`^Required

public readonly handlerRole: IRole;

Type: aws-cdk-lib.aws_iam.IRole

The role for the handler.

Classes

Destination

Specifies docker image deployment destination.

Usage:

declare const repo: ecr.IRepository;
const destinationEcr = dockerDeploy.Destination.ecr(repository, {
   tag: 'tag',
});

Initializers

import { Destination } from 'cdk-docker-image-deployment'

new Destination()

Name	Type	Description

Methods

Name	Description
`bind`	Bind grants the CodeBuild role permissions to pull and push to a repository if necessary.

`bind`

public bind(role: IGrantable): DestinationConfig

Bind grants the CodeBuild role permissions to pull and push to a repository if necessary.

Bind should be invoked by the caller to get the DestinationConfig.

`role`^Required

Type: aws-cdk-lib.aws_iam.IGrantable

Static Functions

Name	Description
`ecr`	Uses an ECR repository in the same account as the stack as the destination for the image.

`ecr`

import { Destination } from 'cdk-docker-image-deployment'

Destination.ecr(repository: IRepository, options?: EcrSourceOptions)

Uses an ECR repository in the same account as the stack as the destination for the image.

`repository`^Required

Type: aws-cdk-lib.aws_ecr.IRepository

`options`^Optional

Type: EcrSourceOptions

Source

Specifies docker image deployment source.

Usage:

import * as path from 'path';
const path = path.join(__dirname, 'path/to/directory');
const sourceDirectory = Source.directory(path);

or with additional assetOptions

import * as path from 'path';
const path = path.join(__dirname, 'path/to/directory');
const sourceDirectory = Source.directory(path, {
   file: 'Dockerfile.api',
   buildArgs: {
     HTTP_PROXY: 'http://10.20.30.2:1234'
   }
})

Initializers

import { Source } from 'cdk-docker-image-deployment'

new Source()

Name	Type	Description

Methods

Name	Description
`bind`	Bind grants the CodeBuild role permissions to pull from a repository if necessary.

`bind`

public bind(scope: Construct, context: SourceContext): SourceConfig

Bind grants the CodeBuild role permissions to pull from a repository if necessary.

Bind should be invoked by the caller to get the SourceConfig.

`scope`^Required

Type: constructs.Construct

`context`^Required

Type: SourceContext

Static Functions

Name	Description
`directory`	Uses a local image built from a Dockerfile in a local directory as the source.

`directory`

import { Source } from 'cdk-docker-image-deployment'

Source.directory(path: string, assetOptions?: DockerImageAssetOptions)

Uses a local image built from a Dockerfile in a local directory as the source.

`path`^Required

Type: string

path to the directory containing your Dockerfile (not a path to a file).

`assetOptions`^Optional

Type: aws-cdk-lib.aws_ecr_assets.DockerImageAssetOptions

specify any additional DockerImageAssetOptions (except path).

Files

API.md

Latest commit

History

API.md

File metadata and controls

CDK Docker Image Deployment

Getting Started

Currently Supported Sources

Currently Supported Destinations

Under the Hood

Security

License

API Reference

Constructs

DockerImageDeployment

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

Structs

DestinationConfig

Initializer

Properties

destinationUriRequired

loginConfigRequired

destinationTagOptional

DockerImageDeploymentProps

Initializer

Properties

destinationRequired

sourceRequired

EcrSourceOptions

Initializer

Properties

tagOptional

LoginConfig

Initializer

Properties

loginCommandRequired

regionOptional

SourceConfig

Initializer

Properties

imageTagRequired

imageUriRequired

loginConfigRequired

SourceContext

Initializer

Properties

handlerRoleRequired

Classes

Destination

Initializers

Methods

bind

roleRequired

Static Functions

ecr

repositoryRequired

optionsOptional

Source

Initializers

Methods

bind

scopeRequired

contextRequired

Static Functions

directory

pathRequired

assetOptionsOptional

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`destinationUri`^Required

`loginConfig`^Required

`destinationTag`^Optional

`destination`^Required

`source`^Required

`tag`^Optional

`loginCommand`^Required

`region`^Optional

`imageTag`^Required

`imageUri`^Required

`loginConfig`^Required

`handlerRole`^Required

`bind`

`role`^Required

`ecr`

`repository`^Required

`options`^Optional

`bind`

`scope`^Required

`context`^Required

`directory`

`path`^Required

`assetOptions`^Optional