github.com/koding/terraform@v0.6.4-0.20170608090606-5d7e0339779d/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  ```hcl
    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  
    26    filter {
    27      name   = "name"
    28      values = ["ubuntu/images/hvm-ssd/ubuntu-trusty-14.04-amd64-server-*"]
    29    }
    30  
    31    filter {
    32      name   = "virtualization-type"
    33      values = ["hvm"]
    34    }
    35  
    36    owners = ["099720109477"] # Canonical
    37  }
    38  
    39  resource "aws_instance" "web" {
    40    ami           = "${data.aws_ami.ubuntu.id}"
    41    instance_type = "t2.micro"
    42  
    43    tags {
    44      Name = "HelloWorld"
    45    }
    46  }
    47  ```
    48  
    49  ## Argument Reference
    50  
    51  The following arguments are supported:
    52  
    53  * `ami` - (Required) The AMI to use for the instance.
    54  * `availability_zone` - (Optional) The AZ to start the instance in.
    55  * `placement_group` - (Optional) The Placement Group to start the instance in.
    56  * `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.
    57  * `ebs_optimized` - (Optional) If true, the launched EC2 instance will be
    58       EBS-optimized.
    59  * `disable_api_termination` - (Optional) If true, enables [EC2 Instance
    60       Termination Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingDisableAPITermination)
    61  * `instance_initiated_shutdown_behavior` - (Optional) Shutdown behavior for the
    62  instance. Amazon defaults this to `stop` for EBS-backed instances and
    63  `terminate` for instance-store instances. Cannot be set on instance-store
    64  instances. See [Shutdown Behavior](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingInstanceInitiatedShutdownBehavior) for more information.
    65  * `instance_type` - (Required) The type of instance to start
    66  * `key_name` - (Optional) The key name to use for the instance.
    67  * `monitoring` - (Optional) If true, the launched EC2 instance will have detailed monitoring enabled. (Available since v0.6.0)
    68  * `security_groups` - (Optional) A list of security group names to associate with.
    69     If you are creating Instances in a VPC, use `vpc_security_group_ids` instead.
    70  * `vpc_security_group_ids` - (Optional) A list of security group IDs to associate with.
    71  * `subnet_id` - (Optional) The VPC Subnet ID to launch in.
    72  * `associate_public_ip_address` - (Optional) Associate a public ip address with an instance in a VPC.  Boolean value.
    73  * `private_ip` - (Optional) Private IP address to associate with the
    74       instance in a VPC.
    75  * `source_dest_check` - (Optional) Controls if traffic is routed to the instance when
    76    the destination address does not match the instance. Used for NAT or VPNs. Defaults true.
    77  * `user_data` - (Optional) The user data to provide when launching the instance.
    78  * `iam_instance_profile` - (Optional) The IAM Instance Profile to
    79    launch the instance with. Specified as the name of the Instance Profile.
    80  * `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.
    81  * `ipv6_addresses` - (Optional) Specify one or more IPv6 addresses from the range of the subnet to associate with the primary network interface
    82  * `tags` - (Optional) A mapping of tags to assign to the resource.
    83  * `volume_tags` - (Optional) A mapping of tags to assign to the devices created by the instance at launch time.
    84  * `root_block_device` - (Optional) Customize details about the root block
    85    device of the instance. See [Block Devices](#block-devices) below for details.
    86  * `ebs_block_device` - (Optional) Additional EBS block devices to attach to the
    87    instance.  See [Block Devices](#block-devices) below for details.
    88  * `ephemeral_block_device` - (Optional) Customize Ephemeral (also known as
    89    "Instance Store") volumes on the instance. See [Block Devices](#block-devices) below for details.
    90  * `network_interface` - (Optional) Customize network interfaces to be attached at instance boot time. See [Network Interfaces](#network-interfaces) below for more details.
    91  
    92  ### Timeouts
    93  
    94  The `timeouts` block allows you to specify [timeouts](https://www.terraform.io/docs/configuration/resources.html#timeouts) for certain actions:
    95  
    96  * `create` - (Defaults to 10 mins) Used when launching the instance (until it reaches the initial `running` state)
    97  * `update` - (Defaults to 10 mins) Used when stopping and starting the instance when necessary during update - e.g. when changing instance type
    98  * `delete` - (Defaults to 10 mins) Used when terminating the instance
    99  
   100  ### Block devices
   101  
   102  Each of the `*_block_device` attributes controls a portion of the AWS
   103  Instance's "Block Device Mapping". It's a good idea to familiarize yourself with [AWS's Block Device
   104  Mapping docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   105  to understand the implications of using these attributes.
   106  
   107  The `root_block_device` mapping supports the following:
   108  
   109  * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`,
   110    or `"io1"`. (Default: `"standard"`).
   111  * `volume_size` - (Optional) The size of the volume in gigabytes.
   112  * `iops` - (Optional) The amount of provisioned
   113    [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
   114    This is only valid for `volume_type` of `"io1"`, and must be specified if
   115    using that type
   116  * `delete_on_termination` - (Optional) Whether the volume should be destroyed
   117    on instance termination (Default: `true`).
   118  
   119  Modifying any of the `root_block_device` settings requires resource
   120  replacement.
   121  
   122  Each `ebs_block_device` supports the following:
   123  
   124  * `device_name` - The name of the device to mount.
   125  * `snapshot_id` - (Optional) The Snapshot ID to mount.
   126  * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`,
   127    or `"io1"`. (Default: `"standard"`).
   128  * `volume_size` - (Optional) The size of the volume in gigabytes.
   129  * `iops` - (Optional) The amount of provisioned
   130    [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
   131    This must be set with a `volume_type` of `"io1"`.
   132  * `delete_on_termination` - (Optional) Whether the volume should be destroyed
   133    on instance termination (Default: `true`).
   134  * `encrypted` - (Optional) Enables [EBS
   135    encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html)
   136    on the volume (Default: `false`). Cannot be used with `snapshot_id`.
   137  
   138  Modifying any `ebs_block_device` currently requires resource replacement.
   139  
   140  ~> **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.
   141  
   142  Each `ephemeral_block_device` supports the following:
   143  
   144  * `device_name` - The name of the block device to mount on the instance.
   145  * `virtual_name` - (Optional) The [Instance Store Device
   146    Name](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#InstanceStoreDeviceNames)
   147    (e.g. `"ephemeral0"`).
   148  * `no_device` - (Optional) Suppresses the specified device included in the AMI's block device mapping.
   149  
   150  Each AWS Instance type has a different set of Instance Store block devices
   151  available for attachment. AWS [publishes a
   152  list](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#StorageOnInstanceTypes)
   153  of which ephemeral devices are available on each type. The devices are always
   154  identified by the `virtual_name` in the format `"ephemeral{0..N}"`.
   155  
   156  ~> **NOTE:** Currently, changes to `*_block_device` configuration of _existing_
   157  resources cannot be automatically detected by Terraform. After making updates
   158  to block device configuration, resource recreation can be manually triggered by
   159  using the [`taint` command](/docs/commands/taint.html).
   160  
   161  ### Network Interfaces
   162  
   163  Each of the `network_interface` blocks attach a network interface to an EC2 Instance during boot time. However, because
   164  the network interface is attached at boot-time, replacing/modifying the network interface **WILL** trigger a recreation
   165  of the EC2 Instance. If you should need at any point to detach/modify/re-attach a network interface to the instance, use
   166  the `aws_network_interface` or `aws_network_interface_attachment` resources instead.
   167  
   168  The `network_interface` configuration block _does_, however, allow users to supply their own network interface to be used
   169  as the default network interface on an EC2 Instance, attached at `eth0`.
   170  
   171  Each `network_interface` block supports the following:
   172  
   173  * `device_index` - (Required) The integer index of the network interface attachment. Limited by instance type.
   174  * `network_interface_id` - (Required) The ID of the network interface to attach.
   175  * `delete_on_termination` - (Optional) Whether or not to delete the network interface on instance termination. Defaults to `false`.
   176  
   177  ### Example
   178  
   179  ```hcl
   180  resource "aws_vpc" "my_vpc" {
   181    cidr_block = "172.16.0.0/16"
   182    tags {
   183      Name = "tf-example"
   184    }
   185  }
   186  
   187  resource "aws_subnet" "my_subnet" {
   188    vpc_id = "${aws_vpc.my_vpc.id}"
   189    cidr_block = "172.16.10.0/24"
   190    availability_zone = "us-west-2a"
   191    tags {
   192      Name = "tf-example"
   193    }
   194  }
   195  
   196  resource "aws_network_interface" "foo" {
   197    subnet_id = "${aws_subnet.my_subnet.id}"
   198    private_ips = ["172.16.10.100"]
   199    tags {
   200      Name = "primary_network_interface"
   201    }
   202  }
   203  
   204  resource "aws_instance" "foo" {
   205  	ami = "ami-22b9a343" # us-west-2
   206  	instance_type = "t2.micro"
   207  	network_interface {
   208  	 network_interface_id = "${aws_network_interface.foo.id}"
   209  	 device_index = 0
   210    }
   211  }
   212  ```
   213  
   214  ## Attributes Reference
   215  
   216  The following attributes are exported:
   217  
   218  * `id` - The instance ID.
   219  * `availability_zone` - The availability zone of the instance.
   220  * `placement_group` - The placement group of the instance.
   221  * `key_name` - The key name of the instance
   222  * `public_dns` - The public DNS name assigned to the instance. For EC2-VPC, this
   223    is only available if you've enabled DNS hostnames for your VPC
   224  * `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.
   225  * `network_interface_id` - The ID of the network interface that was created with the instance.
   226  * `primary_network_interface_id` - The ID of the instance's primary network interface.
   227  * `private_dns` - The private DNS name assigned to the instance. Can only be
   228    used inside the Amazon EC2, and only available if you've enabled DNS hostnames
   229    for your VPC
   230  * `private_ip` - The private IP address assigned to the instance
   231  * `security_groups` - The associated security groups.
   232  * `vpc_security_group_ids` - The associated security groups in non-default VPC
   233  * `subnet_id` - The VPC subnet ID.
   234  
   235  
   236  ## Import
   237  
   238  Instances can be imported using the `id`, e.g.
   239  
   240  ```
   241  $ terraform import aws_instance.web i-12345678
   242  ```