🌜
🌞
cdktf

cdktf

v0.12.0

Cloud Development Kit for Terraform

npm install cdktf

README

npm version PyPI version NuGet version Maven Central homebrew

CDK for Terraform

Cloud Development Kit for Terraform (CDKTF) allows you to use familiar programming languages to define cloud infrastructure and provision it through HashiCorp Terraform. This gives you access to the entire Terraform ecosystem without learning HashiCorp Configuration Language (HCL) and lets you leverage the power of your existing toolchain for testing, dependency management, etc.

We currently support TypeScript, Python, Java, C#, and Go.

terraform platform

CDKTF includes two packages:

  • cdktf-cli - A CLI that allows users to run commands to initialize, import, and synthesize CDK for Terraform applications.
  • cdktf - A library for defining Terraform resources using programming constructs.

Get Started

Choose a language:

Hands-on: Try the tutorials in the CDK for Terraform collection on HashiCorp Learn.

Documentation

Refer to the CDKTF documentation for more detail about how to build and manage CDKTF applications, including:

  • Application Architecture: Learn the tools and processes that CDKTF uses to leverage the Terraform ecosystem and convert code into Terraform configuration files. It also explains the major components of a CDKTF application and how those pieces fit together.

  • Project Setup: Learn how to create a new CDKTF project from a pre-built or custom template. Also learn how to convert an existing HCL project into a CDKTF application.

  • Unit Tests: Learn how to test your application in Typescript with jest.

  • Examples: Reference example projects in every supported language and review explanatory videos and other resources.

Community

The development team would love your feedback to help guide the project.

Build

About prerequisites, refer the followings.

Clone the project repository.

git clone https://github.com/hashicorp/terraform-cdk.git

Download dependencies.

cd terraform-cdk/
yarn install

Build the project and packages.

yarn build

Release Notes

0.12.0
Published on July 26, 2022

Breaking Changes

cdktf get exits with 0 exit code when no provider / module specifications are found in the cdktf.json

Previously we would throw an error and exit with 1 if there were no provider or module specifications in the cdktf.json file. This can be inconvenient if cdktf get is part of a workflow.

Fn.merge is split into Fn.mergeLists and Fn.mergeMaps

The Terraform merge function can merge both lists and maps, but this can cause issues when using the result in a typed language. Therefore we split it into Fn.mergeLists and Fn.mergeMaps, this means you need to change your cdktf programs code.

Simplified interfaces of recursive attributes

The generated provider bindings are based on the Terraform schema which does not support recursion and hence uses a large, explicit structure instead. Previously this resulted in long names such as e.g. Wafv2WebAclRuleStatementAndStatementStatementOrStatementStatementLabelMatchStatement. In 0.12 we implemented a first rough detection for this underlying recursion which drastically reduced the amount of generated interfaces as they now are converted to recursive data structures themselves. If you are currently using those types e.g. in a language like Java, you will need to change them to the new shorter names.

feat

  • feat(lib): Introduce Iterator and for_each to implement apply time iteration #1830
  • feat(lib): Introduce TerraformDynamicBlock to enable iterator usage on blocks #1882
  • feat(cli): support refresh only option for diff and deploy #1851
  • feat(docs): Add iterator docs page #1840
  • feat(docs): document FORCE_COLOR env var that allows disabling colored output #1917
  • feat(cli): plug provider add command in help printed after initializing a new cdktf project #1833
  • feat(lib): exposed testing matchers for other languages properly #1935

fix

  • fix: Allow "all" as ignoreChanges lifecycle value #1848
  • fix: Fixed naming collision between resources of different providers #1870
  • fix: Small fix to the CONTRIBUTING.md #1887
  • fix(cli): increase default max memory for node process when running app command for synth #1915
  • fix(provider-generator): Meta arguments available for generated modules #1880
  • fix(provider-generator): replace dashes with underscores in module names for Go when generating bindings for Terraform modules #1928
  • fix(hcl2json): bundle wasm_exec used for building Go instead of looking for it at runtime #1954
  • fix(hcl2cdk): use the same attribute renaming function as in the provider generation #1842
  • fix(hcl2cdk): maps should not be wrapped in arrays #1838

chore

  • chore: document CI flag #1888
  • chore: modernize example output #1914
  • chore: pin provider version #1896
  • chore: update prerequisites #1894
  • chore(tests): Re-enable Windows Provider Add C# Test #1879
  • chore: add tfe test as pre-step to releasing #1872
  • chore: split provider tests into one test per provider #1862
  • chore: reuse integration test definition for releases #1859
  • chore: fix broken link in readme #1845
  • chore: npm-check-updates && yarn upgrade #1706
0.11.2
Published on June 8, 2022

feat

  • feat(cli): support custom Terraform Enterprise instances #1857
  • feat(hcl2json): expose hcl expression parser #1794

chore

  • chore: synthesize all boolean as iresolvable tests #1849
  • chore(docs): Fix Environment Variables and Best Practices #1839
0.11.1
Published on June 2, 2022

fix

  • fix(cli): Fix package version check on Windows #1831
  • fix(docs): fix code blocks in "create and deploy" documentation #1826
  • fix(release): update changelog #1824

chore

  • chore(cli): filter usage errors from error reporting #1828
  • chore: document debug command #1812
  • chore: add best practice page #1790
0.11.0
Published on May 24, 2022

Breaking Changes

Abbreviated version below, for a guide see Upgrade Guide for 0.11

TF_VAR_ prefixed environment variables can no longer be accessed at synth time

These environment variables will now be filtered out in the synth phase since they are only intended to be used during diff (plan) and deploy (apply) phases to supply values for TerraformVariables. This inhibits accidentally inlining those values into the generated cdk.tf.json config.

Environment variable and CLI option changes

  • DEBUG is replaced by setting CDKTF_LOG_LEVEL=debug, setting the CDKTF_LOG_LEVEL to debug will now also behave like DEBUG=1 and include logs from the provider generation
  • CDKTF_DISABLE_LOGGING=false is replaced by setting CDKTF_LOG_FILE_DIRECTORY=/path/to/logs/directory. If left empty no logs will be written.
  • --disable-logging was removed, instead use the environment variable CDKTF_LOG_LEVEL=off
  • DISABLE_VERSION_CHECK, CDKTF_DISABLE_PLUGIN_CACHE_ENV need to be set to true or 1, before anything worked.

Stack ids can no longer contain whitespaces

A TerraformStack may no longer contain whitespace characters, since we rely on paths being whitespace free. If you have a stack with an id containing a whitespace, please replace it with a hyphen. If the stack was already deployed with the default LocalBackend you might need to rename your statefile to match the new stack id.

Computed Map References are referenced through getter

For computed maps, the reference is now through a getter.

To access { property = "value" }, instead of resource.mapAttribute("property") you can now use resource.mapAttribute.lookup("property").

Use ComplexLists and ComplexMaps for complex assignable properties #1725

Assignable properties of the form Object[] or { [key: string]: Object } no longer have setters; they instead have putX methods. The getter return type is also changed to be a derivative of either ComplexList or ComplexMap.

fix

  • fix(docs): Make sure code example works #1807
  • fix(lib): Delay complex object fqn so that override id can still be used #1793
  • fix(provider-generator): strictly adhere to the provider schema #1792
  • fix: Avoid unstable fqn for TerraformElements #1779
  • fix(cli): Respect CDKTF_HOME environment variable for checkpoint telemetry #1778
  • fix(docs): remove outdated docs from the previous watch implementation #1768
  • fix(cli): throw an error if a stack contains a whitespace #1750

feat

  • feat(lib): add docstrings to gcs/http/local backend resources #1803
  • feat(lib): add a warning about id fields #1802
  • feat(docs): add guidance around secrets and warn that those values might be inlined in the generated Terraform config #1801
  • feat(lib): add docstrings to cos/etcd/etcdv3 backend resources #1783
  • feat(lib): add docstrings to artifactory/azurerm/consul backend resources #1781
  • feat(lib): add docstrings to S3 backend resource #1780
  • feat(release): support running releases on backport-release branches besides only on main #1770
  • feat(cli): add cdktf provider add command #1761
  • feat(provider-generator): Use ComplexList for any complex list #1725

test

  • test(lib): ensure list mapper does not fail when passed IResolvables #1791

chore

  • chore: group needs to be prefixed per type #1813
  • chore: limit CI concurrency to the latest pushed commits #1810
  • chore(cli): add sentry error reporting #1809
  • chore: document computed map reference documentation #1775
  • chore(release): Update changelog to contain backported release for 0.10.4 #1773
  • chore(docs): document how to debug cdktf programs #1758
0.10.4
Published on May 4, 2022

fix

  • fix(cli): Stop pinning jest in TS init template #1769
0.10.3
Published on April 28, 2022

feat

  • feat(provider-generator): emit a versions.json file to the output directory, containing the used provider versions #1749
  • feat(cli): debug command #1731

chore

  • chore(cli): add environment variable to disable version checks #1757
  • chore: drop Terraform v0.15.7 from Docker image and replace with v1.1.9 for running tests #1747
  • chore: add Terraform v1.1.9 to Docker image #1743
  • chore(docs): update env var usage #1693

fix

  • fix(lib): Add new optional AWS route attributes #1755
  • fix(cli): handle version check more defensively #1753
  • fix(cli): we should not send wait for approval if a stop has been issued #1740
  • fix(cli): Fix indentation of RemoteBackend in CSharp and Java template #1733
  • fix(cli): fix templates to properly indent cdktf.json and add RemoteBackend in TS template #1732
0.10.2
Published on April 19, 2022

fix

  • fix(tests): pin awscc version #1727
  • fix(cli): return non-zero exit code in case of error when using cdktf diff #1726
  • fix(cli): allow init command to run in a directory containing a README.md #1722
  • fix(provider-generator): Include "arn" when assignable #1716
  • fix(hcl2cdk): detect list extensions in strings and wrap them in an array #1707
  • fix(lib): override values containing intrinsic tokens caused an infinite loop #1702
  • fix(lib): contextualize error messages in terraform functions #1699
  • fix(cli): fix path for .terraform directory #1694
  • fix(cli): improve cli error handling #1687

chore

  • chore: align versions to an unpublished version #1718
  • chore(docs): update convert docs #1701
  • chore(docs): update aspect docs #1690
  • chore: npm-check-updates && yarn upgrade #1683

test

  • test(hcl2cdk): add test case for property renaming #1709

feat

  • feat(cli): warn users about misaligned CLI and library versions #1700
  • feat(lib): improve error messages around misused list mutation #1691
0.10.1
Published on April 1, 2022

fix

  • fix(cli): fix convert single blocks as array bug #1680
  • fix(cli): Only print error that's thrown #1678

refactor

  • refactor(tests): move from table driven tests to functional way #1679
  • refactor(cli): remove xstate as state machine #1670

chore

  • chore(docs): update project maturity statement #1676
  • chore(docs): add sidebar link #1674
  • chore: add extra column for PRs outside our main repo #1673

feat

  • feat(cli): support HTTP_PROXY for Terraform Cloud #1507
0.10.0
Published on March 30, 2022

Breaking Changes

Remove cdktf synth --json Option #1640

If you are using cdktf synth --json <stack-name> to get the synthesized JSON configuration for your Stack, you will now need to run cdktf synth && cat ./cdktf.out/stacks/<stack-name>/cdk.tf.json instead. The ./cdktf.out part is your output directory (set by cdktf.json or via the --output flag).

Model ComplexComputedLists as ComplexLists and ComputedObjects #1499

In an effort to streamline the interfaces of resources, computed attributes of the type list and set are now modeled as a separate ComplexList type instead of being a method that directly takes an index and returns an item. This change also did change the type of the index from string to number.

Typescript

// previously
const firstItemId = resource.listAttribute("0").id;

// new
const firstItemId = resource.listAttribute.get(0).id;
const firstItem = resource.listAttribute.get(0); // now possible

Python

first_item_id = resource.list_attribute("0").id;
0.9.4
Published on February 24, 2022

fix

  • fix(lib): check for null objects and don't try to reverse undefined or null #1592

chore

  • chore(cli): fix typo in test assertion #1591

General

License
MPL-2.0
Typescript Types
Built-in
Tree-shakeable
No

Popularity

GitHub Stargazers
3,847
Community Interest
3,246
Number of Forks
337

Maintenance

Commits
11/2110/220350
Last Commit
Open Issues
263
Closed Issues
789
Open Pull Requests
17
Closed Pull Requests
158

Versions

Versions Released
11/2110/22050
Latest Version Released
Jul 26, 2022
Current Tags
latest0.12.0
next0.13.0-pre.6

Contributors

skorfmann
skorfmann
Commits: 586
DanielMSchmidt
DanielMSchmidt
Commits: 366
jsteinich
jsteinich
Commits: 274
ansgarm
ansgarm
Commits: 245
laurapacilio
laurapacilio
Commits: 143
anubhavmishra
anubhavmishra
Commits: 46
schersh
schersh
Commits: 31
joatmon08
joatmon08
Commits: 23
danieldreier
danieldreier
Commits: 22
neilkuan
neilkuan
Commits: 13
marcoferrer
marcoferrer
Commits: 11
phinze
phinze
Commits: 11
eladb
eladb
Commits: 10
redeux
redeux
Commits: 7
sergeyzenchenko
sergeyzenchenko
Commits: 5