cdkecrdeployment

README

cdk-ecr-deployment

CDK construct to synchronize single docker image between docker registries.

Only use v3 of this package

⚠️ Version 2.* is no longer supported, as the Go.1.x runtime is no longer supported in AWS Lambda.
⚠️ Version 1.* is no longer supported, as CDK v1 has reached the end-of-life stage.

Features

• Copy image from ECR/external registry to (another) ECR/external registry
• Copy an archive tarball image from s3 to ECR/external registry

Environment variables

Enable flags: true, 1. e.g. export CI=1

• CI indicate if it's CI environment. This flag will enable building lambda from scratch.
• NO_PREBUILT_LAMBDA disable using prebuilt lambda.
• FORCE_PREBUILT_LAMBDA force using prebuilt lambda.

⚠️ If you want to force using prebuilt lambda in CI environment to reduce build time. Try export FORCE_PREBUILT_LAMBDA=1.

Examples

import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';

const image = new DockerImageAsset(this, 'CDKDockerImage', {
  directory: path.join(__dirname, 'docker'),
});

// Copy from cdk docker image asset to another ECR.
new ecrdeploy.ECRDeployment(this, 'DeployDockerImage1', {
  src: new ecrdeploy.DockerImageName(image.imageUri),
  dest: new ecrdeploy.DockerImageName(`${cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest`),
});

// Copy from docker registry to ECR.
new ecrdeploy.ECRDeployment(this, 'DeployDockerImage2', {
  src: new ecrdeploy.DockerImageName('nginx:latest'),
  dest: new ecrdeploy.DockerImageName(`${cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx2:latest`),
});

// Copy from private docker registry to ECR.
// The format of secret in aws secrets manager must be plain text! e.g. <username>:<password>
new ecrdeploy.ECRDeployment(this, 'DeployDockerImage3', {
  src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'username:password'),
  // src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'aws-secrets-manager-secret-name'),
  // src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'arn:aws:secretsmanager:us-west-2:000000000000:secret:id'),
  dest: new ecrdeploy.DockerImageName(`${cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx3:latest`),
}).addToPrincipalPolicy(new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,
  actions: [
    'secretsmanager:GetSecretValue',
  ],
  resources: ['*'],
}));

Sample: test/example.ecr-deployment.ts

# Run the following command to try the sample.
NO_PREBUILT_LAMBDA=1 npx cdk deploy -a "npx ts-node -P tsconfig.dev.json --prefer-ts-exts test/example.ecr-deployment.ts"

API

Tech Details & Contribution

The core of this project relies on containers/image which is used by Skopeo. Please take a look at those projects before contribution.

To support a new docker image source(like docker tarball in s3), you need to implement image transport interface. You could take a look at docker-archive transport for a good start.

To test the lambda folder, make test.

Documentation

Overview

CDK construct to deploy docker image to Amazon ECR

Index

• func ECRDeployment_IsConstruct(x interface{}) *bool
• func NewDockerImageName_Override(d DockerImageName, name *string, creds *string)
• func NewECRDeployment_Override(e ECRDeployment, scope constructs.Construct, id *string, ...)
• func NewS3ArchiveName_Override(s S3ArchiveName, p *string, ref *string, creds *string)
• type DockerImageName
  • func NewDockerImageName(name *string, creds *string) DockerImageName
• type ECRDeployment
  • func NewECRDeployment(scope constructs.Construct, id *string, props *ECRDeploymentProps) ECRDeployment
• type ECRDeploymentProps
• type IImageName
• type S3ArchiveName
  • func NewS3ArchiveName(p *string, ref *string, creds *string) S3ArchiveName

Functions

func ECRDeployment_IsConstruct

func ECRDeployment_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func NewDockerImageName_Override

func NewDockerImageName_Override(d DockerImageName, name *string, creds *string)

func NewECRDeployment_Override

func NewECRDeployment_Override(e ECRDeployment, scope constructs.Construct, id *string, props *ECRDeploymentProps)

func NewS3ArchiveName_Override

func NewS3ArchiveName_Override(s S3ArchiveName, p *string, ref *string, creds *string)

Types

type DockerImageName

type DockerImageName interface {
	IImageName
	// The credentials of the docker image.
	//
	// Format `user:password` or `AWS Secrets Manager secret arn` or `AWS Secrets Manager secret name`.
	Creds() *string
	SetCreds(val *string)
	// The uri of the docker image.
	//
	// The uri spec follows https://github.com/containers/skopeo
	Uri() *string
}

func NewDockerImageName

func NewDockerImageName(name *string, creds *string) DockerImageName

type ECRDeployment

type ECRDeployment interface {
	constructs.Construct
	// The tree node.
	Node() constructs.Node
	AddToPrincipalPolicy(statement awsiam.PolicyStatement) *awsiam.AddToPrincipalPolicyResult
	// Returns a string representation of this construct.
	ToString() *string
}

func NewECRDeployment

func NewECRDeployment(scope constructs.Construct, id *string, props *ECRDeploymentProps) ECRDeployment

type ECRDeploymentProps

type ECRDeploymentProps struct {
	// The destination of the docker image.
	Dest IImageName `field:"required" json:"dest" yaml:"dest"`
	// The source of the docker image.
	Src IImageName `field:"required" json:"src" yaml:"src"`
	// Image to use to build Golang lambda for custom resource, if download fails or is not wanted.
	//
	// Might be needed for local build if all images need to come from own registry.
	//
	// Note that image should use yum as a package manager and have golang available.
	// Default: - public.ecr.aws/sam/build-go1.x:latest
	//
	BuildImage *string `field:"optional" json:"buildImage" yaml:"buildImage"`
	// The environment variable to set.
	Environment *map[string]*string `field:"optional" json:"environment" yaml:"environment"`
	// The image architecture to be copied.
	//
	// The 'amd64' architecture will be copied by default. Specify the
	// architecture or architectures to copy here.
	//
	// It is currently not possible to copy more than one architecture
	// at a time: the array you specify must contain exactly one string.
	// Default: ['amd64'].
	//
	ImageArch *[]*string `field:"optional" json:"imageArch" yaml:"imageArch"`
	// The name of the lambda handler.
	// Default: - bootstrap.
	//
	LambdaHandler *string `field:"optional" json:"lambdaHandler" yaml:"lambdaHandler"`
	// The lambda function runtime environment.
	// Default: - lambda.Runtime.PROVIDED_AL2023
	//
	LambdaRuntime awslambda.Runtime `field:"optional" json:"lambdaRuntime" yaml:"lambdaRuntime"`
	// The amount of memory (in MiB) to allocate to the AWS Lambda function which replicates the files from the CDK bucket to the destination bucket.
	//
	// If you are deploying large files, you will need to increase this number
	// accordingly.
	// Default: - 512.
	//
	MemoryLimit *float64 `field:"optional" json:"memoryLimit" yaml:"memoryLimit"`
	// Execution role associated with this function.
	// Default: - A role is automatically created.
	//
	Role awsiam.IRole `field:"optional" json:"role" yaml:"role"`
	// The list of security groups to associate with the Lambda's network interfaces.
	//
	// Only used if 'vpc' is supplied.
	// Default: - If the function is placed within a VPC and a security group is
	// not specified, either by this or securityGroup prop, a dedicated security
	// group will be created for this function.
	//
	SecurityGroups *[]awsec2.SecurityGroup `field:"optional" json:"securityGroups" yaml:"securityGroups"`
	// The VPC network to place the deployment lambda handler in.
	// Default: - None.
	//
	Vpc awsec2.IVpc `field:"optional" json:"vpc" yaml:"vpc"`
	// Where in the VPC to place the deployment lambda handler.
	//
	// Only used if 'vpc' is supplied.
	// Default: - the Vpc default strategy if not specified.
	//
	VpcSubnets *awsec2.SubnetSelection `field:"optional" json:"vpcSubnets" yaml:"vpcSubnets"`
}

type IImageName

type IImageName interface {
	// The credentials of the docker image.
	//
	// Format `user:password` or `AWS Secrets Manager secret arn` or `AWS Secrets Manager secret name`.
	Creds() *string
	SetCreds(c *string)
	// The uri of the docker image.
	//
	// The uri spec follows https://github.com/containers/skopeo
	Uri() *string
}

type S3ArchiveName

type S3ArchiveName interface {
	IImageName
	// The credentials of the docker image.
	//
	// Format `user:password` or `AWS Secrets Manager secret arn` or `AWS Secrets Manager secret name`.
	Creds() *string
	SetCreds(val *string)
	// The uri of the docker image.
	//
	// The uri spec follows https://github.com/containers/skopeo
	Uri() *string
}

func NewS3ArchiveName

func NewS3ArchiveName(p *string, ref *string, creds *string) S3ArchiveName