0
# Core Infrastructure
1

2
Core infrastructure components provide the foundational classes for building CDKTF applications, including the root App construct and TerraformStack containers for organizing resources.
3

4
## Capabilities
5

6
### App Class
7

8
The root construct representing a CDKTF application. All stacks must be contained within an App.
9

10
```typescript { .api }
11
/**
12
 * The root construct representing a CDKTF application
13
 */
14
class App extends Construct {
15
  /**
16
   * Create a new CDKTF app
17
   * @param config - Optional configuration for the app
18
   */
19
  constructor(config?: AppConfig);
20

21
  /**
22
   * Synthesize all resources to the output directory
23
   */
24
  synth(): void;
25

26
  /**
27
   * Create a cross-stack reference between stacks
28
   * @param fromStack - The stack making the reference
29
   * @param toStack - The stack being referenced
30
   * @param identifier - The identifier for the reference
31
   * @returns Reference string for use in the fromStack
32
   */
33
  crossStackReference(fromStack: TerraformStack, toStack: TerraformStack, identifier: string): string;
34

35
  /**
36
   * Check if a construct is an App
37
   */
38
  static isApp(x: any): x is App;
39

40
  /**
41
   * Get the App instance from any construct in the tree
42
   */
43
  static of(construct: IConstruct): App;
44

45
  readonly outdir: string;
46
  readonly targetStackId?: string;
47
  readonly context: {[key: string]: any};
48
}
49
```
50

51
**Usage Example:**
52

53
```typescript
54
import { App, TerraformStack } from "cdktf";
55

56
// Create app with default settings
57
const app = new App();
58

59
// Create app with custom configuration
60
const customApp = new App({
61
  outdir: "./terraform-output",
62
  context: {
63
    "feature:enableNewBehavior": true
64
  }
65
});
66

67
// Synthesize to generate Terraform configuration
68
app.synth();
69
```
70

71
### TerraformStack Class
72

73
A container for Terraform resources, equivalent to a Terraform configuration. Each stack becomes a separate Terraform workspace.
74

75
```typescript { .api }
76
/**
77
 * Container for Terraform resources, equivalent to a Terraform configuration
78
 */
79
class TerraformStack extends Construct {
80
  /**
81
   * Create a new Terraform stack
82
   * @param scope - The parent construct (usually an App)
83
   * @param id - The stack identifier
84
   */
85
  constructor(scope: Construct, id: string);
86

87
  /**
88
   * Synthesize the stack to Terraform JSON format
89
   * @returns Terraform configuration as JSON
90
   */
91
  toTerraform(): any;
92

93
  /**
94
   * Synthesize the stack to HCL format
95
   * @returns Terraform configuration as HCL
96
   */
97
  toHclTerraform(): any;
98

99
  /**
100
   * Add an override to the synthesized Terraform configuration
101
   * @param path - JSON path to override (e.g., "resource.aws_instance.example.tags")
102
   * @param value - Value to set at the path
103
   */
104
  addOverride(path: string, value: any): void;
105

106
  /**
107
   * Get the logical ID for a Terraform element within this stack
108
   * @param tfElement - The element to get the ID for
109
   * @returns Logical ID string
110
   */
111
  getLogicalId(tfElement: ITerraformAddressable): string;
112

113
  /**
114
   * Run all validations for the stack
115
   */
116
  runAllValidations(): void;
117

118
  /**
119
   * Ensure a backend exists for this stack
120
   * @returns The backend instance
121
   */
122
  ensureBackendExists(): TerraformBackend;
123

124
  /**
125
   * Add a dependency on another stack
126
   * @param dependency - The stack this stack depends on
127
   */
128
  addDependency(dependency: TerraformStack): void;
129

130
  /**
131
   * Check if a construct is a TerraformStack
132
   */
133
  static isStack(x: any): x is TerraformStack;
134

135
  /**
136
   * Get the TerraformStack from any construct in the stack tree
137
   */
138
  static of(construct: IConstruct): TerraformStack;
139

140
  readonly dependencies: TerraformStack[];
141
  readonly synthesizer: IStackSynthesizer;
142
}
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { App, TerraformStack } from "cdktf";
149
import { Construct } from "constructs";
150

151
class MyInfrastructureStack extends TerraformStack {
152
  constructor(scope: Construct, id: string) {
153
    super(scope, id);
154

155
    // Add resources, data sources, outputs here
156
  }
157
}
158

159
// Create multiple stacks
160
const app = new App();
161
const networkingStack = new MyInfrastructureStack(app, "networking");
162
const computeStack = new MyInfrastructureStack(app, "compute");
163

164
// Add stack dependency
165
computeStack.addDependency(networkingStack);
166

167
// Add configuration overrides
168
networkingStack.addOverride("terraform.required_version", ">= 1.0");
169

170
// Synthesize all stacks
171
app.synth();
172
```
173

174
### TerraformElement Class
175

176
Abstract base class for all Terraform elements (resources, data sources, providers, etc.).
177

178
```typescript { .api }
179
/**
180
 * Base class for all Terraform elements
181
 */
182
abstract class TerraformElement extends Construct {
183
  /**
184
   * Create a new Terraform element
185
   * @param scope - The parent construct
186
   * @param id - Element identifier
187
   * @param elementType - Type of Terraform element
188
   */
189
  constructor(scope: Construct, id: string, elementType?: string);
190

191
  /**
192
   * Synthesize element to Terraform JSON format
193
   * @returns JSON representation
194
   */
195
  abstract toTerraform(): any;
196

197
  /**
198
   * Synthesize element to HCL format
199
   * @returns HCL representation
200
   */
201
  toHclTerraform(): any;
202

203
  /**
204
   * Get metadata for the element
205
   * @returns Metadata object
206
   */
207
  toMetadata(): any;
208

209
  /**
210
   * Override synthesized attributes
211
   * @param path - Path to attribute
212
   * @param value - Value to set
213
   */
214
  addOverride(path: string, value: any): void;
215

216
  /**
217
   * Override the logical ID for this element
218
   * @param newLogicalId - New logical ID to use
219
   */
220
  overrideLogicalId(newLogicalId: string): void;
221

222
  /**
223
   * Reset the logical ID override
224
   */
225
  resetOverrideLogicalId(): void;
226

227
  /**
228
   * The fully-qualified name of this element type
229
   */
230
  readonly fqn: string;
231

232
  /**
233
   * Unique identifier for this element
234
   */
235
  readonly friendlyUniqueId: string;
236

237
  /**
238
   * The stack this element belongs to
239
   */
240
  readonly cdktfStack: TerraformStack;
241

242
  /**
243
   * The Terraform resource/element type
244
   */
245
  readonly terraformResourceType: string;
246

247
  /**
248
   * Generator metadata for this element
249
   */
250
  readonly terraformGeneratorMetadata?: TerraformProviderGeneratorMetadata;
251
}
252
```
253

254
## Configuration Interfaces
255

256
```typescript { .api }
257
interface AppConfig {
258
  /**
259
   * Additional context values to make available to the app
260
   */
261
  readonly context?: {[key: string]: any};
262

263
  /**
264
   * Output directory for generated Terraform files
265
   * @default "."
266
   */
267
  readonly outdir?: string;
268

269
  /**
270
   * Include stack traces in error messages
271
   * @default false
272
   */
273
  readonly stackTraces?: boolean;
274

275
  /**
276
   * Generate HCL output instead of JSON
277
   * @default false
278
   */
279
  readonly hclOutput?: boolean;
280

281
  /**
282
   * Skip backend validation during synthesis
283
   * @default false
284
   */
285
  readonly skipBackendValidation?: boolean;
286

287
  /**
288
   * Skip all validation during synthesis
289
   * @default false
290
   */
291
  readonly skipValidation?: boolean;
292
}
293

294
interface IStackSynthesizer {
295
  /**
296
   * Synthesize the associated stack to the session
297
   * @param session - The synthesis session
298
   */
299
  synthesize(session: ISynthesisSession): void;
300
}
301

302
interface ISynthesisSession {
303
  /**
304
   * The output directory for synthesis artifacts
305
   */
306
  readonly outdir: string;
307

308
  /**
309
   * Whether to skip validation
310
   */
311
  readonly skipValidation: boolean;
312
}
313

314
interface TerraformProviderGeneratorMetadata {
315
  /**
316
   * The version of the provider
317
   */
318
  readonly providerName: string;
319

320
  /**
321
   * The version of the provider
322
   */
323
  readonly providerVersion?: string;
324

325
  /**
326
   * The version of the generator used
327
   */
328
  readonly providerVersionConstraint?: string;
329
}
330
```