website: docs for amazon-chroot
This commit is contained in:
Mitchell Hashimoto
parent
3865c33be1
commit
750b788344
|
|
@ -0,0 +1,177 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Amazon AMI Builder (chroot)"
|
||||
---
|
||||
|
||||
# AMI Builder (chroot)
|
||||
|
||||
Type: `amazon-chroot`
|
||||
|
||||
The `amazon-chroot` builder is able to create Amazon AMIs backed by
|
||||
an EBS volume 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).
|
||||
|
||||
The difference between this builder and the `amazon-ebs` builder is that
|
||||
this builder is able to build an EBS-backed AMI without launching a new
|
||||
EC2 instance. This can dramatically speed up AMI builds for organizations
|
||||
who need the extra fast build.
|
||||
|
||||
<div class="alert alert-block alert-warn">
|
||||
<p><strong>This is an advanced builder.</strong> If you're just getting
|
||||
started with Packer, we recommend starting with the
|
||||
<a href="/docs/builders/amazon-ebs.html">amazon-ebs builder</a>, which is
|
||||
much easier to use.</p>
|
||||
</div>
|
||||
|
||||
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.
|
||||
|
||||
## How Does it Work?
|
||||
|
||||
This builder works by creating a new EBS volume from an existing source AMI
|
||||
and attaching it into an already-running EC2 instance. One attached, a
|
||||
[chroot](http://en.wikipedia.org/wiki/Chroot) is used to provision the
|
||||
system within that volume. After provisioning, the volume is detached,
|
||||
snapshotted, and an AMI is made.
|
||||
|
||||
Using this process, minutes can be shaved off the AMI creation process
|
||||
because a new EC2 instance doesn't need to be launched.
|
||||
|
||||
There are some restrictions, however. The host EC2 instance where the
|
||||
volume is attached to must be a similar system (generally the same OS
|
||||
version, kernel versions, etc.) as the AMI being built. Additionally,
|
||||
this process is much more expensive because the EC2 instance must be kept
|
||||
running persistently in order to build AMIs, whereas the other AMI builders
|
||||
start instances on-demand to build AMIs as needed.
|
||||
|
||||
## 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).
|
||||
If the environmental variables aren't set and Packer is running on
|
||||
an EC2 instance, Packer will check the instance metadata for IAM role
|
||||
keys.
|
||||
|
||||
* `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.
|
||||
|
||||
* `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).
|
||||
If the environmental variables aren't set and Packer is running on
|
||||
an EC2 instance, Packer will check the instance metadata for IAM role
|
||||
keys.
|
||||
|
||||
* `source_ami` (string) - The source AMI whose root volume will be copied
|
||||
and provisioned on the currently running instance. This must be an
|
||||
EBS-backed AMI with a root volume snapshot that you have access to.
|
||||
|
||||
Optional:
|
||||
|
||||
* `chroot_mounts` (list of list of strings) - This is a list of additional
|
||||
devices to mount into the chroot environment. This configuration parameter
|
||||
requires some additional documentation which is in the "Chroot Mounts" section
|
||||
below. Please read that section for more information on how to use this.
|
||||
|
||||
* `copy_files` (list of strings) - Paths to files on the running EC2 instance
|
||||
that will be copied into the chroot environment prior to provisioning.
|
||||
This is useful, for example, to copy `/etc/resolv.conf` so that DNS lookups
|
||||
work.
|
||||
|
||||
* `device_path` (string) - The path to the device where the root volume
|
||||
of the source AMI will be attached. This defaults to "" (empty string),
|
||||
which forces Packer to find an open device automatically.
|
||||
|
||||
* `mount_command` (string) - The command to use to mount devices. This
|
||||
defaults to "mount". This may be useful to set if you want to set
|
||||
environmental variables or perhaps run it with `sudo` or so on.
|
||||
|
||||
* `mount_path` (string) - The path where the volume will be mounted. This is
|
||||
where the chroot environment will be. This defaults to
|
||||
`packer-amazon-chroot-volumes/{{.Device}}`. This is a configuration
|
||||
template where the `.Device` variable is replaced with the name of the
|
||||
device where the volume is attached.
|
||||
|
||||
* `unmount_command` (string) - Just like `mount_command`, except this is
|
||||
the command to unmount devices.
|
||||
|
||||
## Basic Example
|
||||
|
||||
Here is a basic example. It is completely valid except for the access keys:
|
||||
|
||||
<pre class="prettyprint">
|
||||
{
|
||||
"type": "amazon-chroot",
|
||||
"access_key": "YOUR KEY HERE",
|
||||
"secret_key": "YOUR SECRET KEY HERE",
|
||||
"source_ami": "ami-e81d5881",
|
||||
"ami_name": "packer-amazon-chroot {{.CreateTime}}"
|
||||
}
|
||||
</pre>
|
||||
|
||||
## 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.
|
||||
|
||||
## Chroot Mounts
|
||||
|
||||
The `chroot_mounts` configuration can be used to mount additional devices
|
||||
within the chroot. By default, the following additional mounts are added
|
||||
into the chroot by Packer:
|
||||
|
||||
* `/proc` (proc)
|
||||
* `/sys` (sysfs)
|
||||
* `/dev` (bind to real `/dev`)
|
||||
* `/dev/pts` (devpts)
|
||||
* `/proc/sys/fs/binfmt_misc` (binfmt_misc)
|
||||
|
||||
These default mounts are usually good enough for anyone and are sane
|
||||
defaults. However, if you want to change or add the mount points, you may
|
||||
using the `chroot_mounts` configuration. Here is an example configuration:
|
||||
|
||||
<pre class="prettyprint">
|
||||
{
|
||||
"chroot_mounts": [
|
||||
["proc", "proc", "/proc"],
|
||||
["bind", "/dev", "/dev"]
|
||||
]
|
||||
}
|
||||
</pre>
|
||||
|
||||
`chroot_mounts` is a list of a 3-tuples of strings. The three components
|
||||
of the 3-tuple, in order, are:
|
||||
|
||||
* The filesystem type. If this is "bind", then Packer will properly bind
|
||||
the filesystem to another mount point.
|
||||
|
||||
* The source device.
|
||||
|
||||
* The mount directory.
|
||||
|
||||
## Parallelism
|
||||
|
||||
A quick note on parallelism: it is perfectly safe to run multiple
|
||||
_separate_ Packer processes with the `amazon-chroot` builder on the same
|
||||
EC2 instance. In fact, this is recommended as a way to push the most performance
|
||||
out of your AMI builds.
|
||||
|
||||
Packer properly obtains a process lock for the parallelism-sensitive parts
|
||||
of its internals such as finding an available device.
|
||||
|
|
@ -18,6 +18,13 @@ AMI. Packer supports the following builders at the moment:
|
|||
instance-store AMIs by launching and provisioning a source instance, then
|
||||
rebundling it and uploading it to S3.
|
||||
|
||||
* [amazon-chroot](/docs/builders/amazon-chroot.html) - Create EBS-backed AMIs
|
||||
from an existing EC2 instance by mounting the root device and using a
|
||||
[Chroot](http://en.wikipedia.org/wiki/Chroot) environment to provision
|
||||
that device. This is an **advanced builder and should not be used by
|
||||
newcomers**. However, it is also the fastest way to build an EBS-backed
|
||||
AMI since no new EC2 instance needs to be launched.
|
||||
|
||||
<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
|
||||
|
|
|
|||
Loading…
Reference in New Issue