> ## Documentation Index
> Fetch the complete documentation index at: https://cdktn.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Modules - CDK Terrain
> Use both public and private modules in your CDKTN application to reuse existing configurations.
A [Terraform module](https://developer.hashicorp.com/terraform/language/modules) is a single directory that contains one or more configuration files.
Modules let you reuse configurations across projects and teams, saving time, enforcing consistency, and reducing errors. For example, you could create a module to describe the configuration for all of your organization's public website buckets. When you package and share this module, other users can incorporate it into their configurations. As requirements evolve, you can make changes to your module once, release a new version, and apply those changes everywhere that module is used.
You can specify any existing public or private module in your `cdktf.json` file, and CDK Terrain (CDKTN) generates the necessary code bindings for you to use in your application.
## Install Modules
You can use modules from the [Terraform Registry](https://registry.terraform.io/) (or [OpenTofu Registry](https://search.opentofu.org/)) and other sources like GitHub in your application. For example, the following TypeScript project has a `main.ts` file that defines AWS resources and uses the [AWS VPC module](https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/latest).
```ts TypeScript theme={null}
import { Construct } from "constructs";
import { TerraformStack } from "cdktn";
import { AwsProvider } from "@cdktn/provider-aws/lib/aws-provider";
import { Vpc } from "./.gen/modules/terraform-aws-modules/aws/vpc";
export class ModulesStack extends TerraformStack {
constructor(scope: Construct, id: string) {
super(scope, id);
const provider = new AwsProvider(this, "aws", {
region: "us-west-2",
});
new Vpc(this, "MyVpc", {
name: "my-vpc",
cidr: "10.0.0.0/16",
azs: ["us-west-2a", "us-west-2b", "us-west-2c"],
privateSubnets: ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"],
publicSubnets: ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"],
enableNatGateway: true,
});
}
}
```
```java Java theme={null}
import software.constructs.Construct;
import io.cdktn.cdktn.TerraformStack;
import io.cdktn.cdktn.App;
import imports.aws.provider.AwsProvider;
import imports.aws.provider.AwsProviderConfig;
import imports.vpc.Vpc;
import imports.vpc.VpcConfig;
public class MainInstallModules extends TerraformStack {
public MainInstallModules(Construct scope, String id){
super(scope, id);
new AwsProvider(this, "aws", AwsProviderConfig.builder()
.region("us-east-1")
.build()
);
new Vpc(this, "myVpc", VpcConfig.builder()
.name("my-vpc")
.cidr("10.0.0.0/16")
.azs(Arrays.asList("us-west-2a", "us-west-2b", "us-west-2c"))
.privateSubnets(Arrays.asList("10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"))
.publicSubnets(Arrays.asList("10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"))
.enableNatGateway(true)
.build()
);
}
public static void main(String[] args) {
final App app = new App();
new MainInstallModules(app, "hello-terraform");
app.synth();
}
}
```
```python Python theme={null}
from constructs import Construct
from cdktn import App, TerraformStack
from imports.aws.provider import AwsProvider
from imports.vpc import Vpc
class ModuleStack(TerraformStack):
def __init__(self, scope: Construct, id: str):
super().__init__(scope, id)
AwsProvider(self, "aws",
region = "us-east-1",
)
Vpc(self, "MyVpc",
name = "my-vpc",
cidr = "10.0.0.0/16",
azs = ['us-west-2a', 'us-west-2b', 'us-west-2c'],
private_subnets = ['10.0.1.0/24', '10.0.2.0/24', '10.0.3.0/24'],
public_subnets = ['10.0.101.0/24', '10.0.102.0/24', '10.0.103.0/24'],
enable_nat_gateway = True
)
app = App()
ModuleStack(app, "hello-terraform")
app.synth()
```
```csharp C# theme={null}
using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using Io.Cdktn;
using vpc;
namespace Examples
{
class ModuleStack : TerraformStack
{
public ModuleStack(Construct scope, string name) : base(scope, name)
{
// Add this to your project's .csproj file:
//
//
//
new Vpc(this, "vpc", new VpcConfig
{
Name = "my-vpc",
Cidr = "10.0.0.0/16",
Azs = new[] { "us-west-2a", "us-west-2b", "us-west-2c" },
PrivateSubnets = new[] { "10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24" },
PublicSubnets = new[] { "10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24" },
EnableNatGateway = true
});
}
}
}
```
```go Go theme={null}
import (
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
"github.com/open-constructs/cdk-terrain-go/cdktn"
aws "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/provider"
"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/terraform-aws-modules/aws/vpc"
)
func NewModulesStack(scope constructs.Construct, name string) cdktn.TerraformStack {
stack := cdktn.NewTerraformStack(scope, &name)
provider := aws.NewAwsProvider(stack, jsii.String("aws"), &aws.AwsProviderConfig{
Region: jsii.String("us-west-2"),
})
vpc.NewVpc(stack, jsii.String("MyVpc"), &vpc.VpcConfig{
Name: jsii.String("my-vpc"),
Cidr: jsii.String("10.0.0.0/16"),
Azs: jsii.Strings("us-west-2a", "us-west-2b", "us-west-2c"),
PrivateSubnets: jsii.Strings("10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"),
PublicSubnets: jsii.Strings("10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"),
EnableNatGateway: jsii.Bool(true),
})
return stack
}
```
### Add Module to `cdktf.json`
To use a module in your application, you must first add it to the `terraformModules` array in the [`cdktf.json` configuration file](/create-and-deploy/configuration-file).
To add a module from the Terraform Registry or a private registry, provide a fully qualified name: `registry-namespace/module-name`.
```json theme={null}
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"terraformProviders": [],
"terraformModules": [
{
"name": "vpc",
"source": "terraform-aws-modules/vpc/aws",
"version": "~> 3.0"
}
]
}
```
For local modules, use the object format.
```json theme={null}
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"terraformProviders": [],
"terraformModules": [
{
"name": "my-local-module",
"source": "./path/to/local/terraform/module"
}
]
}
```
For performance reasons, we don't automatically generate bindings for submodules. To generate bindings for submodules, specify the module source as `terraform-aws-modules/vpc/aws//submodules/vpc-endpoints`, where after the `//` is the path to the submodule in the modules repository. Refer to [the Terraform source specification](https://developer.hashicorp.com/terraform/language/modules/sources) for more details.
When you are using local modules that reference other local modules you need to add all referenced modules to the `terraformModules` array.
### Generate Module Bindings
Go to the working directory and run `cdktn get`. CDKTN automatically creates the appropriate module bindings in the `./.gen` directory for you to use in your application.
## Configure Modules
You can configure modules in the same way as [resources](/concepts/resources), with one exception.
For module inputs that use the `map` type, like `map(string)` or `list(map(string))`, you must specify the map values as strings. You must also ensure that the keys follow the required format listed in the module's documentation. For example, the module may specify that the keys must be in snake case.
## Work with Module Outputs
Modules often return data that you can use as inputs to other modules or resources. When this data is only available after Terraform (or OpenTofu) applies the configuration, you must use [Terraform Outputs](/concepts/variables-and-outputs#output-values).
### Examples
The following example uses a local module and references its output as a Terraform output.
```ts TypeScript theme={null}
import { Construct } from "constructs";
import { TerraformStack } from "cdktn";
import { AwsProvider } from "@cdktn/provider-aws/lib/aws-provider";
import { TerraformOutput } from "cdktn";
// This module can come from a registry or through a local / remote reference
import { MyLocalModule } from "./.gen/modules/my-local-module";
export class ModulesStack extends TerraformStack {
constructor(scope: Construct, id: string) {
super(scope, id);
const provider = new AwsProvider(this, "aws", {
region: "us-west-2",
});
const localModule = new MyLocalModule(this, "local-module", {
ipAddress: "127.0.0.1",
});
new TerraformOutput(this, "dns-server", {
value: localModule.dnsServerOutput,
});
}
}
```
```python Python theme={null}
from constructs import Construct
from cdktn import App, TerraformStack, TerraformOutput
# This module can come from a registry or through a local / remote reference
from imports.my_local_module import MyLocalModule
class ModuleWithOutputStack(TerraformStack):
def __init__(self, scope: Construct, ns: str):
super().__init__(scope, ns)
localModule = MyLocalModule(self, "local-module", ip_address='127.0.0.1')
TerraformOutput(self, "dns-server", value=localModule.dns_server_output)
app = App()
ModuleWithOutputStack(app, "hello-terraform")
app.synth()
```
```java Java theme={null}
import io.cdktn.cdktn.TerraformOutput;
import io.cdktn.cdktn.TerraformOutputConfig;
import io.cdktn.cdktn.TerraformStack;
import software.constructs.Construct;
import imports.my_local_module.MyLocalModule;
import imports.my_local_module.MyLocalModuleConfig;
public class MainModuleExample extends TerraformStack {
public MainModuleExample(Construct scope, String id){
super(scope, id);
MyLocalModule localModule = new MyLocalModule(this, "local-module", MyLocalModuleConfig.builder()
.ipAddress("127.0.0.1")
.build()
);
new TerraformOutput(this, "dns-server", TerraformOutputConfig.builder()
.value(localModule.getDnsServerOutputOutput())
.build()
);
}
}
```
```csharp C# theme={null}
using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using Io.Cdktn;
using my_local_module;
namespace Examples
{
class LocalModuleStack : TerraformStack
{
public LocalModuleStack(Construct scope, string name) : base(scope, name)
{
// Add this to your project's .csproj file:
//
//
//
MyLocalModule localModule = new MyLocalModule(this, "local-module", new MyLocalModuleConfig
{
IpAddress = "127.0.0.1",
});
new TerraformOutput(this, "dns-server", new TerraformOutputConfig
{
Value = localModule.DnsServerOutput
});
}
}
}
```
```go Go theme={null}
import (
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
"github.com/open-constructs/cdk-terrain-go/cdktn"
// This module can come from a registry or through a local / remote reference
"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/my_local_module"
)
func NewModulesStack(scope constructs.Construct, name string) cdktn.TerraformStack {
stack := cdktn.NewTerraformStack(scope, &name)
localModule := my_local_module.NewMyLocalModule(stack, jsii.String("local-module"), &my_local_module.MyLocalModuleConfig{
IpAddress: jsii.String("127.0.0.1"),
})
cdktn.NewTerraformOutput(stack, jsii.String("dns-server"), &cdktn.TerraformOutputConfig{
Value: localModule.DnsServerOutput(),
})
return stack
}
```
## Create Modules
While we generally recommend generating code bindings for modules, you can also use the `TerraformHclModule` class to reference any module that Terraform supports. Both methods create identical synthesized Terraform configuration files, but using `TerraformHclModule` does not generate any types or type-safe inputs or outputs.
The following example uses `TerraformHclModule` to import an AWS module.
```ts TypeScript theme={null}
import { Construct } from "constructs";
import { TerraformStack } from "cdktn";
import { AwsProvider } from "@cdktn/provider-aws/lib/aws-provider";
import { TerraformHclModule } from "cdktn";
export class ModulesStack extends TerraformStack {
constructor(scope: Construct, id: string) {
super(scope, id);
const provider = new AwsProvider(this, "aws", {
region: "us-west-2",
});
new TerraformHclModule(this, "Vpc", {
source: "terraform-aws-modules/vpc/aws",
// Note: variables has no types for its inputs.
// When using this for other modules consult the docs of the module
// to ensure the arguments are correct.
variables: {
name: "my-vpc",
cidr: "10.0.0.0/16",
azs: ["us-west-2a", "us-west-2b", "us-west-2c"],
private_subnets: ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"],
public_subnets: ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"],
enable_nat_gateway: true,
},
providers: [provider],
});
}
}
```
```java Java theme={null}
AwsProvider provider = new AwsProvider(stack, "provider", AwsProviderConfig.builder()
.region("us-east-1")
.build()
);
TerraformHclModule module = new TerraformHclModule(stack, "Vpc", TerraformHclModuleConfig.builder()
.source("terraform-aws-modules/vpc/aws")
// Note: variables has no types for its inputs.
// When using this for other modules consult the docs of the module
// to ensure the arguments are correct.
.variables(new HashMap(){{
put("name", "my-vpc");
put("cidr", "10.0.0.0/16");
put("azs", Arrays.asList("us-west-2a", "us-west-2b", "us-west-2c"));
put("private_subnets", Arrays.asList("10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"));
put("public_subnets", Arrays.asList("10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"));
put("enable_nat_gateway", true);
}})
.providers(Arrays.asList(provider))
.build()
);
```
```python Python theme={null}
class HclModuleStack(TerraformStack):
def __init__(self, scope: Construct, id: str):
super().__init__(scope, id)
provider = AwsProvider(self, "provider",
region = "us-east-1",
)
module = TerraformHclModule(self, "Vpc",
source = "terraform-aws-modules/vpc/aws",
# Note: variables has no types for its inputs.
# When using this for other modules consult the docs of the module
# to ensure the arguments are correct.
variables = {
"name": "my-vpc",
"cidr": "10.0.0.0/16",
"azs": ["us-west-2a", "us-west-2b", "us-west-2c"],
"private_subnets": ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"],
"public_subnets": ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"],
"enable_nat_gateway": True,
},
providers = [provider]
)
app = App()
HclModuleStack(app, "hello-terraform")
app.synth()
```
```csharp C# theme={null}
using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using Io.Cdktn;
using aws.Provider;
namespace Examples
{
class TerraformHclModuleStack : TerraformStack
{
public TerraformHclModuleStack(Construct scope, string name) : base(scope, name)
{
AwsProvider provider = new AwsProvider(this, "aws", new AwsProviderConfig
{
Region = "eu-east-1"
});
new TerraformHclModule(this, "vpc", new TerraformHclModuleConfig
{
Source = "terraform-aws-modules/vpc/aws",
// Note: Variables has no types for its inputs.
// When using this for other modules consult the docs of the module
// to ensure the arguments are correct.
Variables = new Dictionary {
{ "name", "my-vpc" },
{ "cidr", "10.0.0.0/16" },
{ "azs", new [] { "us-west-2a", "us-west-2b", "us-west-2c" } },
{ "private_subnets", new [] { "10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24" } },
{ "public_subnets", new [] { "10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24" } },
{ "enable_nat_gateway", true }
},
Providers = new[] { provider }
});
}
}
}
```
```go Go theme={null}
import (
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
"github.com/open-constructs/cdk-terrain-go/cdktn"
aws "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/provider"
)
func NewModulesStack(scope constructs.Construct, name string) cdktn.TerraformStack {
stack := cdktn.NewTerraformStack(scope, &name)
provider := aws.NewAwsProvider(stack, jsii.String("aws"), &aws.AwsProviderConfig{
Region: jsii.String("us-west-2"),
})
// create a list with the AWS provider construct to pass to the module
providers := append(make([]interface{}, 0), provider)
cdktn.NewTerraformHclModule(stack, jsii.String("Vpc"), &cdktn.TerraformHclModuleConfig{
Source: jsii.String("terraform-aws-modules/vpc/aws"),
// Note: Variables has no types for its inputs.
// When using this for other modules consult the docs of the module
// to ensure the arguments are correct.
Variables: &map[string]interface{}{
"name": "my-vpc",
"cidr": "10.0.0.0/16",
"azs": []string{"us-west-2a", "us-west-2b", "us-west-2c"},
"private_subnets": []string{"10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"},
"public_subnets": []string{"10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"},
"enable_nat_gateway": true,
},
Providers: &providers,
})
return stack
}
```