Metadata-Version: 2.1
Name: cdklabs.deploy-time-build
Version: 0.1.2
Summary: Run build on CDK deployment time.
Home-page: https://github.com/cdklabs/deploy-time-build.git
Author: Amazon Web Services<aws-cdk-dev@amazon.com>
License: Apache-2.0
Project-URL: Source, https://github.com/cdklabs/deploy-time-build.git
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved
Requires-Python: ~=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aws-cdk-lib<3.0.0,>=2.38.0
Requires-Dist: constructs<11.0.0,>=10.5.1
Requires-Dist: jsii<2.0.0,>=1.125.0
Requires-Dist: publication>=0.0.3
Requires-Dist: typeguard==2.13.3

# Deploy-time Build

AWS CDK L3 construct that allows you to run a build job for specific purposes. Currently this library supports the following use cases:

* Build web frontend static files
* Build a container image
* Build Seekable OCI (SOCI) indices for container images

[![View on Construct Hub](https://constructs.dev/badge?package=%40cdklabs%2Fdeploy-time-build)](https://constructs.dev/packages/@cdklabs/deploy-time-build)

## Usage

Install from npm:

```sh
npm i @cdklabs/deploy-time-build
```

This library defines several L3 constructs for specific use cases. Here is the usage for each case.

### Build Node.js apps

You can build a Node.js app such as a React frontend app on deploy time by the `NodejsBuild` construct.

![architecture](./imgs/architecture.png)

The following code is an example to use the construct:

```python
from cdklabs.deploy_time_build import AssetConfig
from cdklabs.deploy_time_build import NodejsBuild


NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="example-app",
        exclude=["dist", "node_modules"]
    )
    ],
    destination_bucket=destination_bucket,
    distribution=distribution,
    output_source_directory="dist",
    build_commands=["npm ci", "npm run build"],
    build_environment={
        "VITE_API_ENDPOINT": api.url
    },
    nodejs_version=24
)
```

Note that it is possible to pass environment variable `VITE_API_ENDPOINT: api.url` to the construct, which is resolved on deploy time, and injected to the build environment (a vite process in this case.)
The resulting build artifacts will be deployed to `destinationBucket` from CodeBuild.

You can specify multiple input assets by `assets` property. These assets are extracted to respective sub directories. For example, assume you specified assets like the following:

```python
from cdklabs.deploy_time_build import AssetConfig, AssetConfig
NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        # directory containing source code and package.json
        path="example-app",
        exclude=["dist", "node_modules"],
        commands=["npm install"]
    ), AssetConfig(
        # directory that is also required for the build
        path="module1"
    )
    ],
    destination_bucket=destination_bucket,
    distribution=distribution,
    output_source_directory="dist",
    nodejs_version=24
)
```

Then, the extracted directories will be located as the following:

```sh
.                         # a temporary directory (automatically created)
├── example-app           # extracted example-app assets
│   ├── src/              # dist or node_modules directories are excluded even if they exist locally.
│   ├── package.json      # npm install will be executed since its specified in `commands` property.
│   └── package-lock.json
└── module1               # extracted module1 assets
```

You can also override the path where assets are extracted by `extractPath` property for each asset.

With `outputEnvFile` property enabled, a `.env` file is automatically generated and uploaded to your S3 bucket. This file can be used running you frontend project locally. You can download the file to your local machine by running the command added in the stack output.

Please also check [the example directory](./example/) for a complete example.

#### Allowing access from the build environment to other AWS resources

Since `NodejsBuild` construct implements [`iam.IGrantable`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IGrantable.html) interface, you can use `grant*` method of other constructs to allow access from the build environment.

```python
# some_bucket: s3.IBucket
# build: NodejsBuild

some_bucket.grant_read_write(build)
```

You can also use [`iam.Grant`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Grant.html) class to allow any actions and resources.

```python
# build: NodejsBuild

iam.Grant.add_to_principal(grantee=build, actions=["s3:ListBucket"], resource_arns=["*"])
```

#### Motivation - why do we need the `NodejsBuild` construct?

I talked about why this construct can be useful in some situations at CDK Day 2023. See the recording or slides below:

[Recording](https://www.youtube.com/live/b-nSH18gFQk?si=ogEZ2x1NixOj6J6j&t=373) | [Slides](https://speakerdeck.com/tmokmss/deploy-web-frontend-apps-with-aws-cdk)

#### Caching

You can enable npm caching to speed up builds using the `cache` property:

```python
from cdklabs.deploy_time_build import AssetConfig
NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="example-app",
        exclude=["dist", "node_modules"]
    )
    ],
    destination_bucket=destination_bucket,
    output_source_directory="dist",
    cache=CacheType.S3,  # or CacheType.LOCAL
    nodejs_version=24
)
```

Two cache types are available:

* `CacheType.S3`: Stores the npm cache directory in an S3 bucket. Good for builds that run infrequently on different hosts.
* `CacheType.LOCAL`: Stores the npm cache directory on the build host. Faster than S3 but only effective if builds run on the same host.

#### Compute Type

You can specify the compute type for the CodeBuild project using the `computeType` property:

```python
from cdklabs.deploy_time_build import AssetConfig
NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="example-app",
        exclude=["dist", "node_modules"]
    )
    ],
    destination_bucket=destination_bucket,
    output_source_directory="dist",
    compute_type=ComputeType.MEDIUM,
    nodejs_version=24
)
```

#### Considerations

Since this construct builds your frontend apps every time you deploy the stack and there is any change in input assets (and currently there's even no build cache in the Lambda function!), the time a deployment takes tends to be longer (e.g. a few minutes even for the simple app in `example` directory.) This might results in worse developer experience if you want to deploy changes frequently (imagine `cdk watch` deployment always re-build your frontend app).

To mitigate this issue, you can separate the stack for frontend construct from other stacks especially for a dev environment. Another solution would be to set a fixed string as an asset hash, and avoid builds on every deployment.

```python
from cdklabs.deploy_time_build import AssetConfig
NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="../frontend",
        exclude=["node_modules", "dist"],
        commands=["npm ci"],
        # Set a fixed string as a asset hash to prevent deploying changes.
        # This can be useful for an environment you use to develop locally.
        asset_hash="frontend_asset"
    )
    ],
    destination_bucket=destination_bucket,
    distribution=distribution,
    output_source_directory="dist",
    nodejs_version=24
)
```

### Build a container image

You can build a container image at deploy time by the following code:

```python
from aws_cdk.aws_ecs import RuntimePlatform
from cdklabs.deploy_time_build import ContainerImageBuild


image = ContainerImageBuild(self, "Build",
    directory="example-image",
    build_args={"DUMMY_FILE_SIZE_MB": "15"},
    tag="my-image-tag"
)
DockerImageFunction(self, "Function",
    code=image.to_lambda_docker_image_code()
)
arm_image = ContainerImageBuild(self, "BuildArm",
    directory="example-image",
    platform=Platform.LINUX_ARM64,
    repository=image.repository,
    zstd_compression=True
)
FargateTaskDefinition(self, "TaskDefinition",
    runtime_platform=RuntimePlatform(cpu_architecture=CpuArchitecture.ARM64)
).add_container("main",
    image=arm_image.to_ecs_docker_image_code()
)
```

The third argument (props) are a superset of DockerImageAsset's properties. You can set a few additional properties such as `tag`, `repository`, and `zstdCompression`.

### Build SOCI index for a container image

[Seekable OCI (SOCI)](https://aws.amazon.com/about-aws/whats-new/2022/09/introducing-seekable-oci-lazy-loading-container-images/) is a way to help start tasks faster for Amazon ECS tasks on Fargate 1.4.0. You can build and push a SOCI index using the `SociIndexV2Build` construct.

![soci-architecture](imgs/soci-architecture.png)

The following code is an example to use the construct:

```python
from cdklabs.deploy_time_build import SociIndexV2Build


asset = DockerImageAsset(self, "Image", directory="example-image")
soci_index = SociIndexV2Build(self, "SociV2Index",
    repository=asset.repository,
    input_image_tag=asset.asset_hash,
    output_image_tag=f"{asset.assetHash}-soci"
)

# Use with ECS Fargate
task_definition = FargateTaskDefinition(self, "TaskDefinition")
task_definition.add_container("main",
    image=soci_index.to_ecs_docker_image_code()
)

# Or create from DockerImageAsset using utility method
soci_index_from_asset = SociIndexV2Build.from_docker_image_asset(self, "SociV2Index2", asset)
```

The `SociIndexV2Build` construct:

* Takes an input container image and builds a SOCI v2 index for it
* Outputs a new image tag with the embedded SOCI index
* Provides `toEcsDockerImageCode()` method to easily use with ECS tasks
* Uses the same ECR repository for input and output images

We currently use [`soci-wrapper`](https://github.com/tmokmss/soci-wrapper) to build and push SOCI indices.

> [!WARNING]
> The previous `SocideIndexBuild` construct is now deprecated. Customers new to SOCI on AWS Fargate can only use SOCI index manifest v2. See [this article](https://aws.amazon.com/blogs/containers/improving-amazon-ecs-deployment-consistency-with-soci-index-manifest-v2/) for more details.

#### Motivation - why do we need the `SociIndexBuild` construct?

Currently there are several other ways to build a SOCI index; 1. use `soci-snapshotter` CLI, or 2. use [cfn-ecr-aws-soci-index-builder](https://github.com/aws-ia/cfn-ecr-aws-soci-index-builder) solution, none of which can be directly used from AWS CDK. If you are familiar with CDK, you should often deploy container images as CDK assets, which is an ideal way to integrate with other L2 constructs such as ECS. To make the developer experience for SOCI as close as the ordinary container images, the `SociIndexBuild` allows you to deploying a SOCI index directly from CDK, without any dependencies outside of CDK context.

## Development

Commands for maintainers:

```sh
# run test locally
npx tsc -p tsconfig.dev.json
npx integ-runner
npx integ-runner --update-on-failed
```
