page_title | description |
---|---|
Configuration - CDK for Terraform |
Use the cdktf.json file to customize configuration settings and define the providers and modules to use with your application. |
The cdktf.json
file is where you can supply custom configuration settings for your application and define the providers and modules that you want to use. When you initialize a new CDK for Terraform project with a built-in template, the template generates a basic cdktf.json
file in your root directory that you can customize for your application. Refer to the Project Setup documentation for more information about initializing a new project.
export enum Language {
TYPESCRIPT = "typescript",
PYTHON = "python",
CSHARP = "csharp",
JAVA = "java",
GO = "go",
}
export interface TerraformDependencyConstraint {
readonly name: string; // name of the module / provider
readonly source?: string; // path / url / registry identifier for the module / provider
readonly version?: string; // version constraint (https://www.terraform.io/docs/language/providers/requirements.html#version-constraints)
}
type RequirementDefinition = string | TerraformDependencyConstraint;
export interface Config {
readonly app?: string; // The command to run in order to synthesize the code to Terraform compatible JSON
readonly language?: Language; // Target language for building provider or module bindings. Currently supported: `typescript`, `python`, `java`, `csharp`, and `go`
readonly output: string; // Default: 'cdktf.out'. Where the synthesized JSON should go. Also will be the working directory for Terraform operations
readonly codeMakerOutput: string; // Default: '.gen'. Path where generated provider bindings will be rendered to.
readonly projectId: string; // Default: generated UUID. Unique identifier for the project used to differentiate projects
readonly sendCrashReports: boolean; // Default: false. Whether to send crash reports to the CDKTF team
readonly terraformProviders?: RequirementDefinition[]; // Terraform Providers to build
readonly terraformModules?: RequirementDefinition[]; // Terraform Modules to build
}
The most basic configuration only defines app
. This is useful when you plan to use pre-built providers and you don't need to generate any provider or module bindings.
{
"app": "npm run --silent compile && node main.js"
}
You must declare all of the providers and modules that require code bindings in your cdktf.json
file. CDKTF generates these code bindings from cdktf.json
when you run cdktf get
. We have a selection of pre-built providers available, but you may occasionally want to re-generate the code bindings for those providers yourself. For example, you may need a different version of that provider than the pre-built package. We do not provide pre-built modules, so you must always declare them in your cdktf.json
file.
The schema for both providers and modules in CDK for Terraform consists of a name, a source, and a version constraint.
You can declare providers and modules using either JSON or a string with the format source@ ~> version
.
-
HashiCorp providers: You can specify official HashiCorp maintained providers by their name on the Terraform Registry. For example, you can use
aws
to declare the official AWS provider:aws@ ~> 2.0
-
Community providers: You must provide the fully-qualified name. The fully-qualified name is available on the provider's registry page. For example, to define the DataDog provider:
DataDog/datadog@ ~> 3.4.0
-
For modules on the Terraform Registry, provide the the full registry namespace. For example, to define the AWS VPC module:
terraform-aws-modules/vpc/aws@ ~> 3.2.0
. -
For local modules, please use the object format to ensure that CDKTF can properly name the generated classes.
{ // ... "terraformModules": [ { "name": "myLocalModule", "source": "../my-modules/local-module" } ] }
When you declare providers and modules in the string format, add the version constraint after the provider or module name separated by an @
. For example, so provider|module@ ~> version
. The version constraint is optional; when you omit the version constraint, CDK for Terraform will download and use the latest version.
When you declare providers in JSON, add the constraint in the version
property.
{
//...
"terraformProviders": [
{
"name": "aws",
"source": "hashicorp/aws",
"version": "~> 3.22"
}
]
}
When using cdktf watch
, CDKTF inspects the cdktf.json
s watchPattern
property to determine which files to watch. If you do not specify a watchPattern
property, CDKTF adds the default watch pattern for your language on the first run. The watchPattern
expects an array of glob patterns, e.g. ["main.ts", "../constructs/**/*.ts", "lib/*.ts"]
.
Defining output
changes the directory where cdktf
stores your generated Terraform configuration file. Terraform performs all operations within this directory.
The following example synthesizes the JSON Terraform configuration into my-workdir
:
{
"app": "npm run --silent compile && node main.js",
"output": "my-workdir"
}
With the following terraformProviders
configuration, a cdktf get
builds the latest AWS provider within the 2.X version range. CDKTF saves the generated code in in .gen
by default. You can adjust this behavior with codeMakerOutput
. Refer to the other examples on this page.
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"terraformProviders": ["aws@~> 2.0"]
}
With the following terraformModules
configuration, a cdktf get
builds the latest terraform-aws-modules/vpc/aws
module from the Terraform Registry. The generated code will be saved into .gen
by default. You can adjust this behavior with codeMakerOutput
. Refer to the other examples on this page.
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"terraformModules": ["terraform-aws-modules/vpc/aws"]
}
With the following example configuration, a cdktf get
builds both the AWS provider and the latest terraform-aws-modules/vpc/aws
module from the Terraform Registry.
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"terraformModules": ["terraform-aws-modules/vpc/aws"],
"terraformProviders": ["aws@~> 2.0"]
}
You can also build multiple providers or modules. The following example builds multiple providers.
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"terraformProviders": [
"null",
"aws",
"google",
"azurerm",
"kubernetes",
"consul",
"vault",
"nomad"
]
}
The following configuration generates the aws
provider bindings in the folder ./imports
. The Python template uses this method to make it easier to reference the generated classes.
{
"language": "python",
"app": "pipenv run ./main.py",
"terraformProviders": ["aws@~> 2.0"],
"codeMakerOutput": "imports"
}
You can enable or disable crash reporting by setting the sendCrashReports
property to true
or false
. Sending crash reports helps our team improve the CLI faster. Refer to Telemetry for more information about what we track.
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"sendCrashReports": true
}