A minimal bundle containing the tools required to use CDK for Terraform with your favorite programming language.
The main advantage of such a bundle is that, to be able to develop and deploy CDKTF code, there is no need to install a programming language toolchain, Node.js or even Terraform. This makes it great for clean dev and CI environments in which a versioned set of tools translates into reproducible builds.
The tools are packaged and distributed as a Docker image, available in many flavors:
- language:
python
andgo
- operating system:
linux
anddarwin
- platform:
amd64
andarm64
.
The easiest way to use the bundle is to configure an alias referencing the required image:
# Python
alias cdktf_bundle='docker run --rm -it \
--name cdktf \
--user $(id -u):$(id -g) \
--volume $(pwd):/workspace \
ghcr.io/pcasteran/cdktf-bundle:latest-python-linux'
# Go
alias cdktf_bundle='docker run --rm -it \
--name cdktf \
--user $(id -u):$(id -g) \
--volume $(pwd):/workspace \
ghcr.io/pcasteran/cdktf-bundle:latest-go-linux'
Then, you just have to prepend cdktf_bundle
to all the commands that you want to run, for example:
# Python
cdktf_bundle cdktf init --template=python --local \
--project-name=test --project-description=test \
--enable-crash-reporting=false
cdktf_bundle cdktf provider add google
cdktf_bundle pipenv run ./main.py
cdktf_bundle cdktf deploy
# Go
cdktf_bundle cdktf init --template=go --local \
--project-name=test --project-description=test \
--enable-crash-reporting=false
cdktf_bundle cdktf provider add google
cdktf_bundle go mod download
cdktf_bundle go run main.go
cdktf_bundle cdktf deploy
If using version 0.13.3
, just ignore the following warning:
Could not run version check - A system error occurred: uv_os_get_passwd returned ENOENT (no such file or directory)
As usual when using the CDKTF CLI, all the
commands must be executed from the directory containing the CDKTF configuration. This directory is mounted as a
read-write volume in the run container (--volume
option), this allows to:
- access the CDKTF configuration files from inside the container
- write the run artifacts inside the
cdktf.out
directory - persist the different caches (downloaded Terraform providers, Python virtual environments, ...) inside the
.home
folder that will be automatically created (and marked as gitignored)
The Docker container is run as the current user (--user
option), so all the files created during the execution will
have the correct owner.
If you need to build the image, it is advised (but not mandatory) to
use docker buildx
which supports
the new BuildKit build backend.
Some build arguments are available to customize the image content, they can be found in the Dockerfile. Here are the most important ones:
BASE
: name of the base layer to use, this layer contains the chosen programing language toolchain (python
orgo
)CDKTF_VERSION
: the version of the cdktf-cli package to installTERRAFORM_VERSION
: the version of Terraform to install
For example:
docker buildx build \
--build-arg "BASE=python" \
--build-arg "CDKTF_VERSION=0.13.3" \
--tag cdktf-bundle:my-python \
.
When creating a new CDKTF project (cdktf init
), you can choose between
two built-in templates for Python
projects: python
(which uses Pipenv as the dependency manager) and python-pip
.
If you want to use Poetry as the dependency manager, it is possible using a community maintained template. To allow that, Poetry is installed in the Python flavor Docker images.
# Python
cdktf_bundle cdktf init --local \
--template="https://github.com/johnfraney/cdktf-remote-template-python-poetry/archive/refs/heads/main.zip" \
--project-name=test --project-description=test \
--no-enable-crash-reporting
There is however one small issue regarding the installation of providers. Currently, CDKTF only allows to install
Python packages using pipenv
or pip
commands (
see PythonPackageManager
)
.
As there is no support for Poetry, it is not possible to install a provider using the cdktf provider add
command, for
example: cdktf_bundle cdktf provider add google
. Instead, the provider must be installed directly using Poetry, for
example: cdktf_bundle poetry add cdktf-cdktf-provider-google
(notice the full
PyPI package name).
When accessing the GCP API, Terraform authenticates using the Application default credentials mechanism.
To allow using these credentials from inside the cdktf
container, you just need to modify the alias as follows:
alias cdktf_bundle='docker run --rm -it \
--name cdktf \
--user $(id -u):$(id -g) \
--volume $(pwd):/workspace \
--volume "${HOME}/.config/gcloud/application_default_credentials.json":/gcp/adc.json:ro \
--env GOOGLE_APPLICATION_CREDENTIALS=/gcp/adc.json \
ghcr.io/pcasteran/cdktf-bundle:latest-python-linux'
The new volume declaration mounts the JSON file containing your credentials, in read-only mode, inside the
container. Then, the standard GOOGLE_APPLICATION_CREDENTIALS
environment variable is set to point to this file.