github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/amazon-chroot.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "Amazon AMI Builder (chroot)" 4 description: |- 5 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. 6 --- 7 8 # AMI Builder (chroot) 9 10 Type: `amazon-chroot` 11 12 The `amazon-chroot` Packer builder is able to create Amazon AMIs backed by 13 an EBS volume as the root device. For more information on the difference 14 between instance storage and EBS-backed instances, see the 15 ["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). 16 17 The difference between this builder and the `amazon-ebs` builder is that 18 this builder is able to build an EBS-backed AMI without launching a new 19 EC2 instance. This can dramatically speed up AMI builds for organizations 20 who need the extra fast build. 21 22 ~> **This is an advanced builder** If you're just getting 23 started with Packer, we recommend starting with the 24 [amazon-ebs builder](/docs/builders/amazon-ebs.html), which is 25 much easier to use. 26 27 The builder does _not_ manage AMIs. Once it creates an AMI and stores it 28 in your account, it is up to you to use, delete, etc. the AMI. 29 30 ## How Does it Work? 31 32 This builder works by creating a new EBS volume from an existing source AMI 33 and attaching it into an already-running EC2 instance. Once attached, a 34 [chroot](http://en.wikipedia.org/wiki/Chroot) is used to provision the 35 system within that volume. After provisioning, the volume is detached, 36 snapshotted, and an AMI is made. 37 38 Using this process, minutes can be shaved off the AMI creation process 39 because a new EC2 instance doesn't need to be launched. 40 41 There are some restrictions, however. The host EC2 instance where the 42 volume is attached to must be a similar system (generally the same OS 43 version, kernel versions, etc.) as the AMI being built. Additionally, 44 this process is much more expensive because the EC2 instance must be kept 45 running persistently in order to build AMIs, whereas the other AMI builders 46 start instances on-demand to build AMIs as needed. 47 48 ## Configuration Reference 49 50 There are many configuration options available for the builder. They are 51 segmented below into two categories: required and optional parameters. Within 52 each category, the available configuration keys are alphabetized. 53 54 In addition to the options listed here, a 55 [communicator](/docs/templates/communicator.html) 56 can be configured for this builder. 57 58 ### Required: 59 60 * `access_key` (string) - The access key used to communicate with AWS. 61 If not specified, Packer will use the key from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file 62 or fall back to environment variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order), if set. 63 If the environmental variables aren't set and Packer is running on 64 an EC2 instance, Packer will check the instance metadata for IAM role 65 keys. 66 67 * `ami_name` (string) - The name of the resulting AMI that will appear 68 when managing AMIs in the AWS console or via APIs. This must be unique. 69 To help make this unique, use a function like `timestamp` (see 70 [configuration templates](/docs/templates/configuration-templates.html) for more info) 71 72 * `secret_key` (string) - The secret key used to communicate with AWS. 73 If not specified, Packer will use the secret from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file 74 or fall back to environment variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order), if set. 75 If the environmental variables aren't set and Packer is running on 76 an EC2 instance, Packer will check the instance metadata for IAM role 77 keys. 78 79 * `source_ami` (string) - The source AMI whose root volume will be copied 80 and provisioned on the currently running instance. This must be an 81 EBS-backed AMI with a root volume snapshot that you have access to. 82 83 ### Optional: 84 85 * `ami_description` (string) - The description to set for the resulting 86 AMI(s). By default this description is empty. 87 88 * `ami_groups` (array of strings) - A list of groups that have access 89 to launch the resulting AMI(s). By default no groups have permission 90 to launch the AMI. `all` will make the AMI publicly accessible. 91 92 * `ami_product_codes` (array of strings) - A list of product codes to 93 associate with the AMI. By default no product codes are associated with 94 the AMI. 95 96 * `ami_regions` (array of strings) - A list of regions to copy the AMI to. 97 Tags and attributes are copied along with the AMI. AMI copying takes time 98 depending on the size of the AMI, but will generally take many minutes. 99 100 * `ami_users` (array of strings) - A list of account IDs that have access 101 to launch the resulting AMI(s). By default no additional users other than the user 102 creating the AMI has permissions to launch it. 103 104 * `ami_virtualization_type` (string) - The type of virtualization for the AMI 105 you are building. This option is required to register HVM images. Can be 106 "paravirtual" (default) or "hvm". 107 108 * `chroot_mounts` (array of array of strings) - This is a list of additional 109 devices to mount into the chroot environment. This configuration parameter 110 requires some additional documentation which is in the "Chroot Mounts" section 111 below. Please read that section for more information on how to use this. 112 113 * `command_wrapper` (string) - How to run shell commands. This 114 defaults to "{{.Command}}". This may be useful to set if you want to set 115 environmental variables or perhaps run it with `sudo` or so on. This is a 116 configuration template where the `.Command` variable is replaced with the 117 command to be run. 118 119 * `copy_files` (array of strings) - Paths to files on the running EC2 instance 120 that will be copied into the chroot environment prior to provisioning. 121 This is useful, for example, to copy `/etc/resolv.conf` so that DNS lookups 122 work. 123 124 * `device_path` (string) - The path to the device where the root volume 125 of the source AMI will be attached. This defaults to "" (empty string), 126 which forces Packer to find an open device automatically. 127 128 * `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) on 129 HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. 130 131 * `force_deregister` (boolean) - Force Packer to first deregister an existing 132 AMI if one with the same name already exists. Default `false`. 133 134 * `mount_path` (string) - The path where the volume will be mounted. This is 135 where the chroot environment will be. This defaults to 136 `packer-amazon-chroot-volumes/{{.Device}}`. This is a configuration 137 template where the `.Device` variable is replaced with the name of the 138 device where the volume is attached. 139 140 * `mount_options` (array of strings) - Options to supply the `mount` command 141 when mounting devices. Each option will be prefixed with `-o ` and supplied to 142 the `mount` command ran by Packer. Because this command is ran in a shell, user 143 discrestion is advised. See [this manual page for the mount command][1] for valid 144 file system specific options 145 146 * `root_volume_size` (integer) - The size of the root volume for the chroot 147 environment, and the resulting AMI 148 149 * `tags` (object of key/value strings) - Tags applied to the AMI. 150 151 ## Basic Example 152 153 Here is a basic example. It is completely valid except for the access keys: 154 155 ```javascript 156 { 157 "type": "amazon-chroot", 158 "access_key": "YOUR KEY HERE", 159 "secret_key": "YOUR SECRET KEY HERE", 160 "source_ami": "ami-e81d5881", 161 "ami_name": "packer-amazon-chroot {{timestamp}}" 162 } 163 ``` 164 165 ## Chroot Mounts 166 167 The `chroot_mounts` configuration can be used to mount additional devices 168 within the chroot. By default, the following additional mounts are added 169 into the chroot by Packer: 170 171 * `/proc` (proc) 172 * `/sys` (sysfs) 173 * `/dev` (bind to real `/dev`) 174 * `/dev/pts` (devpts) 175 * `/proc/sys/fs/binfmt_misc` (binfmt_misc) 176 177 These default mounts are usually good enough for anyone and are sane 178 defaults. However, if you want to change or add the mount points, you may 179 using the `chroot_mounts` configuration. Here is an example configuration: 180 181 ```javascript 182 { 183 "chroot_mounts": [ 184 ["proc", "proc", "/proc"], 185 ["bind", "/dev", "/dev"] 186 ] 187 } 188 ``` 189 190 `chroot_mounts` is a list of a 3-tuples of strings. The three components 191 of the 3-tuple, in order, are: 192 193 * The filesystem type. If this is "bind", then Packer will properly bind 194 the filesystem to another mount point. 195 196 * The source device. 197 198 * The mount directory. 199 200 ## Parallelism 201 202 A quick note on parallelism: it is perfectly safe to run multiple 203 _separate_ Packer processes with the `amazon-chroot` builder on the same 204 EC2 instance. In fact, this is recommended as a way to push the most performance 205 out of your AMI builds. 206 207 Packer properly obtains a process lock for the parallelism-sensitive parts 208 of its internals such as finding an available device. 209 210 ## Gotchas 211 212 One of the difficulties with using the chroot builder is that your provisioning 213 scripts must not leave any processes running or packer will be unable to unmount 214 the filesystem. 215 216 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 217 prevent packages installed by your provisioners from starting services: 218 219 ```javascript 220 { 221 "type": "shell", 222 "inline": [ 223 "echo '#!/bin/sh' > /usr/sbin/policy-rc.d", 224 "echo 'exit 101' >> /usr/sbin/policy-rc.d", 225 "chmod a+x /usr/sbin/policy-rc.d" 226 ] 227 }, 228 229 // ... 230 231 { 232 "type": "shell", 233 "inline": [ 234 "rm -f /usr/sbin/policy-rc.d" 235 ] 236 } 237 ``` 238 239 240 [1]: http://linuxcommand.org/man_pages/mount8.html