github.com/armen/terraform@v0.5.2-0.20150529052519-caa8117a08f1/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 ami-1234 on an m1.small node
    18  # with an AWS Tag naming it "HelloWorld"
    19  resource "aws_instance" "web" {
    20      ami = "ami-1234"
    21      instance_type = "m1.small"
    22      tags {
    23          Name = "HelloWorld"
    24      }
    25  }
    26  ```
    27  
    28  ## Argument Reference
    29  
    30  The following arguments are supported:
    31  
    32  * `ami` - (Required) The AMI to use for the instance.
    33  * `availability_zone` - (Optional) The AZ to start the instance in.
    34  * `placement_group` - (Optional) The Placement Group to start the instance in.
    35  * `ebs_optimized` - (Optional) If true, the launched EC2 instance will be
    36       EBS-optimized.
    37  * `disable_api_termination` - (Optional) If true, enables [EC2 Instance
    38       Termination Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingDisableAPITermination)
    39  * `instance_type` - (Required) The type of instance to start
    40  * `key_name` - (Optional) The key name to use for the instance.
    41  * `security_groups` - (Optional) A list of security group names to associate with.
    42     If you are within a non-default VPC, you'll need to use `vpc_security_group_ids` instead.
    43  * `vpc_security_group_ids` - (Optional) A list of security group IDs to associate with.
    44  * `subnet_id` - (Optional) The VPC Subnet ID to launch in.
    45  * `associate_public_ip_address` - (Optional) Associate a public ip address with an instance in a VPC.
    46  * `private_ip` - (Optional) Private IP address to associate with the
    47       instance in a VPC.
    48  * `source_dest_check` - (Optional) Controls if traffic is routed to the instance when
    49    the destination address does not match the instance. Used for NAT or VPNs. Defaults true.
    50  * `user_data` - (Optional) The user data to provide when launching the instance.
    51  * `iam_instance_profile` - (Optional) The IAM Instance Profile to
    52    launch the instance with.
    53  * `tags` - (Optional) A mapping of tags to assign to the resource.
    54  * `root_block_device` - (Optional) Customize details about the root block
    55    device of the instance. See [Block Devices](#block-devices) below for details.
    56  * `ebs_block_device` - (Optional) Additional EBS block devices to attach to the
    57    instance.  See [Block Devices](#block-devices) below for details.
    58  * `ephemeral_block_device` - (Optional) Customize Ephemeral (also known as
    59    "Instance Store") volumes on the instance. See [Block Devices](#block-devices) below for details.
    60  
    61  
    62  <a id="block-devices"></a>
    63  ## Block devices
    64  
    65  Each of the `*_block_device` attributes controls a portion of the AWS
    66  Instance's "Block Device Mapping". It's a good idea to familiarize yourself with [AWS's Block Device
    67  Mapping docs](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
    68  to understand the implications of using these attributes.
    69  
    70  The `root_block_device` mapping supports the following:
    71  
    72  * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`,
    73    or `"io1"`. (Default: `"standard"`).
    74  * `volume_size` - (Optional) The size of the volume in gigabytes.
    75  * `iops` - (Optional) The amount of provisioned
    76    [IOPS](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
    77    This must be set with a `volume_type` of `"io1"`.
    78  * `delete_on_termination` - (Optional) Whether the volume should be destroyed
    79    on instance termination (Default: `true`).
    80  
    81  Modifying any of the `root_block_device` settings requires resource
    82  replacement.
    83  
    84  Each `ebs_block_device` supports the following:
    85  
    86  * `device_name` - The name of the device to mount.
    87  * `snapshot_id` - (Optional) The Snapshot ID to mount.
    88  * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`,
    89    or `"io1"`. (Default: `"standard"`).
    90  * `volume_size` - (Optional) The size of the volume in gigabytes.
    91  * `iops` - (Optional) The amount of provisioned
    92    [IOPS](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
    93    This must be set with a `volume_type` of `"io1"`.
    94  * `delete_on_termination` - (Optional) Whether the volume should be destroyed
    95    on instance termination (Default: `true`).
    96  * `encrypted` - (Optional) Enables [EBS
    97    encryption](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html)
    98    on the volume (Default: `false`).
    99  
   100  Modifying any `ebs_block_device` currently requires resource replacement.
   101  
   102  Each `ephemeral_block_device` supports the following:
   103  
   104  * `device_name` - The name of the block device to mount on the instance.
   105  * `virtual_name` - The [Instance Store Device
   106    Name](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#InstanceStoreDeviceNames)
   107    (e.g. `"ephemeral0"`)
   108  
   109  Each AWS Instance type has a different set of Instance Store block devices
   110  available for attachment. AWS [publishes a
   111  list](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#StorageOnInstanceTypes)
   112  of which ephemeral devices are available on each type. The devices are always
   113  identified by the `virtual_name` in the format `"ephemeral{0..N}"`.
   114  
   115  ~> **NOTE:** Currently, changes to `*_block_device` configuration of _existing_
   116  resources cannot be automatically detected by Terraform. After making updates
   117  to block device configuration, resource recreation can be manually triggered by
   118  using the [`taint` command](/docs/commands/taint.html).
   119  
   120  ## Attributes Reference
   121  
   122  The following attributes are exported:
   123  
   124  * `id` - The instance ID.
   125  * `availability_zone` - The availability zone of the instance.
   126  * `placement_group` - The placement group of the instance.
   127  * `key_name` - The key name of the instance
   128  * `private_dns` - The Private DNS name of the instance
   129  * `private_ip` - The private IP address.
   130  * `public_dns` - The public DNS name of the instance
   131  * `public_ip` - The public IP address.
   132  * `security_groups` - The associated security groups.
   133  * `vpc_security_group_ids` - The associated security groups in non-default VPC
   134  * `subnet_id` - The VPC subnet ID.