website: document the amazon-instance builder

website/source/docs/builders/amazon-ebs.html.markdown

@@ -1,22 +1,17 @@
 ---
 layout: "docs"
+page_title: "Amazon AMI Builder (EBS backed)"
 ---
 
-# Amazon AMI Builder
+# AMI Builder (EBS backed)
 
 Type: `amazon-ebs`
 
 The `amazon-ebs` builder is able to create Amazon AMIs backed by EBS
-volumes for use in [EC2](http://aws.amazon.com/ec2/). The builder takes
+volumes for use in [EC2](http://aws.amazon.com/ec2/). For more information
-an initial source AMI, runs any provisioning necesary on the instance,
+on the difference betwen EBS-backed instances and instance-store backed
-and snapshots it into a reusable AMI.
+instances, see the
-
+["storage for the root device" section in the EC2 documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device).
-Amazon supports two types of AMIs: EBS-backed and instance-store. Instance
-store AMIs are considerably harder to create, requiring many platform-specific
-steps that can often take a very long time. EBS-backed AMIs, on the hand,
-only require a source AMI to exist. This builder only builds EBS-backed
-instances, because they are easier to create, especially across many
-platforms running Packer.
 
 This builder builds an AMI by launching an EC2 instance from a source AMI,
 provisioning that running machine, and then creating an AMI from that machine.

website/source/docs/builders/amazon-instance.html.markdown

@@ -0,0 +1,217 @@
+---
+layout: "docs"
+page_title: "Amazon AMI Builder (instance-store)"
+---
+
+# AMI Builder (instance-store)
+
+Type: `amazon-instance`
+
+The `amazon-instance` 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](http://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. The builder will create temporary
+keypairs, security group rules, etc. that provide it temporary access to
+the instance while the image is being created. This simplifies configuration
+quite a bit.
+
+The 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.
+
+## Configuration Reference
+
+There are many configuration options available for the builder. They are
+segmented below into two categories: required and optional parameters. Within
+each category, the available configuration keys are alphabetized.
+
+Required:
+
+* `access_key` (string) - The access key used to communicate with AWS.
+  If not specified, Packer will attempt to read this from environmental
+  variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order).
+
+* `account_id` (string) - Your AWS account ID. This is required for bundling
+  the AMI. This is _not the same_ as the access key. You can find your
+  account ID in the security credentials page of your AWS account.
+
+* `ami_name` (string) - The name of the resulting AMI that will appear
+  when managing AMIs in the AWS console or via APIs. This must be unique.
+  To help make this unique, certain template parameters are available for
+  this value, which are documented below.
+
+* `instance_type` (string) - The EC2 instance type to use while building
+  the AMI, such as "m1.small".
+
+* `region` (string) - The name of the region, such as "us-east-1", in which
+  to launch the EC2 instance to create the AMI.
+
+* `s3_bucket` (string) - The name of the S3 bucket to upload the AMI.
+  This bucket will be created if it doesn't exist.
+
+* `secret_key` (string) - The secret key used to communicate with AWS.
+  If not specified, Packer will attempt to read this from environmental
+  variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order).
+
+* `source_ami` (string) - The initial AMI used as a base for the newly
+  created machine.
+
+* `ssh_username` (string) - The username to use in order to communicate
+  over SSH to the running machine.
+
+* `x509_cert_path` (string) - The local path to a valid X509 certificate for
+  your AWS account. This is used for bundling the AMI. This X509 certificate
+  must be registered with your account from the security credentials page
+  in the AWS console.
+
+* `x509_key_path` (string) - The local path to the private key for the X509
+  certificate specified by `x509_cert_path`. This is used for bundling the AMI.
+
+Optional:
+
+* `bundle_destination` (string) - The directory on the running instance
+  where the bundled AMI will be saved prior to uploading. By default this is
+  "/tmp". This directory must exist and be writable.
+
+* `bundle_prefix` (string) - The prefix for files created from bundling
+  the root volume. By default this is "image-{{.Createtime}}". The `CreateTime`
+  variable should be used to make sure this is unique, otherwise it can
+  collide with other created AMIs by Packer in your account.
+
+* `bundle_upload_command` (string) - The command to use to upload the
+  bundled volume. See the "custom bundle commands" section below for more
+  information.
+
+* `bundle_vol_command` (string) - The command to use to bundle the volume.
+  See the "custom bundle commands" section below for more information.
+
+* `security_group_id` (string) - The ID (_not_ the name) of the security
+  group to assign to the instance. By default this is not set and Packer
+  will automatically create a new temporary security group to allow SSH
+  access. Note that if this is specified, you must be sure the security
+  group allows access to the `ssh_port` given below.
+
+* `ssh_port` (int) - The port that SSH will be available on. This defaults
+  to port 22.
+
+* `ssh_timeout` (string) - The time to wait for SSH to become available
+  before timing out. The format of this value is a duration such as "5s"
+  or "5m". The default SSH timeout is "1m", or one minute.
+
+* `subnet_id` (string) - If using VPC, the ID of the subnet, such as
+  "subnet-12345def", where Packer will launch the EC2 instance.
+
+* `vpc_id` (string) - If launching into a VPC subnet, Packer needs the
+  VPC ID in order to create a temporary security group within the VPC.
+
+* `x509_upload_path` (string) - The path on the remote machine where the
+  X509 certificate will be uploaded. This path must already exist and be
+  writable. X509 certificates are uploaded after provisioning is run, so
+  it is perfectly okay to create this directory as part of the provisioning
+  process.
+
+## Basic Example
+
+Here is a basic example. It is completely valid except for the access keys:
+
+<pre class="prettyprint">
+{
+  "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 {{.CreateTime}}"
+}
+</pre>
+
+<div class="alert alert-block alert-info">
+<strong>Note:</strong> 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.
+</div>
+
+## AMI Name Variables
+
+The AMI name specified by the `ami_name` configuration variable is actually
+treated as a [configuration template](/docs/templates/configuration-templates.html).
+Packer provides a set of variables that it will replace
+within the AMI name. This helps ensure the AMI name is unique, as AWS requires.
+
+The available variables are shown below:
+
+* `CreateTime` - This will be replaced with the Unix timestamp of when
+  the AMI was built.
+
+## 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/configuration-templates.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.
+
+```
+sudo -n ec2-bundle-vol \
+	-k {{.KeyPath}}  \
+	-u {{.AccountId}} \
+	-c {{.CertPath}} \
+	-r {{.Architecture}} \
+	-e {{.PrivatePath}} \
+	-d {{.Destination}} \
+	-p {{.Prefix}} \
+	--batch
+```
+
+The available template variables should be self-explanatory based on the
+parameters they're used to satisfy the `ec2-bundle-vol` command.
+
+### Bundle Upload Command
+
+The default value for `bundle_upload_command` is shown below. It is split
+across multiple lines for convenience of reading. The bundle upload command
+is responsible for taking the bundled volume and uploading it to S3.
+
+```
+sudo -n ec2-upload-bundle \
+	-b {{.BucketName}} \
+	-m {{.ManifestPath}} \
+	-a {{.AccessKey}} \
+	-s {{.SecretKey}} \
+	-d {{.BundleDirectory}} \
+	--batch \
+	--retry
+```
+
+The available template variables should be self-explanatory based on the
+parameters they're used to satisfy the `ec2-upload-bundle` command.

website/source/docs/builders/amazon.html.markdown

@@ -0,0 +1,25 @@
+---
+layout: "docs"
+page_title: "Amazon AMI Builder"
+---
+
+# Amazon AMI Builder
+
+Packer is able to create Amazon AMIs. To achieve this, Packer comes with
+multiple builders depending on the strategy you want to use to build the
+AMI. Packer supports the following builders at the moment:
+
+* [amazon-ebs](/docs/builders/amazon-ebs.html) - Create EBS-backed AMIs
+  by launching a source instance and re-packaging it into a new AMI after
+  provisioning. If in doubt, use this builder, which is the easiest to get
+  started with.
+
+* [amazon-instance](/docs/builders/amazon-instance.html) - Create
+  instance-store AMIs by launching and provisioning a source instance, then
+  rebundling it and uploading it to S3.
+
+<div class="alert alert-block alert-info">
+<strong>Don't know which builder to use?</strong> If in doubt, use the
+<a href="/docs/builders/amazon-ebs.html">amazon-ebs builder</a>. It is
+much easier to use and Amazon generally recommends EBS-backed images nowadays.
+</div>

website/source/layouts/docs.erb

@@ -27,7 +27,7 @@
 
 		<ul>
 			<li><h4>Builders</h4></li>
-			<li><a href="/docs/builders/amazon-ebs.html">Amazon EC2 (AMI)</a></li>
+			<li><a href="/docs/builders/amazon.html">Amazon EC2 (AMI)</a></li>
 			<li><a href="/docs/builders/digitalocean.html">DigitalOcean</a></li>
 			<li><a href="/docs/builders/virtualbox.html">VirtualBox</a></li>
 			<li><a href="/docs/builders/vmware.html">VMware</a></li>