Import Terraform Modules
Leverage the module ecosystem
Pulumi can directly use existing Terraform modules from the Terraform Registry, private registries, or local sources. This allows you to access thousands of existing modules without rewriting them in Pulumi.
Add Terraform modules
Use the pulumi package add command to add Terraform modules to your project:
# Add a module from the Terraform Registry
$ pulumi package add terraform-module terraform-aws-modules/vpc/aws 6.0.0 vpc
# Add a local module
$ pulumi package add terraform-module ./path/to/module localmod
Example: AWS VPC module
Let’s use the popular AWS vpc module to create a VPC with subnets, and then deploy an EC2 instance in that VPC:
First, create a new Pulumi program:
$ mkdir pulumi-terraform-modules-test && cd pulumi-terraform-modules-test
$ pulumi new aws-typescript --yes
Next, add the VPC module:
$ pulumi package add terraform-module terraform-aws-modules/vpc/aws 6.0.0 vpc
Then use it in your Pulumi program:
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as vpc from "@pulumi/vpc";
// Use the Terraform VPC module
const myVpc = new vpc.Module("my-vpc", {
name: "my-vpc",
cidr: "10.0.0.0/16",
azs: ["us-west-2a", "us-west-2b", "us-west-2c"],
public_subnets: ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"],
private_subnets: ["10.0.10.0/24", "10.0.11.0/24", "10.0.12.0/24"],
enable_nat_gateway: true,
enable_vpn_gateway: true,
tags: {
Terraform: "true",
Environment: "dev",
},
});
// Create a security group
const webSg = new aws.ec2.SecurityGroup("web-sg", {
name: "web-sg",
description: "Security group for web servers",
vpcId: myVpc.vpc_id.apply(id => id!),
ingress: [
{
description: "HTTP",
fromPort: 80,
toPort: 80,
protocol: "tcp",
cidrBlocks: ["0.0.0.0/0"],
},
{
description: "SSH",
fromPort: 22,
toPort: 22,
protocol: "tcp",
cidrBlocks: ["0.0.0.0/0"],
},
],
egress: [
{
fromPort: 0,
toPort: 0,
protocol: "-1",
cidrBlocks: ["0.0.0.0/0"],
},
],
});
// Get the latest Amazon Linux 2 AMI
const amazonLinux = aws.ec2.getAmiOutput({
mostRecent: true,
owners: ["amazon"],
filters: [
{
name: "name",
values: ["amzn2-ami-hvm-*-x86_64-gp2"],
},
],
});
// Create an EC2 instance in the VPC
const webServer = new aws.ec2.Instance("web-server", {
ami: amazonLinux.id,
instanceType: "t3.micro",
subnetId: myVpc.public_subnets.apply(subnets => subnets![0]),
vpcSecurityGroupIds: [webSg.id],
associatePublicIpAddress: true,
userData: `#!/bin/bash
yum update -y
yum install -y httpd
systemctl start httpd
systemctl enable httpd
echo "<h1>Hello from Pulumi and Terraform modules!</h1>" > /var/www/html/index.html
`,
tags: {
Name: "web-server",
Environment: "dev",
},
});
// Output important information
export const vpcId = myVpc.vpc_id;
export const instanceId = webServer.id;
export const publicIp = webServer.publicIp;
export const websiteUrl = pulumi.interpolate`http://${webServer.publicIp}`;
First, create a new Pulumi program:
$ mkdir pulumi-terraform-modules-test && cd pulumi-terraform-modules-test
$ pulumi new aws-python --yes
Next, add the VPC module:
$ pulumi package add terraform-module terraform-aws-modules/vpc/aws 6.0.0 vpc
Then use it in your Pulumi program:
import pulumi
import pulumi_aws as aws
import pulumi_vpc as vpc
# Use the Terraform VPC module
my_vpc = vpc.Module("my-vpc",
name="my-vpc",
cidr="10.0.0.0/16",
azs=["us-west-2a", "us-west-2b", "us-west-2c"],
public_subnets=["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"],
private_subnets=["10.0.10.0/24", "10.0.11.0/24", "10.0.12.0/24"],
enable_nat_gateway=True,
enable_vpn_gateway=True,
tags={
"Terraform": "true",
"Environment": "dev",
}
)
# Create a security group
web_sg = aws.ec2.SecurityGroup("web-sg",
name="web-sg",
description="Security group for web servers",
vpc_id=my_vpc.vpc_id.apply(lambda id: id),
ingress=[
{
"description": "HTTP",
"from_port": 80,
"to_port": 80,
"protocol": "tcp",
"cidr_blocks": ["0.0.0.0/0"],
},
{
"description": "SSH",
"from_port": 22,
"to_port": 22,
"protocol": "tcp",
"cidr_blocks": ["0.0.0.0/0"],
},
],
egress=[
{
"from_port": 0,
"to_port": 0,
"protocol": "-1",
"cidr_blocks": ["0.0.0.0/0"],
}
]
)
# Get the latest Amazon Linux 2 AMI
amazon_linux = aws.ec2.get_ami(
most_recent=True,
owners=["amazon"],
filters=[
{
"name": "name",
"values": ["amzn2-ami-hvm-*-x86_64-gp2"],
}
]
)
# Create an EC2 instance in the VPC
web_server = aws.ec2.Instance("web-server",
ami=amazon_linux.id,
instance_type="t3.micro",
subnet_id=my_vpc.public_subnets.apply(lambda subnets: subnets[0]),
vpc_security_group_ids=[web_sg.id],
associate_public_ip_address=True,
user_data="""#!/bin/bash
yum update -y
yum install -y httpd
systemctl start httpd
systemctl enable httpd
echo "<h1>Hello from Pulumi and Terraform modules!</h1>" > /var/www/html/index.html
""",
tags={
"Name": "web-server",
"Environment": "dev",
}
)
# Output important information
pulumi.export("vpcId", my_vpc.vpc_id)
pulumi.export("instanceId", web_server.id)
pulumi.export("publicIp", web_server.public_ip)
pulumi.export("websiteUrl", pulumi.Output.format("http://{0}", web_server.public_ip))
First, create a new Pulumi program:
$ mkdir pulumi-terraform-modules-test && cd pulumi-terraform-modules-test
$ pulumi new aws-go --yes
Next, add the VPC module:
$ pulumi package add terraform-module terraform-aws-modules/vpc/aws 6.0.0 vpc
Then use it in your Pulumi program:
package main
import (
"github.com/pulumi/pulumi-aws/sdk/v6/go/aws/ec2"
vpc "github.com/pulumi/pulumi-terraform-module/sdks/go/vpc/v6/vpc"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
// Use the Terraform VPC module
myVpc, err := vpc.NewModule(ctx, "my-vpc", &vpc.ModuleArgs{
Name: pulumi.String("my-vpc"),
Cidr: pulumi.String("10.0.0.0/16"),
Azs: pulumi.StringArray{pulumi.String("us-west-2a"), pulumi.String("us-west-2b"), pulumi.String("us-west-2c")},
Private_subnets: pulumi.StringArray{pulumi.String("10.0.1.0/24"), pulumi.String("10.0.2.0/24"), pulumi.String("10.0.3.0/24")},
Public_subnets: pulumi.StringArray{pulumi.String("10.0.10.0/24"), pulumi.String("10.0.11.0/24"), pulumi.String("10.0.12.0/24")},
Enable_nat_gateway: pulumi.Bool(true),
Enable_vpn_gateway: pulumi.Bool(true),
Tags: pulumi.StringMap{
"Terraform": pulumi.String("true"),
"Environment": pulumi.String("dev"),
},
})
if err != nil {
return err
}
// Get the latest Amazon Linux 2 AMI
amazonLinux, err := ec2.LookupAmi(ctx, &ec2.LookupAmiArgs{
MostRecent: pulumi.BoolRef(true),
Owners: []string{"amazon"},
Filters: []ec2.GetAmiFilter{
{
Name: "name",
Values: []string{"amzn2-ami-hvm-*-x86_64-gp2"},
},
},
})
if err != nil {
return err
}
// Create a security group
webSg, err := ec2.NewSecurityGroup(ctx, "web-sg", &ec2.SecurityGroupArgs{
Name: pulumi.String("web-sg"),
Description: pulumi.String("Security group for web servers"),
VpcId: myVpc.Vpc_id,
Ingress: ec2.SecurityGroupIngressArray{
&ec2.SecurityGroupIngressArgs{
Description: pulumi.String("HTTP"),
FromPort: pulumi.Int(80),
ToPort: pulumi.Int(80),
Protocol: pulumi.String("tcp"),
CidrBlocks: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
},
&ec2.SecurityGroupIngressArgs{
Description: pulumi.String("SSH"),
FromPort: pulumi.Int(22),
ToPort: pulumi.Int(22),
Protocol: pulumi.String("tcp"),
CidrBlocks: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
},
},
Egress: ec2.SecurityGroupEgressArray{
&ec2.SecurityGroupEgressArgs{
FromPort: pulumi.Int(0),
ToPort: pulumi.Int(0),
Protocol: pulumi.String("-1"),
CidrBlocks: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
},
},
})
if err != nil {
return err
}
// Create an EC2 instance in the VPC
webServer, err := ec2.NewInstance(ctx, "web-server", &ec2.InstanceArgs{
Ami: pulumi.String(amazonLinux.Id),
InstanceType: pulumi.String("t3.micro"),
SubnetId: myVpc.Public_subnets.ApplyT(func(subnets []string) string {
return subnets[0]
}).(pulumi.StringOutput),
VpcSecurityGroupIds: pulumi.StringArray{webSg.ID()},
AssociatePublicIpAddress: pulumi.Bool(true),
UserData: pulumi.String(`#!/bin/bash
yum update -y
yum install -y httpd
systemctl start httpd
systemctl enable httpd
echo "<h1>Hello from Pulumi and Terraform modules!</h1>" > /var/www/html/index.html
`),
Tags: pulumi.StringMap{
"Name": pulumi.String("web-server"),
"Environment": pulumi.String("dev"),
},
})
if err != nil {
return err
}
// Output important information
ctx.Export("vpcId", myVpc.Vpc_id)
ctx.Export("instanceId", webServer.ID())
ctx.Export("publicIp", webServer.PublicIp)
ctx.Export("websiteUrl", pulumi.Sprintf("http://%s", webServer.PublicIp))
return nil
})
}
First, create a new Pulumi program:
$ mkdir pulumi-terraform-modules-test && cd pulumi-terraform-modules-test
$ pulumi new aws-csharp --yes
Next, add the VPC module:
$ pulumi package add terraform-module terraform-aws-modules/vpc/aws 6.0.0 vpc
The pulumi package add ... command will add the required dependencies to the solution file, but you’ll need to manually add the following directive:
<PropertyGroup>
<!-- ... -->
<DefaultItemExcludes>$(DefaultItemExcludes);sdks/**/*.cs</DefaultItemExcludes>
</PropertyGroup>
Then use it in your Pulumi program:
using System.Collections.Generic;
using Pulumi;
using Pulumi.Aws.Ec2;
using Pulumi.Vpc;
return await Deployment.RunAsync(() =>
{
// Use the Terraform VPC module
var myVpc = new Vpc("my-vpc", new VpcArgs
{
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,
EnableVpnGateway = true,
Tags = new Dictionary<string, string>
{
["Terraform"] = "true",
["Environment"] = "dev",
},
});
// Get the latest Amazon Linux 2 AMI
var amazonLinux = GetAmi.Invoke(new GetAmiInvokeArgs
{
MostRecent = true,
Owners = new[] { "amazon" },
Filters = new[]
{
new GetAmiFilterInputArgs
{
Name = "name",
Values = new[] { "amzn2-ami-hvm-*-x86_64-gp2" },
},
},
});
// Create a security group
var webSg = new SecurityGroup("web-sg", new SecurityGroupArgs
{
Name = "web-sg",
Description = "Security group for web servers",
VpcId = myVpc.VpcId,
Ingress = new[]
{
new SecurityGroupIngressArgs
{
Description = "HTTP",
FromPort = 80,
ToPort = 80,
Protocol = "tcp",
CidrBlocks = new[] { "0.0.0.0/0" },
},
new SecurityGroupIngressArgs
{
Description = "SSH",
FromPort = 22,
ToPort = 22,
Protocol = "tcp",
CidrBlocks = new[] { "0.0.0.0/0" },
},
},
Egress = new[]
{
new SecurityGroupEgressArgs
{
FromPort = 0,
ToPort = 0,
Protocol = "-1",
CidrBlocks = new[] { "0.0.0.0/0" },
},
},
});
// Create an EC2 instance in the VPC
var webServer = new Instance("web-server", new InstanceArgs
{
Ami = amazonLinux.Apply(ami => ami.Id),
InstanceType = "t3.micro",
SubnetId = myVpc.PublicSubnets.Apply(subnets => subnets[0]),
VpcSecurityGroupIds = new[] { webSg.Id },
AssociatePublicIpAddress = true,
UserData = @"#!/bin/bash
yum update -y
yum install -y httpd
systemctl start httpd
systemctl enable httpd
echo ""<h1>Hello from Pulumi and Terraform modules!</h1>"" > /var/www/html/index.html
",
Tags = new Dictionary<string, string>
{
["Name"] = "web-server",
["Environment"] = "dev",
},
});
return new Dictionary<string, object?>
{
["vpcId"] = myVpc.VpcId,
["publicSubnets"] = myVpc.PublicSubnets,
["privateSubnets"] = myVpc.PrivateSubnets,
["instanceId"] = webServer.Id,
["publicIp"] = webServer.PublicIp,
["websiteUrl"] = webServer.PublicIp.Apply(ip => $"http://{ip}"),
};
});
First, create a new Pulumi program:
$ mkdir pulumi-terraform-modules-test && cd pulumi-terraform-modules-test
$ pulumi new aws-java --yes
Next, add the VPC module:
$ pulumi package add terraform-module terraform-aws-modules/vpc/aws 6.0.0 vpc
The pulumi package add ... command will output some important instructions. There are two steps you must perform manually: copy the contents of the generated SDK to your Java project, and add the dependencies to pom.xml:
<dependencies>
<!-- ... -->
<dependency>
<groupId>com.google.code.findbugs</groupId>
<artifactId>jsr305</artifactId>
<version>3.0.2</version>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.9</version>
</dependency>
</dependencies>
Then use it in your Pulumi program, by replacing the contents of src/main/java/myproject/App.java with:
package myproject;
import com.pulumi.Pulumi;
import com.pulumi.aws.ec2.Ec2Functions;
import com.pulumi.aws.ec2.Instance;
import com.pulumi.aws.ec2.InstanceArgs;
import com.pulumi.aws.ec2.SecurityGroup;
import com.pulumi.aws.ec2.SecurityGroupArgs;
import com.pulumi.aws.ec2.inputs.GetAmiArgs;
import com.pulumi.aws.ec2.inputs.GetAmiFilterArgs;
import com.pulumi.aws.ec2.inputs.SecurityGroupEgressArgs;
import com.pulumi.aws.ec2.inputs.SecurityGroupIngressArgs;
import java.util.Collections;
import java.util.Map;
public class App {
public static void main(String[] args) {
Pulumi.run(ctx -> {
// Use the Terraform VPC module
var myVpc = new com.pulumi.vpc.Module("my-vpc", com.pulumi.vpc.ModuleArgs.builder()
.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.10.0/24", "10.0.11.0/24", "10.0.12.0/24")
.enable_nat_gateway(true)
.enable_vpn_gateway(true)
.tags(Map.of(
"Terraform", "true",
"Environment", "dev"
))
.build());
// Get the latest Amazon Linux 2 AMI
var amazonLinux = Ec2Functions.getAmi(GetAmiArgs.builder()
.mostRecent(true)
.owners("amazon")
.filters(GetAmiFilterArgs.builder()
.name("name")
.values("amzn2-ami-hvm-*-x86_64-gp2")
.build())
.build());
// Create a security group
var webSg = new SecurityGroup("web-sg", SecurityGroupArgs.builder()
.name("web-sg")
.description("Security group for web servers")
.vpcId(myVpc.vpc_id().applyValue(id->id.get()).applyValue(String::valueOf))
.ingress(
SecurityGroupIngressArgs.builder()
.description("HTTP")
.fromPort(80)
.toPort(80)
.protocol("tcp")
.cidrBlocks("0.0.0.0/0")
.build(),
SecurityGroupIngressArgs.builder()
.description("SSH")
.fromPort(22)
.toPort(22)
.protocol("tcp")
.cidrBlocks("0.0.0.0/0")
.build()
)
.egress(SecurityGroupEgressArgs.builder()
.fromPort(0)
.toPort(0)
.protocol("-1")
.cidrBlocks("0.0.0.0/0")
.build())
.build());
// Output<List<String>> secGrps = webSg.id().applyValue(s -> Collections.singletonList(s));
// Create an EC2 instance in the VPC
var webServer = new Instance("web-server", InstanceArgs.builder()
.ami(amazonLinux.applyValue(ami -> ami.id()))
.instanceType("t3.micro")
.subnetId(myVpc.public_subnets().applyValue(subnets -> subnets.get().get(0)))
.vpcSecurityGroupIds(webSg.id().applyValue(s -> Collections.singletonList(s)))
.associatePublicIpAddress(true)
.userData(String.join("\n",
"#!/bin/bash",
"yum update -y",
"yum install -y httpd",
"systemctl start httpd",
"systemctl enable httpd",
"echo \"<h1>Hello from Pulumi and Terraform modules!</h1>\" > /var/www/html/index.html"
))
.tags(Map.of(
"Name", "web-server",
"Environment", "dev"
))
.build());
// Output important information
ctx.export("vpcId", myVpc.vpc_id());
ctx.export("instanceId", webServer.id());
ctx.export("publicIp", webServer.publicIp());
ctx.export("websiteUrl", webServer.publicIp().applyValue(ip -> String.format("http://%s", ip)));
});
}
}
First, create a new Pulumi program:
$ mkdir pulumi-terraform-modules-test && cd pulumi-terraform-modules-test
$ pulumi new aws-yaml --yes
Next, add the VPC module:
$ pulumi package add terraform-module terraform-aws-modules/vpc/aws 6.0.0 vpc
Then use it in your Pulumi program:
name: pulumi-terraform-modules-example
runtime: yaml
description: Use Terraform modules in Pulumi
variables:
# Get the latest Amazon Linux 2 AMI
amazonLinux:
fn::invoke:
function: aws:ec2:getAmi
arguments:
mostRecent: true
owners: ["amazon"]
filters:
- name: name
values: ["amzn2-ami-hvm-*-x86_64-gp2"]
resources:
# Use the Terraform VPC module
my-vpc:
type: vpc:index:Module
properties:
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.10.0/24", "10.0.11.0/24", "10.0.12.0/24"]
enable_nat_gateway: true
enable_vpn_gateway: true
tags:
Terraform: "true"
Environment: "dev"
# Create a security group
web-sg:
type: aws:ec2:SecurityGroup
properties:
name: web-sg
description: Security group for web servers
vpcId: ${my-vpc.vpc_id}
ingress:
- description: HTTP
fromPort: 80
toPort: 80
protocol: tcp
cidrBlocks: ["0.0.0.0/0"]
- description: SSH
fromPort: 22
toPort: 22
protocol: tcp
cidrBlocks: ["0.0.0.0/0"]
egress:
- fromPort: 0
toPort: 0
protocol: "-1"
cidrBlocks: ["0.0.0.0/0"]
# Create an EC2 instance in the VPC
web-server:
type: aws:ec2:Instance
properties:
ami: ${amazonLinux.id}
instanceType: t3.micro
subnetId: ${my-vpc.public_subnets[0]}
vpcSecurityGroupIds:
- ${web-sg.id}
associatePublicIpAddress: true
userData: |
#!/bin/bash
yum update -y
yum install -y httpd
systemctl start httpd
systemctl enable httpd
echo "<h1>Hello from Pulumi and Terraform modules!</h1>" > /var/www/html/index.html
tags:
Name: web-server
Environment: dev
outputs:
vpcId: ${my-vpc.vpc_id}
instanceId: ${web-server.id}
publicIp: ${web-server.publicIp}
websiteUrl: http://${web-server.publicIp}
# The vpc Terraform module package definition
packages:
vpc:
source: terraform-module
version: 0.1.4
parameters:
- terraform-aws-modules/vpc/aws
- 6.0.0
- vpc
Compare with Terraform
The same functionality in Terraform would look like:
# Terraform equivalent
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
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.10.0/24", "10.0.11.0/24", "10.0.12.0/24"]
enable_nat_gateway = true
enable_vpn_gateway = true
tags = {
Terraform = "true"
Environment = "dev"
}
}
data "aws_ami" "amazon_linux" {
most_recent = true
owners = ["amazon"]
filter {
name = "name"
values = ["amzn2-ami-hvm-*-x86_64-gp2"]
}
}
resource "aws_security_group" "web_sg" {
name = "web-sg"
description = "Security group for web servers"
vpc_id = module.vpc.vpc_id
ingress {
description = "HTTP"
from_port = 80
to_port = 80
protocol = "tcp"
cidr_blocks = ["0.0.0.0/0"]
}
ingress {
description = "SSH"
from_port = 22
to_port = 22
protocol = "tcp"
cidr_blocks = ["0.0.0.0/0"]
}
egress {
from_port = 0
to_port = 0
protocol = "-1"
cidr_blocks = ["0.0.0.0/0"]
}
}
resource "aws_instance" "web_server" {
ami = data.aws_ami.amazon_linux.id
instance_type = "t3.micro"
subnet_id = module.vpc.public_subnets[0]
vpc_security_group_ids = [aws_security_group.web_sg.id]
associate_public_ip_address = true
user_data = <<-EOF
#!/bin/bash
yum update -y
yum install -y httpd
systemctl start httpd
systemctl enable httpd
echo "<h1>Hello from Pulumi and Terraform modules!</h1>" > /var/www/html/index.html
EOF
tags = {
Name = "web-server"
Environment = "dev"
}
}
output "vpc_id" {
value = module.vpc.vpc_id
}
output "instance_id" {
value = aws_instance.web_server.id
}
output "public_ip" {
value = aws_instance.web_server.public_ip
}
output "website_url" {
value = "http://${aws_instance.web_server.public_ip}"
}
Best practices
- Pin module versions: Always specify module versions in production
- Review module source: Understand what the module does before using it
- Test module outputs: Verify that module outputs work as expected
- Monitor module updates: Keep track of module updates and breaking changes
- Use reputable sources: Prefer well-maintained modules from trusted sources
- Document module usage: Document why you chose specific modules and their configuration
Clean up
Test your deployment and clean up resources:
# Deploy the stack
$ pulumi up
# Visit the website URL from the output
# When done, destroy the resources
$ pulumi destroy
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.
