aws / aws/aws-cdk

aws-cdk: Support setting the container runtime in cdk.json

Open
#31,319 4 comments 1 reaction 0 assignees View on GitHub
@aws-cdk/core @aws-cdk/pipelines effort/medium feature-request p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
1d 19h
Merged PRs (30d)
74

Description

### Describe the feature

The undocumented (https://github.com/aws/aws-cdk/issues/25657) `CDK_DOCKER` environment variable introduced by https://github.com/aws/aws-cdk/pull/23855 lets users specify the container runtime to use for Docker/OCI container image asset functionality in the AWS CDK.

To make this portable, however, users need to rely on other environment management tools that support project-specific configurations which can be committed to source control such as [Nix](https://github.com/NixOS/nix) (`flake.nix` or `shell.nix`), [direnv](https://github.com/direnv/direnv) (`.envrc`), [dotenv](https://github.com/motdotla/dotenv) (`.env`), or [development containers](https://containers.dev).

Instead of needing to set up these others tools, users should be able to set this option in their `cdk.json` which they are already committing to source control.

### Use Case

Some CI/CD pipelines use Docker/OCI container based environments where users specify a container image (contains a Linux userspace) to use as the build environment (e.g. AWS CodeBuild steps in AWS CodePipelines, GitLab Pipelines with runners using the Docker executor). That is, build jobs run inside a container.

Since the build job itself might need to use a container engine to build containers or run containerized services within the build environment for testing, users end up doing Docker-in-Docker (DinD).

DinD, however, [has a lot of sharp edges](https://jpetazzo.github.io/2015/09/03/do-not-use-docker-in-docker-for-ci). Some of these are related to the Docker daemon requiring escalated privileges.

Unless the CI/CD pipeline has a workaround like exposing the underlying host's Docker daemon Unix socket with a bind mount or running the build job in a privileged container (both are security vulnerabilities), users need to use an alternative container runtime like Podman which doesn't rely on a privileged daemon.

To make it easier to configure the AWS CDK to use an alternative container runtime in both local development and CI/CD environments, users should be able to set this option in their `cdk.json`. This file is already committed to source control for AWS CDK projects and is pulled into CI/CD environments as a result.

### Acknowledgements

- [ ] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### CDK version used

2.155.0

### Environment details (OS name and version, etc.)

macOS 14 (Sonoma)

Contributor guide

Open the contributing guide

Research direction

The request targets cdk.json and the CDK_DOCKER environment variable. Start by locating where CDK_DOCKER is read and how cdk.json settings are loaded; done when the container runtime can be selected from committed cdk.json configuration in local and CI use cases, with coverage for the new setting.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, docker
Domain
cloud, devops
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.