Skip to main content

25.8K Contact us Sign in Dashboard Get started

⌘K

Virtual Machine on AWS

Deploy View source Get started with Pulumi

Report an issue

The AWS Virtual Machine template scaffolds a Pulumi project that provisions an Amazon EC2 instance running Amazon Linux 2023 inside a new Amazon VPC. The instance boots a small Python HTTP server on port 80 from user data, so the project deploys end to end out of the box. Use it as a starting point for a web application, backend service, or database VM.

Before you begin#

TypeScript

The Pulumi CLI
An AWS account
Pulumi configured with your AWS credentials
Node.js and npm installed locally

Create a new project#

Create a new project using the template in the language of your choice:

TypeScript

$ mkdir my-virtual-machine && cd my-virtual-machine
$ pulumi new vm-aws-typescript

$ mkdir my-virtual-machine && cd my-virtual-machine
$ pulumi new vm-aws-python

$ mkdir my-virtual-machine && cd my-virtual-machine
$ pulumi new vm-aws-go

$ mkdir my-virtual-machine && cd my-virtual-machine
$ pulumi new vm-aws-csharp

$ mkdir my-virtual-machine && cd my-virtual-machine
$ pulumi new vm-aws-yaml

$ mkdir my-virtual-machine && cd my-virtual-machine
$ pulumi new vm-aws-hcl

pulumi new walks you through creating and configuring a new project and stack. A stack is an instance of a project and you can have many of them — dev, staging, prod — each with its own configuration settings. The template also includes some additional settings:

TypeScript

Key	Description	Default
aws:region	The AWS region to deploy into	us-west-2
instanceType	The Amazon EC2 instance type	t3.micro
vpcNetworkCidr	The network CIDR to use for the VPC	10.0.0.0/16

You can change these settings later with pulumi config set:

$ pulumi config set aws:region <value>
$ pulumi config set instanceType <value>
$ pulumi config set vpcNetworkCidr <value>

Key	Description	Default
aws:region	The AWS region to deploy into	us-west-2
instanceType	The Amazon EC2 instance type	t3.micro
vpcNetworkCidr	The network CIDR to use for the VPC	10.0.0.0/16

You can change these settings later with pulumi config set:

$ pulumi config set aws:region <value>
$ pulumi config set instanceType <value>
$ pulumi config set vpcNetworkCidr <value>

Key	Description	Default
aws:region	The AWS region to deploy into	us-west-2
instanceType	The Amazon EC2 instance type	t3.micro
vpcNetworkCidr	The network CIDR to use for the VPC	10.0.0.0/16

You can change these settings later with pulumi config set:

$ pulumi config set aws:region <value>
$ pulumi config set instanceType <value>
$ pulumi config set vpcNetworkCidr <value>

Key	Description	Default
aws:region	The AWS region to deploy into	us-west-2
instanceType	The Amazon EC2 instance type	t3.micro
vpcNetworkCidr	The network CIDR to use for the VPC	10.0.0.0/16

You can change these settings later with pulumi config set:

$ pulumi config set aws:region <value>
$ pulumi config set instanceType <value>
$ pulumi config set vpcNetworkCidr <value>

Key	Description	Default
aws:region	The AWS region to deploy into	us-west-2
instanceType	The Amazon EC2 instance type	t3.micro
vpcNetworkCidr	The network CIDR to use for the VPC	10.0.0.0/16

You can change these settings later with pulumi config set:

$ pulumi config set aws:region <value>
$ pulumi config set instanceType <value>
$ pulumi config set vpcNetworkCidr <value>

Key	Description	Default
aws:region	The AWS region to deploy into	us-west-2
instance_type	The Amazon EC2 instance type	t3.micro
vpc_network_cidr	The network CIDR to use for the VPC	10.0.0.0/16
service_port	The HTTP service port to expose on the VM	80

You can change these settings later with pulumi config set:

$ pulumi config set aws:region <value>
$ pulumi config set instance_type <value>
$ pulumi config set vpc_network_cidr <value>
$ pulumi config set service_port <value>

TypeScript

When setup completes, you’ll see a few key files:

Pulumi.yaml names the project and the language it’s written in.
Pulumi.dev.yaml holds the dev stack’s settings, including the values you just entered.
index.ts is the program: the code that declares your cloud resources.

When setup completes, you’ll see a few key files:

Pulumi.yaml names the project and the language it’s written in.
Pulumi.dev.yaml holds the dev stack’s settings, including the values you just entered.
index.ts is the program: the code that declares your cloud resources.

When setup completes, you’ll see a few key files:

Pulumi.yaml names the project and the language it’s written in.
Pulumi.dev.yaml holds the dev stack’s settings, including the values you just entered.
index.ts is the program: the code that declares your cloud resources.

When setup completes, you’ll see a few key files:

Pulumi.yaml names the project and the language it’s written in.
Pulumi.dev.yaml holds the dev stack’s settings, including the values you just entered.
index.ts is the program: the code that declares your cloud resources.

When setup completes, you’ll see a few key files:

Pulumi.yaml names the project and holds the program: the resources it declares.
Pulumi.dev.yaml holds the dev stack’s settings, including the values you just entered.

When setup completes, you’ll see a few key files:

Pulumi.yaml names the project and the language it’s written in.
Pulumi.dev.yaml holds the dev stack’s settings, including the values you just entered.
index.ts is the program: the code that declares your cloud resources.

Deploy the project#

Deploy with pulumi up. It starts with a preview of what it’s about to create and asks before it changes anything. Choose yes to deploy.

$ pulumi up

Pulumi adds a random suffix to most resource names, so the security group’s name ends in something like -4f8a2c1. This is autonaming. It lets you deploy the same program to more than one stack, and lets Pulumi create a replacement before it deletes the old resource, without names colliding.

When it finishes, Pulumi prints the stack’s outputs, values it only knows once the resources exist:

ip: The IP address of the EC2 instance.
hostname: The provider-assigned hostname of the EC2 instance.
url: The fully-qualified HTTP URL of the HTTP server running on the EC2 instance.

Read one any time with pulumi stack output <name>, or pass it to another command. This opens the instance’s web page in your browser:

$ open $(pulumi stack output url)

To check it from the terminal, fetch the page with curl. It prints Hello, World from Pulumi!. The web server starts as the instance boots, so if curl can’t connect, wait a minute and try again:

$ curl $(pulumi stack output url)

Customize the project#

Projects created with the Virtual Machine template expose the following configuration settings:

TypeScript

instanceType: The EC2 instance type to use for the VM. Defaults to t3.micro.
vpcNetworkCidr: The network CIDR to use for the VPC. Defaults to 10.0.0.0/16.

instanceType: The EC2 instance type to use for the VM. Defaults to t3.micro.
vpcNetworkCidr: The network CIDR to use for the VPC. Defaults to 10.0.0.0/16.

instanceType: The EC2 instance type to use for the VM. Defaults to t3.micro.
vpcNetworkCidr: The network CIDR to use for the VPC. Defaults to 10.0.0.0/16.

instanceType: The EC2 instance type to use for the VM. Defaults to t3.micro.
vpcNetworkCidr: The network CIDR to use for the VPC. Defaults to 10.0.0.0/16.

instanceType: The EC2 instance type to use for the VM. Defaults to t3.micro.
vpcNetworkCidr: The network CIDR to use for the VPC. Defaults to 10.0.0.0/16.

instance_type: The EC2 instance type to use for the VM. Defaults to t3.micro.
vpc_network_cidr: The network CIDR to use for the VPC. Defaults to 10.0.0.0/16.
service_port: The HTTP service port to expose on the VM. Defaults to 80.

All of these settings are optional and may be adjusted either by editing the stack configuration file directly (by default, Pulumi.dev.yaml) or by changing their values with pulumi config set.

Adding a tag#

Tags are key-value labels you can search and filter instances by. The template already tags it Name: webserver. Add an Environment tag in index.ts:

TypeScript

const server = new aws.ec2.Instance("server", {
    // ...
    tags: {
        Name: "webserver",
       Environment: "dev",
    },
});

server = aws.ec2.Instance(
    "server",
    # ...
    tags={
        "Name": "webserver",
       "Environment": "dev",
    },
)

server, err := ec2.NewInstance(ctx, "server", &ec2.InstanceArgs{
  // ...
  Tags: pulumi.StringMap{
    "Name": pulumi.String("webserver"),
    "Environment": pulumi.String("dev"),
  },
})

var server = new Aws.Ec2.Instance("server", new()
{
    // ...
    Tags =
    {
        { "Name", "webserver" },
       { "Environment", "dev" },
    },
});

server:
    type: aws:ec2:Instance
    properties:
        # ...
        tags:
            Name: webserver
           Environment: dev

resource "aws_ec2_instance" "server" {
  # ...
  tags = {
    Name = "webserver"
   Environment = "dev"
  }
}

Deploy it. The preview shows the instance as an update. EC2 adds tags without replacing or restarting it, so url keeps working. Then ask EC2 for the tags on the instance at the stack’s IP address; Environment is now in the list:

$ pulumi up
$ aws ec2 describe-instances --region $(pulumi config get aws:region) --filters "Name=ip-address,Values=$(pulumi stack output ip)" --query "Reservations[].Instances[].Tags" --output table

To see what else you can add, browse the AWS provider in the Pulumi Registry.

Cleaning up#

You can cleanly destroy the stack and all of its infrastructure with pulumi destroy:

$ pulumi destroy

Learn more#

Browse other architecture templates in the Templates gallery.
Explore the AWS provider API docs in the Pulumi Registry.
Walk through Pulumi from the ground up in Pulumi Tutorials.
Read the latest AWS posts on the Pulumi blog.

AWS TypeScript Python Go .NET YAML HCL

Related

AWS Serverless Application

Deploy a serverless application on AWS with Pulumi, AWS Lambda, and Amazon API Gateway.

WalkthroughDeployable

AWS Static Website

Deploy a static website on AWS with Pulumi, Amazon S3, and Amazon CloudFront.

WalkthroughDeployable

The infrastructure as code platform for any cloud.

Contact us Get started