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

329 lines
13 KiB
Plaintext
Raw Normal View History

2013-07-31 01:17:58 -04:00
---
2015-07-22 22:31:00 -04:00
description: |
The `amazon-chroot` Packer 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, storage for the root device section
in the EC2 documentation.
layout: docs
page_title: 'Amazon AMI Builder (chroot)'
---
2013-07-31 01:17:58 -04:00
# AMI Builder (chroot)
Type: `amazon-chroot`
2015-07-22 22:31:00 -04:00
The `amazon-chroot` Packer 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
2016-01-14 15:31:19 -05:00
documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device).
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
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.
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
\~> **This is an advanced builder** If you're just getting started with
Packer, we recommend starting with the [amazon-ebs
builder](/docs/builders/amazon-ebs.html), which is much easier to use.
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
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.
2013-07-31 01:17:58 -04:00
## How Does it Work?
2015-07-22 22:31:00 -04:00
This builder works by creating a new EBS volume from an existing source AMI and
attaching it into an already-running EC2 instance. Once attached, a
2016-01-14 15:31:19 -05:00
[chroot](https://en.wikipedia.org/wiki/Chroot) is used to provision the system
2015-07-22 22:31:00 -04:00
within that volume. After provisioning, the volume is detached, snapshotted, and
an AMI is made.
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
Using this process, minutes can be shaved off the AMI creation process because a
new EC2 instance doesn't need to be launched.
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
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.
2013-07-31 01:17:58 -04:00
## 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:
2013-07-31 01:17:58 -04:00
2015-07-24 23:55:08 -04:00
- `access_key` (string) - The access key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
2013-07-31 01:17:58 -04:00
2015-07-24 23:55:08 -04:00
- `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, use a function like `timestamp` (see [configuration
templates](/docs/templates/configuration-templates.html) for more info)
2013-07-31 01:17:58 -04:00
2015-07-24 23:55:08 -04:00
- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
2013-07-31 01:17:58 -04:00
2015-07-24 23:55:08 -04:00
- `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. Note: this is not
used when `from_scratch` is set to true.
2013-07-31 01:17:58 -04:00
### Optional:
2015-07-22 23:25:58 -04:00
- `ami_description` (string) - The description to set for the
resulting AMI(s). By default this description is empty.
2015-07-22 23:25:58 -04:00
- `ami_groups` (array of strings) - A list of groups that have access to
launch the resulting AMI(s). By default no groups have permission to launch
the AMI. `all` will make the AMI publicly accessible.
2015-07-22 23:25:58 -04:00
- `ami_product_codes` (array of strings) - A list of product codes to
associate with the AMI. By default no product codes are associated with
the AMI.
2015-07-22 23:25:58 -04:00
- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
Tags and attributes are copied along with the AMI. AMI copying takes time
depending on the size of the AMI, but will generally take many minutes.
2015-07-22 23:25:58 -04:00
- `ami_users` (array of strings) - A list of account IDs that have access to
launch the resulting AMI(s). By default no additional users other than the
user creating the AMI has permissions to launch it.
2015-07-22 23:25:58 -04:00
- `ami_virtualization_type` (string) - The type of virtualization for the AMI
you are building. This option is required to register HVM images. Can be
"paravirtual" (default) or "hvm".
- `chroot_mounts` (array of array of strings) - This is a list of devices
to mount into the chroot environment. This configuration parameter
2015-07-22 23:25:58 -04:00
requires some additional documentation which is in the "Chroot Mounts"
section below. Please read that section for more information on how to
use this.
2013-07-31 01:17:58 -04:00
- `command_wrapper` (string) - How to run shell commands. This defaults to
`{{.Command}}`. This may be useful to set if you want to set environmental
variables or perhaps run it with `sudo` or so on. This is a configuration
template where the `.Command` variable is replaced with the command to
be run. Defaults to "{{.Command}}".
2015-07-22 23:25:58 -04:00
- `copy_files` (array of strings) - Paths to files on the running EC2 instance
that will be copied into the chroot environment prior to provisioning. Defaults
to `/etc/resolv.conf` so that DNS lookups work.
2013-07-31 01:17:58 -04:00
2015-07-22 23:25:58 -04:00
- `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.
2013-07-31 01:17:58 -04:00
2015-07-22 23:25:58 -04:00
- `enhanced_networking` (boolean) - Enable enhanced
networking (SriovNetSupport) on HVM-compatible AMIs. If true, add
2015-07-22 23:25:58 -04:00
`ec2:ModifyInstanceAttribute` to your AWS IAM policy.
2014-06-04 18:13:28 -04:00
2015-07-22 23:25:58 -04:00
- `force_deregister` (boolean) - Force Packer to first deregister an existing
AMI if one with the same name already exists. Default `false`.
2015-06-15 11:01:32 -04:00
- `from_scratch` (boolean) - Build a new volume instead of starting from an
existing AMI root volume snapshot. Default `false`. If true, `source_ami` is
no longer used and the following options become required:
`ami_virtualization_type`, `pre_mount_commands` and `root_volume_size`. The
below options are also required in this mode only:
- `ami_block_device_mappings` (array of block device mappings) - Add the block
device mappings to the AMI. A `device_name` entry matching `root_device_name`
should be set. The block device mappings allow for keys:
<%= partial "partials/builders/ami-block-device-mappings" %>
- `root_device_name` (string) - The root device name. For example, `xvda`.
2015-07-22 23:25:58 -04:00
- `mount_path` (string) - The path where the volume will be mounted. This is
where the chroot environment will be. This defaults to
`/mnt/packer-amazon-chroot-volumes/{{.Device}}`. This is a configuration template
2015-07-22 23:25:58 -04:00
where the `.Device` variable is replaced with the name of the device where
the volume is attached.
2013-07-31 01:17:58 -04:00
- `mount_partition` (integer) - The partition number containing the
/ partition. By default this is the first partition of the volume.
2015-07-22 23:25:58 -04:00
- `mount_options` (array of strings) - Options to supply the `mount` command
when mounting devices. Each option will be prefixed with `-o` and supplied
to the `mount` command ran by Packer. Because this command is ran in a
shell, user discrestion is advised. See [this manual page for the mount
command](http://linuxcommand.org/man_pages/mount8.html) for valid file
system specific options
- `pre_mount_commands` (array of strings) - A series of commands to execute
after attaching the root volume and before mounting the chroot. This is not
required unless using `from_scratch`. If so, this should include any
partitioning and filesystem creation commands. The path to the device is
provided by `{{.Device}}`.
- `post_mount_commands` (array of strings) - As `pre_mount_commands`, but the
commands are executed after mounting the root device and before the extra
mount and copy steps. The device and mount path are provided by
`{{.Device}}` and `{{.MountPath}}`.
- `root_volume_size` (integer) - The size of the root volume in GB for the
chroot environment and the resulting AMI. Default size is the snapshot size
of the `source_ami` unless `from_scratch` is `true`, in which case
this field must be defined.
- `skip_region_validation` (boolean) - Set to true if you want to skip
validation of the `ami_regions` configuration option. Default `false`.
- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
Example:
``` {.javascript}
"source_ami_filter": {
"filters": {
"virtualization-type": "hvm",
"name": "*ubuntu-xenial-16.04-amd64-server-*",
"root-device-type": "ebs"
},
"owners": ["099720109477"],
"most_recent": true
}
```
This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical.
2016-10-14 14:51:19 -04:00
NOTE: This will fail unless *exactly* one AMI is returned. In the above
example, `most_recent` will cause this to succeed by selecting the newest image.
- `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless *exactly* one AMI is returned.
Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
This is helpful to limit the AMIs to a trusted third party, or to your own account.
- `most_recent` (bool) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
They will override AMI tags if already applied to snapshot.
2015-07-22 23:25:58 -04:00
- `tags` (object of key/value strings) - Tags applied to the AMI.
2013-07-31 01:17:58 -04:00
## Basic Example
Here is a basic example. It is completely valid except for the access keys:
2015-07-22 22:31:00 -04:00
``` {.javascript}
2013-07-31 01:17:58 -04:00
{
"type": "amazon-chroot",
"access_key": "YOUR KEY HERE",
"secret_key": "YOUR SECRET KEY HERE",
"source_ami": "ami-e81d5881",
"ami_name": "packer-amazon-chroot {{timestamp}}"
2013-07-31 01:17:58 -04:00
}
```
2013-07-31 01:17:58 -04:00
## Chroot Mounts
The `chroot_mounts` configuration can be used to mount specific devices within
2015-07-22 22:31:00 -04:00
the chroot. By default, the following additional mounts are added into the
chroot by Packer:
2013-07-31 01:17:58 -04:00
2015-07-22 23:25:58 -04:00
- `/proc` (proc)
- `/sys` (sysfs)
- `/dev` (bind to real `/dev`)
- `/dev/pts` (devpts)
- `/proc/sys/fs/binfmt_misc` (binfmt\_misc)
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
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 which only
mounts `/prod` and `/dev`:
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
``` {.javascript}
2013-07-31 01:17:58 -04:00
{
"chroot_mounts": [
["proc", "proc", "/proc"],
["bind", "/dev", "/dev"]
]
}
```
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
`chroot_mounts` is a list of a 3-tuples of strings. The three components of the
3-tuple, in order, are:
2013-07-31 01:17:58 -04:00
2015-07-22 23:25:58 -04:00
- The filesystem type. If this is "bind", then Packer will properly bind the
filesystem to another mount point.
2013-07-31 01:17:58 -04:00
2015-07-22 23:25:58 -04:00
- The source device.
2013-07-31 01:17:58 -04:00
2015-07-22 23:25:58 -04:00
- The mount directory.
2013-07-31 01:17:58 -04:00
## Parallelism
2015-07-22 22:31:00 -04:00
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.
2013-07-31 01:17:58 -04:00
2015-07-22 22:31:00 -04:00
Packer properly obtains a process lock for the parallelism-sensitive parts of
its internals such as finding an available device.
## Gotchas
One of the difficulties with using the chroot builder is that your provisioning
scripts must not leave any processes running or packer will be unable to unmount
the filesystem.
2015-07-22 22:31:00 -04:00
For debian based distributions you can setup a
[policy-rc.d](http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt)
file which will prevent packages installed by your provisioners from starting
services:
2015-07-22 22:31:00 -04:00
``` {.javascript}
{
"type": "shell",
"inline": [
"echo '#!/bin/sh' > /usr/sbin/policy-rc.d",
"echo 'exit 101' >> /usr/sbin/policy-rc.d",
"chmod a+x /usr/sbin/policy-rc.d"
]
},
// ...
{
"type": "shell",
"inline": [
"rm -f /usr/sbin/policy-rc.d"
]
}
```
## Building From Scratch
This example demonstrates the essentials of building an image from scratch. A
15G gp2 (SSD) device is created (overriding the default of standard/magnetic).
The device setup commands partition the device with one partition for use as an
HVM image and format it ext4. This builder block should be followed by
provisioning commands to install the os and bootloader.
``` {.javascript}
{
"type": "amazon-chroot",
"ami_name": "packer-from-scratch {{timestamp}}"
"from_scratch": true,
"ami_virtualization_type": "hvm",
"device_setup_commands": [
"parted {{.Device}} mklabel msdos mkpart primary 1M 100% set 1 boot on print",
"mkfs.ext4 {{.Device}}1"
],
"root_volume_size": 15,
"root_device_name": "xvda",
"ami_block_device_mappings": [
{
"device_name": "xvda",
"delete_on_termination": true,
"volume_type": "gp2"
}
]
}
```