Skip to content

Latest commit

 

History

History
1042 lines (642 loc) · 35.6 KB

API.md

File metadata and controls

1042 lines (642 loc) · 35.6 KB
Raw

API Reference

Constructs

ContainerImageBuild

  • Implements: aws-cdk-lib.aws_iam.IGrantable

Build a container image and push it to an ECR repository on deploy-time.

Initializers 

import { ContainerImageBuild } from 'deploy-time-build'

new ContainerImageBuild(scope: Construct, id: string, props: ContainerImageBuildProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props ContainerImageBuildProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toEcsDockerImageCode Get the instance of {@link ContainerImage} for an ECS task definition.
toLambdaDockerImageCode Get the instance of {@link DockerImageCode} for a Lambda function image.
toString 
public toString(): string

Returns a string representation of this construct.

toEcsDockerImageCode 
public toEcsDockerImageCode(): EcrImage

Get the instance of {@link ContainerImage} for an ECS task definition.

toLambdaDockerImageCode 
public toLambdaDockerImageCode(): DockerImageCode

Get the instance of {@link DockerImageCode} for a Lambda function image.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { ContainerImageBuild } from 'deploy-time-build'

ContainerImageBuild.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to.
imageTag string No description.
repository aws-cdk-lib.aws_ecr.IRepository No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

The principal to grant permissions to.

imageTagRequired 
public readonly imageTag: string;
  • Type: string
repositoryRequired 
public readonly repository: IRepository;
  • Type: aws-cdk-lib.aws_ecr.IRepository

NodejsBuild

  • Implements: aws-cdk-lib.aws_iam.IGrantable

Build Node.js app and optionally publish the artifact to an S3 bucket.

Initializers 

import { NodejsBuild } from 'deploy-time-build'

new NodejsBuild(scope: Construct, id: string, props: NodejsBuildProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props NodejsBuildProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

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 { NodejsBuild } from 'deploy-time-build'

NodejsBuild.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

The principal to grant permissions to.

SociIndexBuild

Build and publish a SOCI index for a container image.

A SOCI index helps start Fargate tasks faster in some cases. Please read the following document for more details: https://docs.aws.amazon.com/AmazonECS/latest/userguide/container-considerations.html

Initializers 

import { SociIndexBuild } from 'deploy-time-build'

new SociIndexBuild(scope: Construct, id: string, props: SociIndexBuildProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props SociIndexBuildProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

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.
fromDockerImageAsset A utility method to create a SociIndexBuild construct from a DockerImageAsset instance.
isConstruct 
import { SociIndexBuild } from 'deploy-time-build'

SociIndexBuild.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

fromDockerImageAsset 
import { SociIndexBuild } from 'deploy-time-build'

SociIndexBuild.fromDockerImageAsset(scope: Construct, id: string, imageAsset: DockerImageAsset)

A utility method to create a SociIndexBuild construct from a DockerImageAsset instance.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
imageAssetRequired
  • Type: aws-cdk-lib.aws_ecr_assets.DockerImageAsset

Properties

Name Type Description
node constructs.Node The tree node.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

Structs

AssetConfig

Initializer 

import { AssetConfig } from 'deploy-time-build'

const assetConfig: AssetConfig = { ... }

Properties

Name Type Description
assetHash string Specify a custom hash for this asset.
assetHashType aws-cdk-lib.AssetHashType Specifies the type of hash to calculate for this asset.
bundling aws-cdk-lib.BundlingOptions Bundle the asset by executing a command in a Docker container or a custom bundling provider.
exclude string[] File paths matching the patterns will be excluded.
followSymlinks aws-cdk-lib.SymlinkFollowMode A strategy for how to handle symlinks.
ignoreMode aws-cdk-lib.IgnoreMode The ignore behavior to use for exclude patterns.
readers aws-cdk-lib.aws_iam.IGrantable[] A list of principals that should be able to read this asset from S3.
path string The disk location of the asset.
commands string[] Shell commands executed right after the asset zip is extracted to the build environment.
extractPath string Relative path from a build directory to the directory where the asset is extracted.
assetHashOptional 
public readonly assetHash: string;
  • Type: string
  • Default: based on assetHashType

Specify a custom hash for this asset.

If assetHashType is set it must be set to AssetHashType.CUSTOM. For consistency, this custom hash will be SHA256 hashed and encoded as hex. The resulting hash will be the asset hash.

NOTE: the hash is used in order to identify a specific revision of the asset, and used for optimizing and caching deployment activities related to this asset such as packaging, uploading to Amazon S3, etc. If you chose to customize the hash, you will need to make sure it is updated every time the asset changes, or otherwise it is possible that some deployments will not be invalidated.

assetHashTypeOptional 
public readonly assetHashType: AssetHashType;
  • Type: aws-cdk-lib.AssetHashType
  • Default: the default is AssetHashType.SOURCE, but if assetHash is explicitly specified this value defaults to AssetHashType.CUSTOM.

Specifies the type of hash to calculate for this asset.

If assetHash is configured, this option must be undefined or AssetHashType.CUSTOM.

bundlingOptional 
public readonly bundling: BundlingOptions;
  • Type: aws-cdk-lib.BundlingOptions
  • Default: uploaded as-is to S3 if the asset is a regular file or a .zip file, archived into a .zip file and uploaded to S3 otherwise

Bundle the asset by executing a command in a Docker container or a custom bundling provider.

The asset path will be mounted at /asset-input. The Docker container is responsible for putting content at /asset-output. The content at /asset-output will be zipped and used as the final asset.

excludeOptional 
public readonly exclude: string[];
  • Type: string[]
  • Default: nothing is excluded

File paths matching the patterns will be excluded.

See ignoreMode to set the matching behavior. Has no effect on Assets bundled using the bundling property.

followSymlinksOptional 
public readonly followSymlinks: SymlinkFollowMode;
  • Type: aws-cdk-lib.SymlinkFollowMode
  • Default: SymlinkFollowMode.NEVER

A strategy for how to handle symlinks.

ignoreModeOptional 
public readonly ignoreMode: IgnoreMode;
  • Type: aws-cdk-lib.IgnoreMode
  • Default: IgnoreMode.GLOB

The ignore behavior to use for exclude patterns.

readersOptional 
public readonly readers: IGrantable[];
  • Type: aws-cdk-lib.aws_iam.IGrantable[]
  • Default: No principals that can read file asset.

A list of principals that should be able to read this asset from S3.

You can use asset.grantRead(principal) to grant read permissions later.

pathRequired 
public readonly path: string;
  • Type: string

The disk location of the asset.

The path should refer to one of the following:

  • A regular file or a .zip file, in which case the file will be uploaded as-is to S3.
  • A directory, in which case it will be archived into a .zip file and uploaded to S3.
commandsOptional 
public readonly commands: string[];
  • Type: string[]
  • Default: No command is executed.

Shell commands executed right after the asset zip is extracted to the build environment.

extractPathOptional 
public readonly extractPath: string;
  • Type: string
  • Default: basename of the asset path.

Relative path from a build directory to the directory where the asset is extracted.

ContainerImageBuildProps

Initializer 

import { ContainerImageBuildProps } from 'deploy-time-build'

const containerImageBuildProps: ContainerImageBuildProps = { ... }

Properties

Name Type Description
exclude string[] File paths matching the patterns will be excluded.
followSymlinks aws-cdk-lib.SymlinkFollowMode A strategy for how to handle symlinks.
ignoreMode aws-cdk-lib.IgnoreMode The ignore behavior to use for exclude patterns.
extraHash string Extra information to encode into the fingerprint (e.g. build instructions and other inputs).
buildArgs {[ key: string ]: string} Build args to pass to the docker build command.
file string Path to the Dockerfile (relative to the directory).
invalidation aws-cdk-lib.aws_ecr_assets.DockerImageAssetInvalidationOptions Options to control which parameters are used to invalidate the asset hash.
networkMode aws-cdk-lib.aws_ecr_assets.NetworkMode Networking mode for the RUN commands during build.
platform aws-cdk-lib.aws_ecr_assets.Platform Platform to build for.
target string Docker target to build to.
directory string The directory where the Dockerfile is stored.
repository aws-cdk-lib.aws_ecr.IRepository The ECR repository to push the image.
tag string The tag when to push the image.
zstdCompression boolean Use zstd for compressing a container image.
excludeOptional 
public readonly exclude: string[];
  • Type: string[]
  • Default: nothing is excluded

File paths matching the patterns will be excluded.

See ignoreMode to set the matching behavior. Has no effect on Assets bundled using the bundling property.

followSymlinksOptional 
public readonly followSymlinks: SymlinkFollowMode;
  • Type: aws-cdk-lib.SymlinkFollowMode
  • Default: SymlinkFollowMode.NEVER

A strategy for how to handle symlinks.

ignoreModeOptional 
public readonly ignoreMode: IgnoreMode;
  • Type: aws-cdk-lib.IgnoreMode
  • Default: IgnoreMode.GLOB

The ignore behavior to use for exclude patterns.

extraHashOptional 
public readonly extraHash: string;
  • Type: string
  • Default: hash is only based on source content

Extra information to encode into the fingerprint (e.g. build instructions and other inputs).

buildArgsOptional 
public readonly buildArgs: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: no build args are passed

Build args to pass to the docker build command.

Since Docker build arguments are resolved before deployment, keys and values cannot refer to unresolved tokens (such as lambda.functionArn or queue.queueUrl).

fileOptional 
public readonly file: string;
  • Type: string
  • Default: 'Dockerfile'

Path to the Dockerfile (relative to the directory).

invalidationOptional 
public readonly invalidation: DockerImageAssetInvalidationOptions;
  • Type: aws-cdk-lib.aws_ecr_assets.DockerImageAssetInvalidationOptions
  • Default: hash all parameters

Options to control which parameters are used to invalidate the asset hash.

networkModeOptional 
public readonly networkMode: NetworkMode;
  • Type: aws-cdk-lib.aws_ecr_assets.NetworkMode
  • Default: no networking mode specified (the default networking mode NetworkMode.DEFAULT will be used)

Networking mode for the RUN commands during build.

Support docker API 1.25+.

platformOptional 
public readonly platform: Platform;
  • Type: aws-cdk-lib.aws_ecr_assets.Platform
  • Default: no platform specified (the current machine architecture will be used)

Platform to build for.

Requires Docker Buildx.

targetOptional 
public readonly target: string;
  • Type: string
  • Default: no target

Docker target to build to.

directoryRequired 
public readonly directory: string;
  • Type: string

The directory where the Dockerfile is stored.

Any directory inside with a name that matches the CDK output folder (cdk.out by default) will be excluded from the asset

repositoryOptional 
public readonly repository: IRepository;
  • Type: aws-cdk-lib.aws_ecr.IRepository
  • Default: create a new ECR repository

The ECR repository to push the image.

tagOptional 
public readonly tag: string;
  • Type: string
  • Default: use assetHash as tag

The tag when to push the image.

zstdCompressionOptional 
public readonly zstdCompression: boolean;
  • Type: boolean
  • Default: false

Use zstd for compressing a container image.

NodejsBuildProps

Initializer 

import { NodejsBuildProps } from 'deploy-time-build'

const nodejsBuildProps: NodejsBuildProps = { ... }

Properties

Name Type Description
assets AssetConfig[] The AssetProps from which s3-assets are created and copied to the build environment.
destinationBucket aws-cdk-lib.aws_s3.IBucket S3 Bucket to which your build artifacts are finally deployed.
outputSourceDirectory string Relative path from the working directory to the directory where the build artifacts are output.
buildCommands string[] Shell commands to build your project.
buildEnvironment {[ key: string ]: string} Environment variables injected to the build environment.
destinationKeyPrefix string Key prefix to deploy your build artifact.
distribution aws-cdk-lib.aws_cloudfront.IDistribution The distribution you are using to publish you build artifact.
excludeCommonFiles boolean If true, common unnecessary files/directories such as .DS_Store, .git, node_modules, etc are excluded from the assets by default.
nodejsVersion number The version of Node.js to use in a build environment. Available versions: 12, 14, 16, 18, 20.
outputEnvFile boolean If true, a .env file is uploaded to an S3 bucket with values of buildEnvironment property. You can copy it to your local machine by running the command in the stack output.
workingDirectory string Relative path from the build directory to the directory where build commands run.
assetsRequired 
public readonly assets: AssetConfig[];

The AssetProps from which s3-assets are created and copied to the build environment.

destinationBucketRequired 
public readonly destinationBucket: IBucket;
  • Type: aws-cdk-lib.aws_s3.IBucket

S3 Bucket to which your build artifacts are finally deployed.

outputSourceDirectoryRequired 
public readonly outputSourceDirectory: string;
  • Type: string

Relative path from the working directory to the directory where the build artifacts are output.

buildCommandsOptional 
public readonly buildCommands: string[];
  • Type: string[]
  • Default: ['npm run build']

Shell commands to build your project.

They are executed on the working directory you specified.

buildEnvironmentOptional 
public readonly buildEnvironment: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: {}

Environment variables injected to the build environment.

You can use CDK deploy-time values as well as literals.

destinationKeyPrefixOptional 
public readonly destinationKeyPrefix: string;
  • Type: string
  • Default: '/'

Key prefix to deploy your build artifact.

distributionOptional 
public readonly distribution: IDistribution;
  • Type: aws-cdk-lib.aws_cloudfront.IDistribution
  • Default: No distribution

The distribution you are using to publish you build artifact.

If any specified, the caches are invalidated on new artifact deployments.

excludeCommonFilesOptional 
public readonly excludeCommonFiles: boolean;
  • Type: boolean
  • Default: true

If true, common unnecessary files/directories such as .DS_Store, .git, node_modules, etc are excluded from the assets by default.

nodejsVersionOptional 
public readonly nodejsVersion: number;
  • Type: number
  • Default: 18

The version of Node.js to use in a build environment. Available versions: 12, 14, 16, 18, 20.

outputEnvFileOptional 
public readonly outputEnvFile: boolean;
  • Type: boolean
  • Default: false

If true, a .env file is uploaded to an S3 bucket with values of buildEnvironment property. You can copy it to your local machine by running the command in the stack output.

workingDirectoryOptional 
public readonly workingDirectory: string;
  • Type: string
  • Default: assetProps[0].extractPath

Relative path from the build directory to the directory where build commands run.

SociIndexBuildProps

Initializer 

import { SociIndexBuildProps } from 'deploy-time-build'

const sociIndexBuildProps: SociIndexBuildProps = { ... }

Properties

Name Type Description
imageTag string The tag of the container image you want to build index for.
repository aws-cdk-lib.aws_ecr.IRepository The ECR repository your container image is stored.
imageTagRequired 
public readonly imageTag: string;
  • Type: string

The tag of the container image you want to build index for.

repositoryRequired 
public readonly repository: IRepository;
  • Type: aws-cdk-lib.aws_ecr.IRepository

The ECR repository your container image is stored.

You can only specify a repository in the same environment (account/region). The index artifact will be uploaded to this repository.