github.com/tarrant/terraform@v0.3.8-0.20150402012457-f68c9eee638e/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  * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`,
    70    or `"io1"`. (Default: `"standard"`).
    71  * `volume_size` - (Optional) The size of the volume in gigabytes.
    72  * `iops` - (Optional) The amount of provisioned
    73    [IOPS](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
    74    This must be set with a `volume_type` of `"io1"`.
    75  * `delete_on_termination` - (Optional) Whether the volume should be destroyed
    76    on instance termination (Default: `true`).
    77  
    78  Modifying any of the `root_block_device` settings requires resource
    79  replacement.
    80  
    81  Each `ebs_block_device` supports the following:
    82  
    83  * `device_name` - The name of the device to mount.
    84  * `snapshot_id` - (Optional) The Snapshot ID to mount.
    85  * `volume_type` - (Optional) The type of volume. Can be `"standard"`, `"gp2"`,
    86    or `"io1"`. (Default: `"standard"`).
    87  * `volume_size` - (Optional) The size of the volume in gigabytes.
    88  * `iops` - (Optional) The amount of provisioned
    89    [IOPS](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html).
    90    This must be set with a `volume_type` of `"io1"`.
    91  * `delete_on_termination` - (Optional) Whether the volume should be destroyed
    92    on instance termination (Default: `true`).
    93  * `encrypted` - (Optional) Enables [EBS
    94    encryption](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html)
    95    on the volume (Default: `false`).
    96  
    97  Modifying any `ebs_block_device` currently requires resource replacement.
    98  
    99  Each `ephemeral_block_device` supports the following:
   100  
   101  * `device_name` - The name of the block device to mount on the instance.
   102  * `virtual_name` - The [Instance Store Device
   103    Name](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#InstanceStoreDeviceNames)
   104    (e.g. `"ephemeral0"`)
   105  
   106  Each AWS Instance type has a different set of Instance Store block devices
   107  available for attachment. AWS [publishes a
   108  list](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#StorageOnInstanceTypes)
   109  of which ephemeral devices are available on each type. The devices are always
   110  identified by the `virtual_name` in the format `"ephemeral{0..N}"`.
   111  
   112  
   113  ~> **NOTE:** Because AWS [does not expose Instance Store mapping
   114  details](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html#bdm-instance-metadata)
   115  via an externally accessible API, `ephemeral_block_device` configuration may
   116  only be applied at instance creation time, and changes to configuration of
   117  existing resources cannot be detected by Terraform. Updates to Instance Store
   118  block device configuration can be manually triggered by using the [`taint`
   119  command](/docs/commands/taint.html).
   120  
   121  
   122  ## Attributes Reference
   123  
   124  The following attributes are exported:
   125  
   126  * `id` - The instance ID.
   127  * `availability_zone` - The availability zone of the instance.
   128  * `key_name` - The key name of the instance
   129  * `private_dns` - The Private DNS name of the instance
   130  * `private_ip` - The private IP address.
   131  * `public_dns` - The public DNS name of the instance
   132  * `public_ip` - The public IP address.
   133  * `security_groups` - The associated security groups.
   134  * `subnet_id` - The VPC subnet ID.