## 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:
```ts
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](https://github.com/cdklabs/cdk-docker-image-deployment/issues)
> or [PR](https://github.com/cdklabs/cdk-docker-image-deployment/pulls) 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](https://github.com/cdklabs/cdk-docker-image-deployment/issues)
> or [PR](https://github.com/cdklabs/cdk-docker-image-deployment/pulls) already. If not, please open an issue asking for it
> or better yet, submit a contribution!
### Under the Hood
1. 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.
2. 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.
3. The deployment will wait until the CodeBuild Project completes successfully before finishing.
The architecture of this construct can be seen here:
## Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) 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
```typescript
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`
```typescript
public toString(): string
```
Returns a string representation of this construct.
#### Static Functions
| **Name** | **Description** |
| --- | --- |
| isConstruct | Checks if `x` is a construct. |
---
##### ~~`isConstruct`~~
```typescript
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
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
## Structs
### DestinationConfig
Destination information.
#### Initializer
```typescript
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
```typescript
public readonly destinationUri: string;
```
- *Type:* string
The URI of the destination repository to deploy to.
---
##### `loginConfig`Required
```typescript
public readonly loginConfig: LoginConfig;
```
- *Type:* LoginConfig
The login command and region.
---
##### `destinationTag`Optional
```typescript
public readonly destinationTag: string;
```
- *Type:* string
- *Default:* the tag of the source
The tag of the deployed image.
---
### DockerImageDeploymentProps
#### Initializer
```typescript
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
```typescript
public readonly destination: Destination;
```
- *Type:* Destination
Destination repository to deploy the image to.
---
##### `source`Required
```typescript
public readonly source: Source;
```
- *Type:* Source
Source of the image to deploy.
---
### EcrSourceOptions
Properties needed for Source.ecr.
#### Initializer
```typescript
import { EcrSourceOptions } from 'cdk-docker-image-deployment'
const ecrSourceOptions: EcrSourceOptions = { ... }
```
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| tag | string | Tag of deployed image. |
---
##### `tag`Optional
```typescript
public readonly tag: string;
```
- *Type:* string
- *Default:* tag of source
Tag of deployed image.
---
### LoginConfig
Login commands for specified registry.
#### Initializer
```typescript
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
```typescript
public readonly loginCommand: string;
```
- *Type:* string
Command to run in codebuild to login.
Formatted `docker login ...`.
---
##### `region`Optional
```typescript
public readonly region: string;
```
- *Type:* string
- *Default:* undefined if not an ECR repository
Region of ECR repository.
---
### SourceConfig
Source information.
#### Initializer
```typescript
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
```typescript
public readonly imageTag: string;
```
- *Type:* string
The source tag.
---
##### `imageUri`Required
```typescript
public readonly imageUri: string;
```
- *Type:* string
The source image URI.
---
##### `loginConfig`Required
```typescript
public readonly loginConfig: LoginConfig;
```
- *Type:* LoginConfig
The login command and region.
---
### SourceContext
Bind context for Source.
#### Initializer
```typescript
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
```typescript
public readonly handlerRole: IRole;
```
- *Type:* aws-cdk-lib.aws_iam.IRole
The role for the handler.
---
## Classes
### Destination
Specifies docker image deployment destination.
Usage:
```ts
declare const repo: ecr.IRepository;
const destinationEcr = dockerDeploy.Destination.ecr(repository, {
tag: 'tag',
});
```
#### Initializers
```typescript
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`
```typescript
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`
```typescript
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:
```ts
import * as path from 'path';
const path = path.join(__dirname, 'path/to/directory');
const sourceDirectory = Source.directory(path);
```
#### Initializers
```typescript
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`
```typescript
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`
```typescript
import { Source } from 'cdk-docker-image-deployment'
Source.directory(path: string)
```
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).
---