11 KiB

Raw Blame History

layout	page_title	sidebar_current	description
aws	AWS: aws_instance	docs-aws-resource-instance	Provides an EC2 instance resource. This allows instances to be created, updated, and deleted. Instances also support provisioning.

aws_instance

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

Example Usage

# Create a new instance of the latest Ubuntu 14.04 on an
# t2.micro node with an AWS Tag naming it "HelloWorld"
provider "aws" {
  region = "us-west-2"
}

data "aws_ami" "ubuntu" {
  most_recent = true

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

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

  owners = ["099720109477"] # Canonical
}

resource "aws_instance" "web" {
  ami           = "${data.aws_ami.ubuntu.id}"
  instance_type = "t2.micro"

  tags {
    Name = "HelloWorld"
  }
}

Argument Reference

The following arguments are supported:

ami - (Required) The AMI to use for the instance.
availability_zone - (Optional) The AZ to start the instance in.
placement_group - (Optional) The Placement Group to start the instance in.
tenancy - (Optional) The tenancy of the instance (if the instance is running in a VPC). An instance with a tenancy of dedicated runs on single-tenant hardware. The host tenancy is not supported for the import-instance command.
ebs_optimized - (Optional) If true, the launched EC2 instance will be EBS-optimized.
disable_api_termination - (Optional) If true, enables EC2 Instance Termination Protection
instance_initiated_shutdown_behavior - (Optional) Shutdown behavior for the instance. Amazon defaults this to stop for EBS-backed instances and terminate for instance-store instances. Cannot be set on instance-store instances. See Shutdown Behavior for more information.
instance_type - (Required) The type of instance to start
key_name - (Optional) The key name to use for the instance.
monitoring - (Optional) If true, the launched EC2 instance will have detailed monitoring enabled. (Available since v0.6.0)
security_groups - (Optional) A list of security group names to associate with. If you are creating Instances in a VPC, use vpc_security_group_ids instead.
vpc_security_group_ids - (Optional) A list of security group IDs to associate with.
subnet_id - (Optional) The VPC Subnet ID to launch in.
associate_public_ip_address - (Optional) Associate a public ip address with an instance in a VPC. Boolean value.
private_ip - (Optional) Private IP address to associate with the instance in a VPC.
source_dest_check - (Optional) Controls if traffic is routed to the instance when the destination address does not match the instance. Used for NAT or VPNs. Defaults true.
user_data - (Optional) The user data to provide when launching the instance.
iam_instance_profile - (Optional) The IAM Instance Profile to launch the instance with. Specified as the name of the Instance Profile.
ipv6_address_count- (Optional) A number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet.
ipv6_addresses - (Optional) Specify one or more IPv6 addresses from the range of the subnet to associate with the primary network interface
tags - (Optional) A mapping of tags to assign to the resource.
volume_tags - (Optional) A mapping of tags to assign to the devices created by the instance at launch time.
root_block_device - (Optional) Customize details about the root block device of the instance. See Block Devices below for details.
ebs_block_device - (Optional) Additional EBS block devices to attach to the instance. See Block Devices below for details.
ephemeral_block_device - (Optional) Customize Ephemeral (also known as "Instance Store") volumes on the instance. See Block Devices below for details.
network_interface - (Optional) Customize network interfaces to be attached at instance boot time. See Network Interfaces below for more details.

Block devices

Each of the *_block_device attributes controls a portion of the AWS Instance's "Block Device Mapping". It's a good idea to familiarize yourself with AWS's Block Device Mapping docs to understand the implications of using these attributes.

The root_block_device mapping supports the following:

volume_type - (Optional) The type of volume. Can be "standard", "gp2", or "io1". (Default: "standard").
volume_size - (Optional) The size of the volume in gigabytes.
iops - (Optional) The amount of provisioned IOPS. This is only valid for volume_type of "io1", and must be specified if using that type
delete_on_termination - (Optional) Whether the volume should be destroyed on instance termination (Default: true).

Modifying any of the root_block_device settings requires resource replacement.

Each ebs_block_device supports the following:

device_name - The name of the device to mount.
snapshot_id - (Optional) The Snapshot ID to mount.
volume_type - (Optional) The type of volume. Can be "standard", "gp2", or "io1". (Default: "standard").
volume_size - (Optional) The size of the volume in gigabytes.
iops - (Optional) The amount of provisioned IOPS. This must be set with a volume_type of "io1".
delete_on_termination - (Optional) Whether the volume should be destroyed on instance termination (Default: true).
encrypted - (Optional) Enables EBS encryption on the volume (Default: false). Cannot be used with snapshot_id.

Modifying any ebs_block_device currently requires resource replacement.

~> NOTE on EBS block devices: If you use ebs_block_device on an aws_instance, Terraform will assume management over the full set of non-root EBS block devices for the instance, and treats additional block devices as drift. For this reason, ebs_block_device cannot be mixed with external aws_ebs_volume + aws_volume_attachment resources for a given instance.

Each ephemeral_block_device supports the following:

device_name - The name of the block device to mount on the instance.
virtual_name - (Optional) The Instance Store Device Name (e.g. "ephemeral0").
no_device - (Optional) Suppresses the specified device included in the AMI's block device mapping.

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}".

~> NOTE: Currently, changes to *_block_device configuration of existing resources cannot be automatically detected by Terraform. After making updates to block device configuration, resource recreation can be manually triggered by using the taint command.

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:

device_index - (Required) The integer index of the network interface attachment. Limited by instance type.
network_interface_id - (Required) The ID of the network interface to attach.
delete_on_termination - (Optional) Whether or not to delete the network interface on instance termination. Defaults to false.

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-22b9a343" // us-west-2
	instance_type = "t2.micro"
	network_interface {
	 network_interface_id = "${aws_network_interface.foo.id}"
	 device_index = 0
  }
}

Attributes Reference

The following attributes are exported:

id - The instance ID.
availability_zone - The availability zone of the instance.
placement_group - The placement group of the instance.
key_name - The key name of the instance
public_dns - The public DNS name assigned to the instance. For EC2-VPC, this is only available if you've enabled DNS hostnames for your VPC
public_ip - The public IP address assigned to the instance, if applicable. NOTE: If you are using an aws_eip with your instance, you should refer to the EIP's address directly and not use public_ip, as this field will change after the EIP is attached.
network_interface_id - The ID of the network interface that was created with the instance.
primary_network_interface_id - The ID of the instance's primary network interface.
private_dns - The private DNS name assigned to the instance. Can only be used inside the Amazon EC2, and only available if you've enabled DNS hostnames for your VPC
private_ip - The private IP address assigned to the instance
security_groups - The associated security groups.
vpc_security_group_ids - The associated security groups in non-default VPC
subnet_id - The VPC subnet ID.

Import

Instances can be imported using the id, e.g.

$ terraform import aws_instance.web i-12345678

11 KiB Raw Blame History