github.com/ndarilek/terraform@v0.3.8-0.20150320140257-d3135c1b2bac/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  * `ebs_optimized` - (Optional) If true, the launched EC2 instance will be
    35       EBS-optimized.
    36  * `instance_type` - (Required) The type of instance to start
    37  * `key_name` - (Optional) The key name to use for the instance.
    38  * `security_groups` - (Optional) A list of security group IDs or names to associate with.
    39     If you are within a non-default VPC, you'll need to use the security group ID. Otherwise,
    40     for EC2 and the default VPC, use the security group name.
    41  * `subnet_id` - (Optional) The VPC Subnet ID to launch in.
    42  * `associate_public_ip_address` - (Optional) Associate a public ip address with an instance in a VPC.
    43  * `private_ip` - (Optional) Private IP address to associate with the
    44       instance in a VPC.
    45  * `source_dest_check` - (Optional) Controls if traffic is routed to the instance when
    46    the destination address does not match the instance. Used for NAT or VPNs. Defaults true.
    47  * `user_data` - (Optional) The user data to provide when launching the instance.
    48  * `iam_instance_profile` - (Optional) The IAM Instance Profile to
    49    launch the instance with.
    50  * `tags` - (Optional) A mapping of tags to assign to the resource.
    51  * `root_block_device` - (Optional) Customize details about the root block
    52    device of the instance. See [Block Devices](#block-devices) below for details.
    53  * `ebs_block_device` - (Optional) Additional EBS block devices to attach to the
    54    instance.  See [Block Devices](#block-devices) below for details.
    55  * `ephemeral_block_device` - (Optional) Customize Ephemeral (also known as
    56    "Instance Store") volumes on the instance. See [Block Devices](#block-devices) below for details.
    57  
    58  
    59  <a id="block-devices"></a>
    60  ## Block devices
    61  
    62  Each of the `*_block_device` attributes controls a portion of the AWS
    63  Instance's "Block Device Mapping". It's a good idea to familiarize yourself with [AWS's Block Device
    64  Mapping docs](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
    65  to understand the implications of using these attributes.
    66  
    67  The `root_block_device` mapping supports the following:
    68  
    69  * `device_name` - The name of the root device on the target instance. Must
    70    match the root device as defined in the AMI. Defaults to `"/dev/sda1"`, which
    71    is the typical root volume for Linux instances.
    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  
   116  ~> **NOTE:** Because AWS [does not expose Instance Store mapping
   117  details](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html#bdm-instance-metadata)
   118  via an externally accessible API, `ephemeral_block_device` configuration may
   119  only be applied at instance creation time, and changes to configuration of
   120  existing resources cannot be detected by Terraform. Updates to Instance Store
   121  block device configuration can be manually triggered by using the [`taint`
   122  command](/docs/commands/taint.html).
   123  
   124  
   125  ## Attributes Reference
   126  
   127  The following attributes are exported:
   128  
   129  * `id` - The instance ID.
   130  * `availability_zone` - The availability zone of the instance.
   131  * `key_name` - The key name of the instance
   132  * `private_dns` - The Private DNS name of the instance
   133  * `private_ip` - The private IP address.
   134  * `public_dns` - The public DNS name of the instance
   135  * `public_ip` - The public IP address.
   136  * `security_groups` - The associated security groups.
   137  * `subnet_id` - The VPC subnet ID.