website: document the amazon-instance builder
This commit is contained in:
Mitchell Hashimoto
parent
d46741e4f7
commit
321d1cce16
|
|
@ -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
|
||||
an initial source AMI, runs any provisioning necesary on the instance,
|
||||
and snapshots it into a reusable AMI.
|
||||
|
||||
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.
|
||||
volumes for use in [EC2](http://aws.amazon.com/ec2/). For more information
|
||||
on the difference betwen EBS-backed instances and instance-store 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 a source AMI,
|
||||
provisioning that running machine, and then creating an AMI from that machine.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue