0
# CDKTF - Cloud Development Kit for Terraform
1
2
The Cloud Development Kit for Terraform (CDKTF) enables you to define cloud infrastructure using familiar programming languages instead of HashiCorp Configuration Language (HCL). It leverages the entire Terraform ecosystem through a TypeScript-based JSII library that supports multiple target languages including Python, Java, C#, and Go.
3
4
## Package Information
5
6
- **Package Name**: cdktf
7
- **Package Type**: npm
8
- **Language**: TypeScript (with JSII multi-language support)
9
- **Installation**: `npm install cdktf constructs`
10
11
## Core Imports
12
13
```typescript
14
import { App, TerraformStack, TerraformOutput } from "cdktf";
15
import { Construct } from "constructs";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const { App, TerraformStack, TerraformOutput } = require("cdktf");
22
```
23
24
## Basic Usage
25
26
```typescript
27
import { App, TerraformStack, TerraformOutput } from "cdktf";
28
import { Construct } from "constructs";
29
30
class MyStack extends TerraformStack {
31
constructor(scope: Construct, id: string) {
32
super(scope, id);
33
34
// Add Terraform resources, data sources, and outputs here
35
new TerraformOutput(this, "example", {
36
value: "Hello, CDKTF!",
37
});
38
}
39
}
40
41
const app = new App();
42
new MyStack(app, "my-stack");
43
app.synth();
44
```
45
46
## Architecture
47
48
CDKTF is built around several key architectural components:
49
50
- **Constructs Framework**: Based on AWS CDK constructs, providing a hierarchical component model
51
- **JSII Compatibility**: Cross-language support enabling usage in TypeScript, Python, Java, C#, and Go
52
- **Terraform Synthesis**: Converts construct trees into valid Terraform JSON and HCL configurations
53
- **Provider Integration**: Seamless integration with the entire Terraform provider ecosystem
54
- **State Management**: Full compatibility with Terraform state management and backends
55
- **Testing Framework**: Built-in testing utilities for infrastructure validation
56
57
## Capabilities
58
59
### Core Infrastructure Components
60
61
Essential classes for building CDKTF applications, including the root App construct and TerraformStack containers.
62
63
```typescript { .api }
64
class App extends Construct {
65
constructor(config?: AppConfig);
66
synth(): void;
67
crossStackReference(fromStack: TerraformStack, toStack: TerraformStack, identifier: string): string;
68
static isApp(x: any): x is App;
69
static of(construct: IConstruct): App;
70
}
71
72
class TerraformStack extends Construct {
73
constructor(scope: Construct, id: string);
74
toTerraform(): any;
75
toHclTerraform(): any;
76
addOverride(path: string, value: any): void;
77
getLogicalId(tfElement: ITerraformAddressable): string;
78
prepareStack(): void;
79
runAllValidations(): void;
80
ensureBackendExists(): TerraformBackend;
81
allProviders(): TerraformProvider[];
82
addDependency(dependency: TerraformStack): void;
83
dependsOn(stack: TerraformStack): boolean;
84
hasResourceMove(): boolean;
85
registerOutgoingCrossStackReference(identifier: string): TerraformOutput;
86
registerIncomingCrossStackReference(fromStack: TerraformStack): TerraformRemoteState;
87
static isStack(x: any): x is TerraformStack;
88
static of(construct: IConstruct): TerraformStack;
89
}
90
```
91
92
[Core Infrastructure](./core-infrastructure.md)
93
94
### Resources and Data Sources
95
96
Terraform resource and data source management with full attribute access and lifecycle controls.
97
98
```typescript { .api }
99
class TerraformResource extends TerraformElement {
100
constructor(scope: Construct, id: string, config: TerraformResourceConfig);
101
getStringAttribute(terraformAttribute: string): string;
102
getNumberAttribute(terraformAttribute: string): number;
103
getListAttribute(terraformAttribute: string): string[];
104
getBooleanAttribute(terraformAttribute: string): IResolvable;
105
getNumberListAttribute(terraformAttribute: string): number[];
106
getStringMapAttribute(terraformAttribute: string): {[key: string]: string};
107
getNumberMapAttribute(terraformAttribute: string): {[key: string]: number};
108
getBooleanMapAttribute(terraformAttribute: string): {[key: string]: boolean};
109
getAnyMapAttribute(terraformAttribute: string): {[key: string]: any};
110
interpolationForAttribute(terraformAttribute: string): IResolvable;
111
importFrom(id: string, provider?: TerraformProvider): void;
112
moveTo(moveTarget: string, index?: string | number): void;
113
moveToId(id: string): void;
114
moveFromId(id: string): void;
115
addMoveTarget(moveTarget: string): void;
116
hasResourceMove(): boolean;
117
static isTerraformResource(x: any): x is TerraformResource;
118
}
119
120
class TerraformDataSource extends TerraformElement {
121
constructor(scope: Construct, id: string, config: TerraformResourceConfig);
122
static isTerraformDataSource(x: any): x is TerraformDataSource;
123
}
124
```
125
126
[Resources and Data Sources](./resources-data-sources.md)
127
128
### Providers and Modules
129
130
Provider configuration and Terraform module integration for external resource management.
131
132
```typescript { .api }
133
abstract class TerraformProvider extends TerraformElement {
134
constructor(scope: Construct, id: string, config: TerraformProviderConfig);
135
readonly terraformResourceType: string;
136
readonly alias?: string;
137
static isTerraformProvider(x: any): x is TerraformProvider;
138
}
139
140
abstract class TerraformModule extends TerraformElement {
141
constructor(scope: Construct, id: string, options: TerraformModuleConfig);
142
interpolationForOutput(moduleOutput: string): IResolvable;
143
getString(output: string): string;
144
addProvider(provider: TerraformProvider | TerraformModuleProvider): void;
145
}
146
```
147
148
[Providers and Modules](./providers-modules.md)
149
150
### Variables and Outputs
151
152
Input variables and output values for parameterizing and exposing infrastructure values.
153
154
```typescript { .api }
155
class TerraformVariable extends TerraformElement {
156
constructor(scope: Construct, id: string, config: TerraformVariableConfig);
157
readonly stringValue: string;
158
readonly numberValue: number;
159
readonly listValue: string[];
160
readonly booleanValue: IResolvable;
161
readonly value: any;
162
addValidation(validation: TerraformVariableValidationConfig): void;
163
}
164
165
class TerraformOutput extends TerraformElement {
166
constructor(scope: Construct, id: string, config: TerraformOutputConfig);
167
readonly value: any;
168
readonly description?: string;
169
readonly sensitive?: boolean;
170
static isTerraformOutput(x: any): x is TerraformOutput;
171
}
172
173
class TerraformLocal extends TerraformElement {
174
constructor(scope: Construct, id: string, expression: any);
175
readonly expression: any;
176
readonly fqn: string;
177
}
178
```
179
180
[Variables and Outputs](./variables-outputs.md)
181
182
### Backend Configuration
183
184
Terraform backend configuration for state management across different storage systems.
185
186
```typescript { .api }
187
abstract class TerraformBackend extends TerraformElement {
188
constructor(scope: Construct, id: string, name: string);
189
abstract getRemoteStateDataSource(scope: Construct, name: string, fromStack: string): TerraformRemoteState;
190
static isBackend(x: any): x is TerraformBackend;
191
}
192
```
193
194
Backend implementations: S3Backend, LocalBackend, RemoteBackend, CloudBackend, AzurermBackend, ConsulBackend, GcsBackend, and more.
195
196
[Backend Configuration](./backend-configuration.md)
197
198
### Token System and Expressions
199
200
Token resolution system for handling unresolved values and creating Terraform expressions.
201
202
```typescript { .api }
203
class Token {
204
static isUnresolved(obj: any): boolean;
205
static asString(value: any, options?: EncodingOptions): string;
206
static asNumber(value: any): number;
207
static asList(value: any, options?: EncodingOptions): string[];
208
static asNumberList(value: any): number[];
209
static asStringMap(value: any, options?: EncodingOptions): {[key: string]: string};
210
static asNumberMap(value: any, options?: EncodingOptions): {[key: string]: number};
211
static asBooleanMap(value: any, options?: EncodingOptions): {[key: string]: boolean};
212
static asAnyMap(value: any, options?: EncodingOptions): {[key: string]: any};
213
static asAny(value: any): IResolvable;
214
static nullValue(): IResolvable;
215
}
216
217
function ref(identifier: string, stack?: TerraformStack): IResolvable;
218
function conditional(condition: Expression, trueValue: Expression, falseValue: Expression): any;
219
function propertyAccess(target: Expression, args: Expression[]): IResolvable;
220
```
221
222
[Token System and Expressions](./tokens-expressions.md)
223
224
### Iterators and Dynamic Blocks
225
226
Iterator support for for_each constructs and dynamic block generation.
227
228
```typescript { .api }
229
abstract class TerraformIterator {
230
static fromList(list: any[]): ListTerraformIterator;
231
static fromMap(map: {[key: string]: any}): MapTerraformIterator;
232
static fromResources(resource: ITerraformResource): ResourceTerraformIterator;
233
getString(attribute: string): string;
234
getNumber(attribute: string): number;
235
dynamic(attributes: {[key: string]: any}): IResolvable;
236
keys(): IResolvable;
237
values(): IResolvable;
238
}
239
```
240
241
[Iterators and Dynamic Blocks](./iterators-dynamic.md)
242
243
### Terraform Functions
244
245
Comprehensive access to Terraform's built-in functions for expressions and computations.
246
247
```typescript { .api }
248
class Fn {
249
static bcrypt(str: string, cost?: number): string;
250
static conditional(condition: any, trueValue: any, falseValue: any): any;
251
static lookup(inputMap: any, key: string, defaultValue?: any): any;
252
static join(separator: string, list: string[]): string;
253
static length(value: any): number;
254
static keys(inputMap: any): string[];
255
static values(inputMap: any): any[];
256
// Plus 100+ additional Terraform functions
257
}
258
```
259
260
[Terraform Functions](./terraform-functions.md)
261
262
### Testing Framework
263
264
Built-in testing utilities for validating CDKTF applications and infrastructure configurations.
265
266
```typescript { .api }
267
class Testing {
268
static app(options?: TestingAppConfig): App;
269
static stubVersion(app: App): App;
270
static fakeCdktfJsonPath(app: App): App;
271
static enableFutureFlags(app: App): App;
272
static synthScope(fn: IScopeCallback): string;
273
static synth(stack: TerraformStack, runValidations?: boolean): string;
274
static synthHcl(stack: TerraformStack, runValidations?: boolean, returnMetadata?: boolean): string;
275
static fullSynth(stack: TerraformStack): string;
276
static renderConstructTree(construct: IConstruct): string;
277
static toHaveDataSourceWithProperties(received: string, resourceType: string, properties?: Record<string, any>): boolean;
278
static toHaveDataSource(received: string, resourceType: string): boolean;
279
static toHaveResourceWithProperties(received: string, resourceType: string, properties?: Record<string, any>): boolean;
280
static toHaveResource(received: string, resourceType: string): boolean;
281
static toHaveProviderWithProperties(received: string, resourceType: string, properties?: Record<string, any>): boolean;
282
static toHaveProvider(received: string, resourceType: string): boolean;
283
static toBeValidTerraform(received: string): boolean;
284
static setupJest(): void;
285
}
286
```
287
288
Testing matchers: `toHaveResource`, `toHaveResourceWithProperties`, `toHaveDataSource`, `toBeValidTerraform`, and more.
289
290
[Testing Framework](./testing.md)
291
292
### Provisioners
293
294
Resource provisioning capabilities for executing scripts and transferring files during resource creation.
295
296
```typescript { .api }
297
interface FileProvisioner {
298
type: "file";
299
source: string;
300
destination: string;
301
connection?: SSHProvisionerConnection | WinrmProvisionerConnection;
302
}
303
304
interface LocalExecProvisioner {
305
type: "local-exec";
306
command: string;
307
workingDir?: string;
308
interpreter?: string[];
309
environment?: {[key: string]: string};
310
}
311
312
interface RemoteExecProvisioner {
313
type: "remote-exec";
314
inline?: string[];
315
script?: string;
316
scripts?: string[];
317
connection: SSHProvisionerConnection | WinrmProvisionerConnection;
318
}
319
```
320
321
[Provisioners](./provisioners.md)
322
323
### Annotations and Aspects
324
325
Construct annotation system for adding metadata and cross-cutting concerns through aspect-oriented programming.
326
327
```typescript { .api }
328
class Annotations {
329
static of(scope: IConstruct): Annotations;
330
addInfo(message: string): void;
331
addWarning(message: string): void;
332
addError(message: string): void;
333
}
334
335
interface IAspect {
336
visit(node: IConstruct): void;
337
}
338
339
class Aspects {
340
static of(scope: IConstruct): Aspects;
341
add(aspect: IAspect): void;
342
readonly all: IAspect[];
343
}
344
```
345
346
[Annotations and Aspects](./annotations-aspects.md)
347
348
## Core Types
349
350
```typescript { .api }
351
interface AppConfig {
352
readonly context?: {[key: string]: any};
353
readonly outdir?: string;
354
readonly stackTraces?: boolean;
355
readonly hclOutput?: boolean;
356
readonly skipBackendValidation?: boolean;
357
readonly skipValidation?: boolean;
358
}
359
360
interface TerraformResourceConfig {
361
readonly terraformResourceType: string;
362
readonly terraformGeneratorMetadata?: TerraformProviderGeneratorMetadata;
363
readonly provider?: TerraformProvider;
364
readonly dependsOn?: ITerraformDependable[];
365
readonly count?: number | TerraformCount;
366
readonly forEach?: ITerraformIterator;
367
readonly lifecycle?: TerraformResourceLifecycle;
368
readonly provisioners?: (FileProvisioner | LocalExecProvisioner | RemoteExecProvisioner)[];
369
readonly connection?: SSHProvisionerConnection | WinrmProvisionerConnection;
370
}
371
372
interface IResolvable {
373
readonly creationStack: string[];
374
resolve(context: IResolveContext): any;
375
toString(): string;
376
}
377
378
interface ITerraformDependable {
379
// Marker interface for dependable resources
380
}
381
382
interface ITerraformAddressable {
383
readonly fqn: string;
384
}
385
386
interface TestingAppConfig {
387
readonly outdir?: string;
388
readonly stackTraces?: boolean;
389
readonly stubVersion?: boolean;
390
readonly enableFutureFlags?: boolean;
391
readonly fakeCdktfJsonPath?: boolean;
392
readonly context?: {[key: string]: any};
393
}
394
395
interface IScopeCallback {
396
(scope: Construct): void;
397
}
398
399
interface EncodingOptions {
400
readonly displayHint?: string;
401
}
402
```