- Copying over previously generated zip files with Lambda functions.
- Deploying static local files to S3.
Usage Example
The following example usesTerraformAsset to upload the contents of the specified directory into an S3 Bucket. The TerraformAsset is responsible for making sure the directory ends up in the correct output folder as a zip file that the S3BucketObject can reference.
The stack output directory in cdktf.out contains all of the assets that TerraformAsset needs. This is important for workflows where you use synthesized configurations with Terraform directly. For example, you would only need to upload the contents of the stack output folder to HCP Terraform or Terraform Enterprise.
Paths
Assets support both absolute and relative paths. Relative paths are always considered to be relative to your project’scdktf.json file.
Asset Hashing
Each asset exposes anassetHash, and the hash is part of the synthesized path. When the asset’s contents change, the hash — and therefore the path — changes, so resources referencing the asset pick up the new version. You can pass a fixed assetHash in the TerraformAsset configuration to control this yourself, for example to avoid updates from files that change on every build.
With the canonicalAssetHashes feature flag enabled, the hash covers everything that affects the emitted asset: file contents, names, permission bits, symlink targets, and — for directory assets — empty directories. Renaming a file, making a script executable, or retargeting a symlink each produce a new hash and asset path. For ARCHIVE assets the hash corresponds exactly to the emitted zip file.
Projects created with cdktn init have the flag enabled. Existing projects can opt in via cdktf.json:
Enabling the flag on an existing project changes all asset hashes and paths once, so referencing resources see a one-time update. See Canonical Asset Hashes for details.
Rebuilding Bundled Assets
ATerraformAsset with a bundler builds once per hash under the default SOURCE hashing, and also when you set a fixed assetHash. On later synths, CDKTN keeps the artifact already in the output directory (cdktf.out by default) as long as the hash and the asset type are unchanged, instead of running the bundler again. See Bundlers for how a bundler is set up.
Under SOURCE hashing, the hash covers the source under path, extraHash, the bundler’s bundlerKey, and the cdktn:assetHashSalt context value. Changes the hash can’t see don’t trigger a rebuild, for example:
- A change to the bundler’s code or options that its
bundlerKeydoesn’t reflect. - Files the build reads from outside
path, such as a working directory above the source or a shared package in a monorepo. - A new image behind a mutable Docker tag such as
node:20.
extraHash, for example a version string or a hash of the extra files. To force a rebuild once, delete the output directory, or change cdktn:assetHashSalt to rebuild every asset in the app. With a fixed assetHash, extraHash is not used, so change the assetHash value instead. With AssetHashType.OUTPUT, the bundler runs on every synth because the hash is taken from its output.