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 "github.com/aws/aws-cdk-go/awscdk"


image := awscdk.NewDockerImageAsset(this, jsii.String("CDKDockerImage"), &DockerImageAssetProps{
	Directory: path.join(__dirname, jsii.String("docker")),
})

// Copy from cdk docker image asset to another ECR.
// Copy from cdk docker image asset to another ECR.
ecrdeploy.NewECRDeployment(this, jsii.String("DeployDockerImage1"), &ECRDeploymentProps{
	Src: ecrdeploy.NewDockerImageName(image.ImageUri),
	Dest: ecrdeploy.NewDockerImageName(fmt.Sprintf("%v.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest", cdk.Aws_ACCOUNT_ID())),
})

// Copy from docker registry to ECR.
// Copy from docker registry to ECR.
ecrdeploy.NewECRDeployment(this, jsii.String("DeployDockerImage2"), &ECRDeploymentProps{
	Src: ecrdeploy.NewDockerImageName(jsii.String("nginx:latest")),
	Dest: ecrdeploy.NewDockerImageName(fmt.Sprintf("%v.dkr.ecr.us-west-2.amazonaws.com/my-nginx2:latest", cdk.Aws_ACCOUNT_ID())),
})

// Copy from private docker registry to ECR.
// The format of secret in aws secrets manager must be plain text! e.g. <username>:<password>
// Copy from private docker registry to ECR.
// The format of secret in aws secrets manager must be plain text! e.g. <username>:<password>
ecrdeploy.NewECRDeployment(this, jsii.String("DeployDockerImage3"), &ECRDeploymentProps{
	Src: ecrdeploy.NewDockerImageName(jsii.String("javacs3/nginx:latest"), jsii.String("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: ecrdeploy.NewDockerImageName(fmt.Sprintf("%v.dkr.ecr.us-west-2.amazonaws.com/my-nginx3:latest", cdk.Aws_ACCOUNT_ID())),
}).AddToPrincipalPolicy(awscdk.Aws_iam.NewPolicyStatement(&PolicyStatementProps{
	Effect: awscdk.*Aws_iam.Effect_ALLOW,
	Actions: []*string{
		jsii.String("secretsmanager:GetSecretValue"),
	},
	Resources: []*string{
		jsii.String("*"),
	},
}))

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.

Use this method instead of `instanceof` to properly detect `Construct` instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the `constructs` library on disk are seen as independent, completely different libraries. As a consequence, the class `Construct` in each copy of the `constructs` library is seen as a different class, and an instance of one class will not test as `instanceof` the other class. `npm install` will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the `constructs` library can be accidentally installed, and `instanceof` will behave unpredictably. It is safest to avoid using `instanceof`, and using this type-testing method instead.

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

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 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