Resource: aws_instance

Provides an EC2 instance resource. This allows instances to be created, updated, and deleted. Instances also support provisioning.

Example Usage

Basic example using AMI lookup

data "aws_ami" "ubuntu" {
  most_recent = true

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }

  owners = ["099720109477"] # Canonical
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  tags = {
    Name = "HelloWorld"
  }
}

Spot instance example

data "aws_ami" "this" {
  most_recent = true
  owners      = ["amazon"]
  filter {
    name   = "architecture"
    values = ["arm64"]
  }
  filter {
    name   = "name"
    values = ["al2023-ami-2023*"]
  }
}

resource "aws_instance" "this" {
  ami = data.aws_ami.this.id
  instance_market_options {
    spot_options {
      max_price = 0.0031
    }
  }
  instance_type = "t4g.nano"
  tags = {
    Name = "test-spot"
  }
}

Network and credit specification example

resource "aws_vpc" "my_vpc" {
  cidr_block = "172.16.0.0/16"

  tags = {
    Name = "tf-example"
  }
}

resource "aws_subnet" "my_subnet" {
  vpc_id            = aws_vpc.my_vpc.id
  cidr_block        = "172.16.10.0/24"
  availability_zone = "us-west-2a"

  tags = {
    Name = "tf-example"
  }
}

resource "aws_network_interface" "foo" {
  subnet_id   = aws_subnet.my_subnet.id
  private_ips = ["172.16.10.100"]

  tags = {
    Name = "primary_network_interface"
  }
}

resource "aws_instance" "foo" {
  ami           = "ami-005e54dee72cc1d00" # us-west-2
  instance_type = "t2.micro"

  network_interface {
    network_interface_id = aws_network_interface.foo.id
    device_index         = 0
  }

  credit_specification {
    cpu_credits = "unlimited"
  }
}

CPU options example

resource "aws_vpc" "example" {
  cidr_block = "172.16.0.0/16"

  tags = {
    Name = "tf-example"
  }
}

resource "aws_subnet" "example" {
  vpc_id            = aws_vpc.example.id
  cidr_block        = "172.16.10.0/24"
  availability_zone = "us-east-2a"

  tags = {
    Name = "tf-example"
  }
}

data "aws_ami" "amzn-linux-2023-ami" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["al2023-ami-2023.*-x86_64"]
  }
}

resource "aws_instance" "example" {
  ami           = data.aws_ami.amzn-linux-2023-ami.id
  instance_type = "c6a.2xlarge"
  subnet_id     = aws_subnet.example.id

  cpu_options {
    core_count       = 2
    threads_per_core = 2
  }

  tags = {
    Name = "tf-example"
  }
}

Host resource group or Licence Manager registered AMI example

A host resource group is a collection of Dedicated Hosts that you can manage as a single entity. As you launch instances, License Manager allocates the hosts and launches instances on them based on the settings that you configured. You can add existing Dedicated Hosts to a host resource group and take advantage of automated host management through License Manager.

resource "aws_instance" "this" {
  ami                     = "ami-0dcc1e21636832c5d"
  instance_type           = "m5.large"
  host_resource_group_arn = "arn:aws:resource-groups:us-west-2:012345678901:group/win-testhost"
  tenancy                 = "host"
}

Tag Guide

These are the five types of tags you might encounter relative to an aws_instance:

  1. Instance tags: Applied to instances but not to ebs_block_device and root_block_device volumes.
  2. Default tags: Applied to the instance and to ebs_block_device and root_block_device volumes.
  3. Volume tags: Applied during creation to ebs_block_device and root_block_device volumes.
  4. Root block device tags: Applied only to the root_block_device volume. These conflict with volume_tags.
  5. EBS block device tags: Applied only to the specific ebs_block_device volume you configure them for and cannot be updated. These conflict with volume_tags.

Do not use volume_tags if you plan to manage block device tags outside the aws_instance configuration, such as using tags in an aws_ebs_volume resource attached via aws_volume_attachment. Doing so will result in resource cycling and inconsistent behavior.

Argument Reference

This resource supports the following arguments:

Capacity Reservation Specification

Capacity reservation specification can be applied/modified to the EC2 Instance at creation time or when the instance is stopped.

The capacity_reservation_specification block supports the following:

For more information, see the documentation on Capacity Reservations.

Capacity Reservation Target

Describes a target Capacity Reservation.

This capacity_reservation_target block supports the following:

CPU Options

CPU options apply to the instance at launch time.

The cpu_options block supports the following:

For more information, see the documentation on Optimizing CPU options.

Credit Specification

The credit_specification block supports the following:

EBS, Ephemeral, and Root Block Devices

Each of the *_block_device attributes control a portion of the EC2 Instance's "Block Device Mapping". For more information, see the AWS Block Device Mapping documentation.

The root_block_device block supports the following:

Modifying the encrypted or kms_key_id settings of the root_block_device requires resource replacement.

Each ebs_block_device block supports the following:

Each ephemeral_block_device block supports the following:

Each AWS Instance type has a different set of Instance Store block devices available for attachment. AWS publishes a list of which ephemeral devices are available on each type. The devices are always identified by the virtual_name in the format ephemeral{0..N}.

Enclave Options

Enclave options apply to the instance at boot time.

The enclave_options block supports the following:

For more information, see the documentation on Nitro Enclaves.

Maintenance Options

The maintenance_options block supports the following:

Market Options

The instance_market_options block supports the following:

Metadata Options

Metadata options can be applied/modified to the EC2 Instance at any time.

The metadata_options block supports the following:

For more information, see the documentation on the Instance Metadata Service.

Network Interfaces

Each of the network_interface blocks attach a network interface to an EC2 Instance during boot time. However, because the network interface is attached at boot-time, replacing/modifying the network interface WILL trigger a recreation of the EC2 Instance. If you should need at any point to detach/modify/re-attach a network interface to the instance, use the aws_network_interface or aws_network_interface_attachment resources instead.

The network_interface configuration block _does_, however, allow users to supply their own network interface to be used as the default network interface on an EC2 Instance, attached at eth0.

Each network_interface block supports the following:

Private DNS Name Options

The private_dns_name_options block supports the following:

Spot Options

The spot_options block supports the following:

Launch Template Specification

Any other instance parameters that you specify will override the same parameters in the launch template.

The launch_template block supports the following:

Attribute Reference

This resource exports the following attributes in addition to the arguments above:

For ebs_block_device, in addition to the arguments above, the following attribute is exported:

For root_block_device, in addition to the arguments above, the following attributes are exported:

For instance_market_options, in addition to the arguments above, the following attributes are exported:

Timeouts

Configuration options:

Import

In Terraform v1.5.0 and later, use an import block to import instances using the id. For example:

import {
  to = aws_instance.web
  id = "i-12345678"
}

Using terraform import, import instances using the id. For example:

% terraform import aws_instance.web i-12345678