mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-03-15 16:00:26 -04:00
afb06f907f
Expose the network interface ID that is created with a new instance. This can be useful when associating an existing elastic IP to the default interface on an instance that has multiple network interfaces.
171 lines
8.3 KiB
Markdown
171 lines
8.3 KiB
Markdown
---
|
|
layout: "aws"
|
|
page_title: "AWS: aws_instance"
|
|
sidebar_current: "docs-aws-resource-instance"
|
|
description: |-
|
|
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](/docs/provisioners/index.html).
|
|
|
|
## Example Usage
|
|
|
|
```
|
|
# Create a new instance of the latest Ubuntu 14.04 on an
|
|
# t1.micro node with an AWS Tag naming it "HelloWorld"
|
|
provider "aws" {
|
|
region = "us-east-1"
|
|
}
|
|
|
|
data "aws_ami" "ubuntu" {
|
|
most_recent = true
|
|
filter {
|
|
name = "name"
|
|
values = ["ubuntu/images/ebs/ubuntu-trusty-14.04-amd64-server-*"]
|
|
}
|
|
filter {
|
|
name = "virtualization-type"
|
|
values = ["paravirtual"]
|
|
}
|
|
owners = ["099720109477"] # Canonical
|
|
}
|
|
|
|
resource "aws_instance" "web" {
|
|
ami = "${data.aws_ami.ubuntu.id}"
|
|
instance_type = "t1.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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingDisableAPITermination)
|
|
* `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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingInstanceInitiatedShutdownBehavior) 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.
|
|
* `tags` - (Optional) A mapping of tags to assign to the resource.
|
|
* `root_block_device` - (Optional) Customize details about the root block
|
|
device of the instance. See [Block Devices](#block-devices) below for details.
|
|
* `ebs_block_device` - (Optional) Additional EBS block devices to attach to the
|
|
instance. See [Block Devices](#block-devices) below for details.
|
|
* `ephemeral_block_device` - (Optional) Customize Ephemeral (also known as
|
|
"Instance Store") volumes on the instance. See [Block Devices](#block-devices) below for 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
|
|
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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
|
|
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`).
|
|
|
|
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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
|
|
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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html)
|
|
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_ebs_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` - The [Instance Store Device
|
|
Name](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#InstanceStoreDeviceNames)
|
|
(e.g. `"ephemeral0"`)
|
|
|
|
Each AWS Instance type has a different set of Instance Store block devices
|
|
available for attachment. AWS [publishes a
|
|
list](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#StorageOnInstanceTypes)
|
|
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](/docs/commands/taint.html).
|
|
|
|
## 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`](/docs/providers/aws/r/eip.html) 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.
|
|
* `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
|
|
``` |