0
# Backend Configuration
1

2
Terraform backend configuration for state management across different storage systems, enabling team collaboration and remote state sharing.
3

4
## Capabilities
5

6
### TerraformBackend Class
7

8
Abstract base class for all Terraform backend implementations, providing state storage and locking capabilities.
9

10
```typescript { .api }
11
/**
12
 * Base class for all Terraform backends
13
 */
14
abstract class TerraformBackend extends TerraformElement {
15
  /**
16
   * Create a new Terraform backend
17
   * @param scope - The parent construct
18
   * @param id - Backend identifier
19
   * @param name - Backend type name
20
   */
21
  constructor(scope: Construct, id: string, name: string);
22

23
  /**
24
   * Get a remote state data source for this backend
25
   * @param scope - The scope for the data source
26
   * @param name - Name for the data source
27
   * @param fromStack - Stack name to read state from
28
   * @returns Remote state data source
29
   */
30
  abstract getRemoteStateDataSource(
31
    scope: Construct,
32
    name: string,
33
    fromStack: string
34
  ): TerraformRemoteState;
35

36
  /**
37
   * Backend type name
38
   */
39
  readonly name: string;
40

41
  /**
42
   * Check if a construct is a TerraformBackend
43
   */
44
  static isBackend(x: any): x is TerraformBackend;
45
}
46
```
47

48
### Backend Implementations
49

50
#### S3Backend
51

52
AWS S3 backend for storing Terraform state in Amazon S3 with DynamoDB locking.
53

54
```typescript { .api }
55
/**
56
 * AWS S3 backend configuration
57
 */
58
class S3Backend extends TerraformBackend {
59
  constructor(scope: Construct, config: S3BackendConfig);
60

61
  readonly bucket: string;
62
  readonly key: string;
63
  readonly region: string;
64
  readonly dynamodbTable?: string;
65
  readonly encrypt?: boolean;
66
}
67
```
68

69
**Usage Example:**
70

71
```typescript
72
import { S3Backend } from "cdktf";
73

74
const backend = new S3Backend(this, {
75
  bucket: "my-terraform-state-bucket",
76
  key: "infrastructure/terraform.tfstate",
77
  region: "us-east-1",
78
  dynamodbTable: "terraform-state-lock",
79
  encrypt: true
80
});
81
```
82

83
#### LocalBackend
84

85
Local file system backend for storing state locally.
86

87
```typescript { .api }
88
/**
89
 * Local file backend configuration
90
 */
91
class LocalBackend extends TerraformBackend {
92
  constructor(scope: Construct, config: LocalBackendConfig);
93

94
  readonly path?: string;
95
  readonly workspaceDir?: string;
96
}
97
```
98

99
#### RemoteBackend
100

101
Terraform Cloud/Enterprise backend for managed state storage.
102

103
```typescript { .api }
104
/**
105
 * Terraform Cloud/Enterprise backend configuration
106
 */
107
class RemoteBackend extends TerraformBackend {
108
  constructor(scope: Construct, config: RemoteBackendConfig);
109

110
  readonly hostname?: string;
111
  readonly organization: string;
112
  readonly token?: string;
113
  readonly workspaces: RemoteBackendWorkspaces;
114
}
115
```
116

117
#### CloudBackend
118

119
Terraform Cloud backend with simplified configuration.
120

121
```typescript { .api }
122
/**
123
 * Terraform Cloud backend configuration
124
 */
125
class CloudBackend extends TerraformBackend {
126
  constructor(scope: Construct, config: CloudBackendConfig);
127

128
  readonly organization: string;
129
  readonly hostname?: string;
130
  readonly token?: string;
131
  readonly workspaces: CloudBackendWorkspaces;
132
}
133
```
134

135
#### Additional Backends
136

137
Other backend implementations follow similar patterns:
138

139
- **AzurermBackend** - Azure Storage backend
140
- **ConsulBackend** - HashiCorp Consul backend
141
- **GcsBackend** - Google Cloud Storage backend
142
- **HttpBackend** - HTTP backend
143
- **PgBackend** - PostgreSQL backend
144
- **SwiftBackend** - OpenStack Swift backend
145

146
**Usage Examples:**
147

148
```typescript
149
import {
150
  AzurermBackend,
151
  GcsBackend,
152
  ConsulBackend
153
} from "cdktf";
154

155
// Azure Storage backend
156
const azureBackend = new AzurermBackend(this, {
157
  resourceGroupName: "tfstate-rg",
158
  storageAccountName: "tfstatestorage",
159
  containerName: "tfstate",
160
  key: "prod.terraform.tfstate"
161
});
162

163
// Google Cloud Storage backend
164
const gcsBackend = new GcsBackend(this, {
165
  bucket: "my-tf-state-bucket",
166
  prefix: "terraform/state"
167
});
168

169
// Consul backend
170
const consulBackend = new ConsulBackend(this, {
171
  address: "consul.example.com",
172
  scheme: "https",
173
  path: "terraform/state/prod"
174
});
175
```
176

177
### TerraformRemoteState Class
178

179
Data source for reading state from remote backends, enabling cross-stack and cross-workspace references.
180

181
```typescript { .api }
182
/**
183
 * Remote state data source for cross-stack references
184
 */
185
class TerraformRemoteState extends TerraformDataSource {
186
  /**
187
   * Create a remote state data source
188
   * @param scope - The parent construct
189
   * @param id - Data source identifier
190
   * @param config - Remote state configuration
191
   */
192
  constructor(scope: Construct, id: string, config: TerraformRemoteStateConfig);
193

194
  /**
195
   * Get an output value from the remote state
196
   * @param output - Name of the output
197
   * @returns Output value as string
198
   */
199
  getString(output: string): string;
200

201
  /**
202
   * Get a list output value from the remote state
203
   * @param output - Name of the output
204
   * @returns Output value as string array
205
   */
206
  getList(output: string): string[];
207

208
  /**
209
   * Get a number output value from the remote state
210
   * @param output - Name of the output
211
   * @returns Output value as number
212
   */
213
  getNumber(output: string): number;
214

215
  /**
216
   * Get a boolean output value from the remote state
217
   * @param output - Name of the output
218
   * @returns Output value as boolean
219
   */
220
  getBoolean(output: string): boolean;
221

222
  /**
223
   * Remote backend configuration
224
   */
225
  readonly backend: string;
226

227
  /**
228
   * Backend-specific configuration
229
   */
230
  readonly config: {[key: string]: any};
231

232
  /**
233
   * Defaults for undefined outputs
234
   */
235
  readonly defaults?: {[key: string]: any};
236

237
  /**
238
   * Workspace to read from
239
   */
240
  readonly workspace?: string;
241
}
242
```
243

244
**Usage Examples:**
245

246
```typescript
247
import { TerraformRemoteState } from "cdktf";
248

249
// Read from S3 backend
250
const networkingState = new TerraformRemoteState(this, "networking", {
251
  backend: "s3",
252
  config: {
253
    bucket: "company-terraform-state",
254
    key: "networking/terraform.tfstate",
255
    region: "us-east-1"
256
  }
257
});
258

259
// Use remote state outputs
260
const vpcId = networkingState.getString("vpc_id");
261
const privateSubnets = networkingState.getList("private_subnet_ids");
262

263
// Create resources using remote state
264
new AwsInstance(this, "app-server", {
265
  ami: "ami-12345678",
266
  instanceType: "t2.micro",
267
  subnetId: privateSubnets[0],
268
  vpcSecurityGroupIds: [securityGroup.id]
269
});
270

271
// Read from Terraform Cloud
272
const sharedState = new TerraformRemoteState(this, "shared", {
273
  backend: "remote",
274
  config: {
275
    organization: "my-org",
276
    workspaces: {
277
      name: "shared-infrastructure"
278
    }
279
  }
280
});
281

282
const dbEndpoint = sharedState.getString("database_endpoint");
283
const cacheCluster = sharedState.getString("cache_cluster_endpoint");
284
```
285

286
## Configuration Interfaces
287

288
```typescript { .api }
289
interface S3BackendConfig {
290
  readonly bucket: string;
291
  readonly key: string;
292
  readonly region: string;
293
  readonly accessKey?: string;
294
  readonly secretKey?: string;
295
  readonly sessionToken?: string;
296
  readonly profile?: string;
297
  readonly sharedCredentialsFile?: string;
298
  readonly dynamodbTable?: string;
299
  readonly dynamodbEndpoint?: string;
300
  readonly encrypt?: boolean;
301
  readonly kmsKeyId?: string;
302
  readonly roleArn?: string;
303
  readonly assumeRolePolicy?: string;
304
  readonly externalId?: string;
305
  readonly sessionName?: string;
306
  readonly workspaceKeyPrefix?: string;
307
}
308

309
interface LocalBackendConfig {
310
  readonly path?: string;
311
  readonly workspaceDir?: string;
312
}
313

314
interface RemoteBackendConfig {
315
  readonly hostname?: string;
316
  readonly organization: string;
317
  readonly token?: string;
318
  readonly workspaces: RemoteBackendWorkspaces;
319
}
320

321
interface RemoteBackendWorkspaces {
322
  readonly name?: string;
323
  readonly prefix?: string;
324
}
325

326
interface CloudBackendConfig {
327
  readonly organization: string;
328
  readonly hostname?: string;
329
  readonly token?: string;
330
  readonly workspaces: CloudBackendWorkspaces;
331
}
332

333
interface CloudBackendWorkspaces {
334
  readonly name?: string;
335
  readonly tags?: string[];
336
  readonly project?: string;
337
}
338

339
interface AzurermBackendConfig {
340
  readonly storageAccountName: string;
341
  readonly containerName: string;
342
  readonly key: string;
343
  readonly resourceGroupName?: string;
344
  readonly accessKey?: string;
345
  readonly sasToken?: string;
346
  readonly clientId?: string;
347
  readonly clientSecret?: string;
348
  readonly tenantId?: string;
349
  readonly subscriptionId?: string;
350
  readonly msiEndpoint?: string;
351
  readonly useAzureadAuth?: boolean;
352
  readonly useMsi?: boolean;
353
}
354

355
interface GcsBackendConfig {
356
  readonly bucket: string;
357
  readonly prefix?: string;
358
  readonly credentials?: string;
359
  readonly accessToken?: string;
360
  readonly impersonateServiceAccount?: string;
361
  readonly impersonateServiceAccountDelegates?: string[];
362
}
363

364
interface TerraformRemoteStateConfig {
365
  readonly backend: string;
366
  readonly workspace?: string;
367
  readonly config?: {[key: string]: any};
368
  readonly defaults?: {[key: string]: any};
369
}
370
```