packer-cn/website/source/docs/builders/amazon-instance.html.md.erb

---
description: |
    The amazon-instance Packer builder is able to create Amazon AMIs backed by
    instance storage as the root device. For more information on the difference
    between instance storage and EBS-backed instances, see the storage for the root
    device section in the EC2 documentation.
layout: docs
page_title: 'Amazon instance-store - Builders'
sidebar_current: 'docs-builders-amazon-instance'
---

# AMI Builder (instance-store)

Type: `amazon-instance`

The `amazon-instance` Packer builder is able to create Amazon AMIs backed by
instance storage as the root device. For more information on the difference
between instance storage and EBS-backed instances, see the ["storage for the
root device" section in the EC2
documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device).

This builder builds an AMI by launching an EC2 instance from an existing
instance-storage backed AMI, provisioning that running machine, and then
bundling and creating a new AMI from that machine. This is all done in your own
AWS account. This builder will create temporary key pairs, security group
rules, etc. that provide it temporary access to the instance while the image is
being created. This simplifies configuration quite a bit.

This builder does *not* manage AMIs. Once it creates an AMI and stores it in
your account, it is up to you to use, delete, etc. the AMI.

-> **Note:** Temporary resources are, by default, all created with the
prefix `packer`. This can be useful if you want to restrict the security groups
and key pairs packer is able to operate on.

-> **Note:** This builder requires that the [Amazon EC2 AMI
Tools](https://aws.amazon.com/developertools/368) are installed onto the
machine. This can be done within a provisioner, but must be done before the
builder finishes running.

\~> Instance builds are not supported for Windows. Use
[`amazon-ebs`](amazon-ebs.html) instead.

## Configuration Reference

There are many configuration options available for the builder. In addition to
the items listed here, you will want to look at the general configuration
references for [AMI](#ami-configuration),
[BlockDevices](#block-devices-configuration),
[Access](#access-configuration),
[Run](#run-configuration) and
[Communicator](#communicator-configuration)
configuration references, which are
necessary for this build to succeed and can be found further down the page.

### Required:

<%= partial "partials/builder/amazon/instance/Config-required" %>

### Optional:

<%= partial "partials/builder/amazon/instance/Config-not-required" %>


### AMI Configuration

#### Required:

<%= partial "partials/builder/amazon/common/AMIConfig-required" %>

#### Optional:
<%= partial "partials/builder/amazon/common/AMIConfig-not-required" %>

### Access Configuration

#### Required:

<%= partial "partials/builder/amazon/common/AccessConfig-required" %>

#### Optional:

<%= partial "partials/builder/amazon/common/AccessConfig-not-required" %>

### Run Configuration

#### Required:

<%= partial "partials/builder/amazon/common/RunConfig-required" %>

#### Optional:

<%= partial "partials/builder/amazon/common/RunConfig-not-required" %>


### Block Devices Configuration

Block devices can be nested in the
[ami_block_device_mappings](#ami_block_device_mappings) or the 
[launch_block_device_mappings](#launch_block_device_mappings) array.

<%= partial "partials/builder/amazon/common/BlockDevice" %>


#### Optional:
<%= partial "partials/builder/amazon/common/BlockDevice-not-required" %>

### Communicator Configuration

#### Optional:

<%= partial "partials/helper/communicator/Config-not-required" %>
<%= partial "partials/helper/communicator/SSH-not-required" %>
<%= partial "partials/helper/communicator/SSHInterface-not-required" %>

## Basic Example

Here is a basic example. It is completely valid except for the access keys:

``` json
{
  "type": "amazon-instance",
  "access_key": "YOUR KEY HERE",
  "secret_key": "YOUR SECRET KEY HERE",
  "region": "us-east-1",
  "source_ami": "ami-d9d6a6b0",
  "instance_type": "m1.small",
  "ssh_username": "ubuntu",

  "account_id": "0123-4567-0890",
  "s3_bucket": "packer-images",
  "x509_cert_path": "x509.cert",
  "x509_key_path": "x509.key",
  "x509_upload_path": "/tmp",

  "ami_name": "packer-quick-start {{timestamp}}"
}
```

-&gt; **Note:** Packer can also read the access key and secret access key from
environmental variables. See the configuration reference in the section above
for more information on what environmental variables Packer will look for.

## Accessing the Instance to Debug

If you need to access the instance to debug for some reason, run this builder
with the `-debug` flag. In debug mode, the Amazon builder will save the private
key in the current directory and will output the DNS or IP information as well.
You can use this information to access the instance as it is running.

## Build template data

In configuration directives marked as a template engine above, the following
variables are available:

-   `BuildRegion` - The region (for example `eu-central-1`) where Packer is
    building the AMI.
-   `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build
    the AMI.
-   `SourceAMIName` - The source AMI Name (for example
    `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
    build the AMI.
-   `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.

## Custom Bundle Commands

A lot of the process required for creating an instance-store backed AMI
involves commands being run on the actual source instance. Specifically, the
`ec2-bundle-vol` and `ec2-upload-bundle` commands must be used to bundle the
root filesystem and upload it, respectively.

Each of these commands have a lot of available flags. Instead of exposing each
possible flag as a template configuration option, the instance-store AMI
builder for Packer lets you customize the entire command used to bundle and
upload the AMI.

These are configured with `bundle_vol_command` and `bundle_upload_command`.
Both of these configurations are [configuration
templates](/docs/templates/engine.html) and have support for their own set of
template variables.

### Bundle Volume Command

The default value for `bundle_vol_command` is shown below. It is split across
multiple lines for convenience of reading. The bundle volume command is
responsible for executing `ec2-bundle-vol` in order to store and image of the
root filesystem to use to create the AMI.

``` text
sudo -i -n ec2-bundle-vol \
  -k {{.KeyPath}}  \
  -u {{.AccountId}} \
  -c {{.CertPath}} \
  -r {{.Architecture}} \
  -e {{.PrivatePath}}/* \
  -d {{.Destination}} \
  -p {{.Prefix}} \
  --batch \
  --no-filter
```

The available template variables should be self-explanatory based on the
parameters they're used to satisfy the `ec2-bundle-vol` command.

\~&gt; **Warning!** Some versions of ec2-bundle-vol silently ignore all .pem
and .gpg files during the bundling of the AMI, which can cause problems on some
systems, such as Ubuntu. You may want to customize the bundle volume command to
include those files (see the `--no-filter` option of `ec2-bundle-vol`).

### Bundle Upload Command

The default value for `bundle_upload_command` is shown below. It is split
across multiple lines for convenience of reading. Access key and secret key are
omitted if using instance profile. The bundle upload command is responsible for
taking the bundled volume and uploading it to S3.

``` text
sudo -i -n ec2-upload-bundle \
  -b {{.BucketName}} \
  -m {{.ManifestPath}} \
  -a {{.AccessKey}} \
  -s {{.SecretKey}} \
  -d {{.BundleDirectory}} \
  --batch \
  --region {{.Region}} \
  --retry
```

The available template variables should be self-explanatory based on the
parameters they're used to satisfy the `ec2-upload-bundle` command.
Additionally, `{{.Token}}` is available when overriding this command. You must
create your own bundle command with the addition of `-t {{.Token}}` if you are
assuming a role.

#### Bundle Upload Permissions

The `ec2-upload-bundle` requires a policy document that looks something like
this:

``` json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:PutObjectAcl"
            ],
            "Resource": "*"
        }
    ]
}
```

You may wish to constrain the resource to a specific bucket.


<%= partial "partials/builders/aws-ssh-differentiation-table" %>