github.com/ves/terraform@v0.8.0-beta2/website/source/docs/providers/aws/r/instance.html.markdown (about) 1 --- 2 layout: "aws" 3 page_title: "AWS: aws_instance" 4 sidebar_current: "docs-aws-resource-instance" 5 description: |- 6 Provides an EC2 instance resource. This allows instances to be created, updated, and deleted. Instances also support provisioning. 7 --- 8 9 # aws\_instance 10 11 Provides an EC2 instance resource. This allows instances to be created, updated, 12 and deleted. Instances also support [provisioning](/docs/provisioners/index.html). 13 14 ## Example Usage 15 16 ``` 17 # Create a new instance of the latest Ubuntu 14.04 on an 18 # t2.micro node with an AWS Tag naming it "HelloWorld" 19 provider "aws" { 20 region = "us-west-2" 21 } 22 23 data "aws_ami" "ubuntu" { 24 most_recent = true 25 filter { 26 name = "name" 27 values = ["ubuntu/images/hvm-ssd/ubuntu-trusty-14.04-amd64-server-*"] 28 } 29 filter { 30 name = "virtualization-type" 31 values = ["hvm"] 32 } 33 owners = ["099720109477"] # Canonical 34 } 35 36 resource "aws_instance" "web" { 37 ami = "${data.aws_ami.ubuntu.id}" 38 instance_type = "t2.micro" 39 tags { 40 Name = "HelloWorld" 41 } 42 } 43 ``` 44 45 ## Argument Reference 46 47 The following arguments are supported: 48 49 * `ami` - (Required) The AMI to use for the instance. 50 * `availability_zone` - (Optional) The AZ to start the instance in. 51 * `placement_group` - (Optional) The Placement Group to start the instance in. 52 * `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. 53 * `ebs_optimized` - (Optional) If true, the launched EC2 instance will be 54 EBS-optimized. 55 * `disable_api_termination` - (Optional) If true, enables [EC2 Instance 56 Termination Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingDisableAPITermination) 57 * `instance_initiated_shutdown_behavior` - (Optional) Shutdown behavior for the 58 instance. Amazon defaults this to `stop` for EBS-backed instances and 59 `terminate` for instance-store instances. Cannot be set on instance-store 60 instances. See [Shutdown Behavior](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingInstanceInitiatedShutdownBehavior) for more information. 61 * `instance_type` - (Required) The type of instance to start 62 * `key_name` - (Optional) The key name to use for the instance. 63 * `monitoring` - (Optional) If true, the launched EC2 instance will have detailed monitoring enabled. (Available since v0.6.0) 64 * `security_groups` - (Optional) A list of security group names to associate with. 65 If you are creating Instances in a VPC, use `vpc_security_group_ids` instead. 66 * `vpc_security_group_ids` - (Optional) A list of security group IDs to associate with. 67 * `subnet_id` - (Optional) The VPC Subnet ID to launch in. 68 * `associate_public_ip_address` - (Optional) Associate a public ip address with an instance in a VPC. Boolean value. 69 * `private_ip` - (Optional) Private IP address to associate with the 70 instance in a VPC. 71 * `source_dest_check` - (Optional) Controls if traffic is routed to the instance when 72 the destination address does not match the instance. Used for NAT or VPNs. Defaults true. 73 * `user_data` - (Optional) The user data to provide when launching the instance. 74 * `iam_instance_profile` - (Optional) The IAM Instance Profile to 75 launch the instance with. 76 * `tags` - (Optional) A mapping of tags to assign to the resource. 77 * `root_block_device` - (Optional) Customize details about the root block 78 device of the instance. See [Block Devices](#block-devices) below for details. 79 * `ebs_block_device` - (Optional) Additional EBS block devices to attach to the 80 instance. See [Block Devices](#block-devices) below for details. 81 * `ephemeral_block_device` - (Optional) Customize Ephemeral (also known as 82 "Instance Store") volumes on the instance. See [Block Devices](#block-devices) below for details. 83 84 85 ## Block devices 86 87 Each of the `*_block_device` attributes controls a portion of the AWS 88 Instance's "Block Device Mapping". It's a good idea to familiarize yourself with [AWS's Block Device 89 Mapping docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html) 90 to understand the implications of using these attributes. 91 92 The `root_block_device` mapping supports the following: 93 94 * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`, 95 or `"io1"`. (Default: `"standard"`). 96 * `volume_size` - (Optional) The size of the volume in gigabytes. 97 * `iops` - (Optional) The amount of provisioned 98 [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html). 99 This must be set with a `volume_type` of `"io1"`. 100 * `delete_on_termination` - (Optional) Whether the volume should be destroyed 101 on instance termination (Default: `true`). 102 103 Modifying any of the `root_block_device` settings requires resource 104 replacement. 105 106 Each `ebs_block_device` supports the following: 107 108 * `device_name` - The name of the device to mount. 109 * `snapshot_id` - (Optional) The Snapshot ID to mount. 110 * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`, 111 or `"io1"`. (Default: `"standard"`). 112 * `volume_size` - (Optional) The size of the volume in gigabytes. 113 * `iops` - (Optional) The amount of provisioned 114 [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html). 115 This must be set with a `volume_type` of `"io1"`. 116 * `delete_on_termination` - (Optional) Whether the volume should be destroyed 117 on instance termination (Default: `true`). 118 * `encrypted` - (Optional) Enables [EBS 119 encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html) 120 on the volume (Default: `false`). Cannot be used with `snapshot_id`. 121 122 Modifying any `ebs_block_device` currently requires resource replacement. 123 124 ~> **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. 125 126 Each `ephemeral_block_device` supports the following: 127 128 * `device_name` - The name of the block device to mount on the instance. 129 * `virtual_name` - The [Instance Store Device 130 Name](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#InstanceStoreDeviceNames) 131 (e.g. `"ephemeral0"`) 132 133 Each AWS Instance type has a different set of Instance Store block devices 134 available for attachment. AWS [publishes a 135 list](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#StorageOnInstanceTypes) 136 of which ephemeral devices are available on each type. The devices are always 137 identified by the `virtual_name` in the format `"ephemeral{0..N}"`. 138 139 ~> **NOTE:** Currently, changes to `*_block_device` configuration of _existing_ 140 resources cannot be automatically detected by Terraform. After making updates 141 to block device configuration, resource recreation can be manually triggered by 142 using the [`taint` command](/docs/commands/taint.html). 143 144 ## Attributes Reference 145 146 The following attributes are exported: 147 148 * `id` - The instance ID. 149 * `availability_zone` - The availability zone of the instance. 150 * `placement_group` - The placement group of the instance. 151 * `key_name` - The key name of the instance 152 * `public_dns` - The public DNS name assigned to the instance. For EC2-VPC, this 153 is only available if you've enabled DNS hostnames for your VPC 154 * `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. 155 * `network_interface_id` - The ID of the network interface that was created with the instance. 156 * `private_dns` - The private DNS name assigned to the instance. Can only be 157 used inside the Amazon EC2, and only available if you've enabled DNS hostnames 158 for your VPC 159 * `private_ip` - The private IP address assigned to the instance 160 * `security_groups` - The associated security groups. 161 * `vpc_security_group_ids` - The associated security groups in non-default VPC 162 * `subnet_id` - The VPC subnet ID. 163 164 165 ## Import 166 167 Instances can be imported using the `id`, e.g. 168 169 ``` 170 $ terraform import aws_instance.web i-12345678 171 ```