github.com/aclaygray/packer@v1.3.2/website/source/docs/builders/amazon-chroot.html.md (about) 1 --- 2 description: | 3 The amazon-chroot Packer builder is able to create Amazon AMIs backed by an 4 EBS volume as the root device. For more information on the difference between 5 instance storage and EBS-backed instances, storage for the root device section 6 in the EC2 documentation. 7 layout: docs 8 page_title: 'Amazon chroot - Builders' 9 sidebar_current: 'docs-builders-amazon-chroot' 10 --- 11 12 # AMI Builder (chroot) 13 14 Type: `amazon-chroot` 15 16 The `amazon-chroot` Packer builder is able to create Amazon AMIs backed by an 17 EBS volume as the root device. For more information on the difference between 18 instance storage and EBS-backed instances, see the ["storage for the root 19 device" section in the EC2 20 documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). 21 22 The difference between this builder and the `amazon-ebs` builder is that this 23 builder is able to build an EBS-backed AMI without launching a new EC2 instance. 24 This can dramatically speed up AMI builds for organizations who need the extra 25 fast build. 26 27 ~> **This is an advanced builder** If you're just getting started with 28 Packer, we recommend starting with the [amazon-ebs 29 builder](/docs/builders/amazon-ebs.html), which is much easier to use. 30 31 The builder does *not* manage AMIs. Once it creates an AMI and stores it in your 32 account, it is up to you to use, delete, etc., the AMI. 33 34 ## How Does it Work? 35 36 This builder works by creating a new EBS volume from an existing source AMI and 37 attaching it into an already-running EC2 instance. Once attached, a 38 [chroot](https://en.wikipedia.org/wiki/Chroot) is used to provision the system 39 within that volume. After provisioning, the volume is detached, snapshotted, and 40 an AMI is made. 41 42 Using this process, minutes can be shaved off the AMI creation process because a 43 new EC2 instance doesn't need to be launched. 44 45 There are some restrictions, however. The host EC2 instance where the volume is 46 attached to must be a similar system (generally the same OS version, kernel 47 versions, etc.) as the AMI being built. Additionally, this process is much more 48 expensive because the EC2 instance must be kept running persistently in order to 49 build AMIs, whereas the other AMI builders start instances on-demand to build 50 AMIs as needed. 51 52 ## Configuration Reference 53 54 There are many configuration options available for the builder. They are 55 segmented below into two categories: required and optional parameters. Within 56 each category, the available configuration keys are alphabetized. 57 58 ### Required: 59 60 - `access_key` (string) - The access key used to communicate with AWS. [Learn 61 how to set this](/docs/builders/amazon.html#specifying-amazon-credentials) 62 63 - `ami_name` (string) - The name of the resulting AMI that will appear when 64 managing AMIs in the AWS console or via APIs. This must be unique. To help 65 make this unique, use a function like `timestamp` (see [template 66 engine](/docs/templates/engine.html) for more info). 67 68 - `secret_key` (string) - The secret key used to communicate with AWS. [Learn 69 how to set this](/docs/builders/amazon.html#specifying-amazon-credentials) 70 71 - `source_ami` (string) - The source AMI whose root volume will be copied and 72 provisioned on the currently running instance. This must be an EBS-backed AMI 73 with a root volume snapshot that you have access to. Note: this is not used 74 when `from_scratch` is set to `true`. 75 76 ### Optional: 77 78 - `ami_description` (string) - The description to set for the 79 resulting AMI(s). By default this description is empty. This is a 80 [template engine](/docs/templates/engine.html), 81 see [Build template data](#build-template-data) for more information. 82 83 - `ami_groups` (array of strings) - A list of groups that have access to 84 launch the resulting AMI(s). By default no groups have permission to launch 85 the AMI. `all` will make the AMI publicly accessible. 86 87 - `ami_product_codes` (array of strings) - A list of product codes to 88 associate with the AMI. By default no product codes are associated with 89 the AMI. 90 91 - `ami_regions` (array of strings) - A list of regions to copy the AMI to. 92 Tags and attributes are copied along with the AMI. AMI copying takes time 93 depending on the size of the AMI, but will generally take many minutes. 94 95 - `ami_users` (array of strings) - A list of account IDs that have access to 96 launch the resulting AMI(s). By default no additional users other than the user creating the AMI has permissions to launch it. 97 98 - `ami_virtualization_type` (string) - The type of virtualization for the AMI 99 you are building. This option is required to register HVM images. Can be 100 `paravirtual` (default) or `hvm`. 101 102 - `chroot_mounts` (array of array of strings) - This is a list of devices 103 to mount into the chroot environment. This configuration parameter 104 requires some additional documentation which is in the [Chroot Mounts](#Chroot Mounts) 105 section. Please read that section for more information on how to 106 use this. 107 108 - `command_wrapper` (string) - How to run shell commands. This defaults to 109 `{{.Command}}`. This may be useful to set if you want to set environmental 110 variables or perhaps run it with `sudo` or so on. This is a configuration 111 template where the `.Command` variable is replaced with the command to 112 be run. Defaults to `{{.Command}}`. 113 114 - `copy_files` (array of strings) - Paths to files on the running EC2 instance 115 that will be copied into the chroot environment prior to provisioning. Defaults 116 to `/etc/resolv.conf` so that DNS lookups work. Pass an empty list to skip 117 copying `/etc/resolv.conf`. You may need to do this if you're building 118 an image that uses systemd. 119 120 - `custom_endpoint_ec2` (string) - This option is useful if you use a cloud 121 provider whose API is compatible with aws EC2. Specify another endpoint 122 like this `https://ec2.custom.endpoint.com`. 123 124 - `decode_authorization_messages` (boolean) - Enable automatic decoding of any 125 encoded authorization (error) messages using the `sts:DecodeAuthorizationMessage` API. 126 Note: requires that the effective user/role have permissions to `sts:DecodeAuthorizationMessage` 127 on resource `*`. Default `false`. 128 129 - `device_path` (string) - The path to the device where the root volume of the 130 source AMI will be attached. This defaults to "" (empty string), which 131 forces Packer to find an open device automatically. 132 133 - `ena_support` (boolean) - Enable enhanced networking (ENA but not SriovNetSupport) 134 on HVM-compatible AMIs. If set, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. 135 If false, this will disable enhanced networking in the final AMI as opposed to passing 136 the setting through unchanged from the source. Note: you must make sure enhanced 137 networking is enabled on your instance. See [Amazon's documentation on enabling enhanced 138 networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). 139 140 - `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the 141 AMI with an encrypted boot volume (discarding the initial unencrypted AMI in the 142 process). Packer will always run this operation, even if the base 143 AMI has an encrypted boot volume to start with. Default `false`. 144 145 - `force_deregister` (boolean) - Force Packer to first deregister an existing 146 AMI if one with the same name already exists. Default `false`. 147 148 - `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with 149 AMIs, which have been deregistered by `force_deregister`. Default `false`. 150 151 152 - `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption. 153 This only applies to the main `region`, other regions where the AMI will be copied 154 will be encrypted by the default EBS KMS key. For valid formats see _KmsKeyId_ in the 155 [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). 156 157 - `from_scratch` (boolean) - Build a new volume instead of starting from an 158 existing AMI root volume snapshot. Default `false`. If `true`, `source_ami` is 159 no longer used and the following options become required: 160 `ami_virtualization_type`, `pre_mount_commands` and `root_volume_size`. The 161 below options are also required in this mode only: 162 163 - `ami_block_device_mappings` (array of block device mappings) - Add one or 164 more [block device mappings](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html) 165 to the AMI. These will be attached when booting a new instance from your 166 AMI. Your options here may vary depending on the type of VM you use. The 167 block device mappings allow for the following configuration: 168 169 - `delete_on_termination` (boolean) - Indicates whether the EBS volume is 170 deleted on instance termination. Default `false`. **NOTE**: If this 171 value is not explicitly set to `true` and volumes are not cleaned up by 172 an alternative method, additional volumes will accumulate after 173 every build. 174 175 - `device_name` (string) - The device name exposed to the instance (for 176 example, `/dev/sdh` or `xvdh`). Required for every device in the 177 block device mapping. 178 179 - `encrypted` (boolean) - Indicates whether or not to encrypt the volume. 180 181 - `kms_key_id` (string) - The ARN for the KMS encryption key. When 182 specifying `kms_key_id`, `encrypted` needs to be set to `true`. 183 For valid formats see _KmsKeyId_ in the 184 [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). 185 186 - `iops` (number) - The number of I/O operations per second (IOPS) that the 187 volume supports. See the documentation on 188 [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) 189 for more information. 190 191 - `no_device` (boolean) - Suppresses the specified device included in the 192 block device mapping of the AMI. 193 194 - `snapshot_id` (string) - The ID of the snapshot. 195 196 - `virtual_name` (string) - The virtual device name. See the documentation on 197 [Block Device 198 Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) 199 for more information. 200 201 - `volume_size` (number) - The size of the volume, in GiB. Required if not 202 specifying a `snapshot_id`. 203 204 - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD) 205 volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic 206 volumes 207 208 - `region_kms_key_ids` (map of strings) - a map of regions to copy the ami to, 209 along with the custom kms key id (alias or arn) to use for encryption for that region. 210 Keys must match the regions provided in `ami_regions`. If you just want to 211 encrypt using a default ID, you can stick with `kms_key_id` and `ami_regions`. 212 If you want a region to be encrypted with that region's default key ID, you can 213 use an empty string `""` instead of a key id in this map. (e.g. `"us-east-1": ""`) 214 However, you cannot use default key IDs if you are using this in conjunction with 215 `snapshot_users` -- in that situation you must use custom keys. For valid formats 216 see _KmsKeyId_ in the 217 [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). 218 219 220 - `root_device_name` (string) - The root device name. For example, `xvda`. 221 222 - `mfa_code` (string) - The MFA [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) 223 code. This should probably be a user variable since it changes all the time. 224 225 - `mount_path` (string) - The path where the volume will be mounted. This is 226 where the chroot environment will be. This defaults to 227 `/mnt/packer-amazon-chroot-volumes/{{.Device}}`. This is a configuration template 228 where the `.Device` variable is replaced with the name of the device where 229 the volume is attached. 230 231 - `mount_partition` (string) - The partition number containing the 232 / partition. By default this is the first partition of the volume, (for 233 example, `xvda1`) but you can designate the entire block device by setting 234 `"mount_partition": "0"` in your config, which will mount `xvda` instead. 235 236 - `mount_options` (array of strings) - Options to supply the `mount` command 237 when mounting devices. Each option will be prefixed with `-o` and supplied 238 to the `mount` command ran by Packer. Because this command is ran in a 239 shell, user discretion is advised. See [this manual page for the mount 240 command](http://linuxcommand.org/man_pages/mount8.html) for valid file 241 system specific options. 242 243 - `nvme_device_path` (string) - When we call the mount command (by default 244 `mount -o device dir`), the string provided in `nvme_mount_path` will 245 replace `device` in that command. When this option is not set, `device` in 246 that command will be something like `/dev/sdf1`, mirroring the attached 247 device name. This assumption works for most instances but will fail with c5 248 and m5 instances. In order to use the chroot builder with c5 and m5 249 instances, you must manually set `nvme_device_path` and `device_path`. 250 251 - `pre_mount_commands` (array of strings) - A series of commands to execute 252 after attaching the root volume and before mounting the chroot. This is not 253 required unless using `from_scratch`. If so, this should include any 254 partitioning and filesystem creation commands. The path to the device is 255 provided by `{{.Device}}`. 256 257 - `profile` (string) - The profile to use in the shared credentials file for 258 AWS. See Amazon's documentation on [specifying 259 profiles](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-profiles) 260 for more details. 261 262 - `post_mount_commands` (array of strings) - As `pre_mount_commands`, but the 263 commands are executed after mounting the root device and before the extra 264 mount and copy steps. The device and mount path are provided by 265 `{{.Device}}` and `{{.MountPath}}`. 266 267 - `root_volume_size` (number) - The size of the root volume in GB for the 268 chroot environment and the resulting AMI. Default size is the snapshot size 269 of the `source_ami` unless `from_scratch` is `true`, in which case 270 this field must be defined. 271 272 - `root_volume_type` (string) - The type of EBS volume for the chroot environment 273 and resulting AMI. The default value is the type of the `source_ami`, unless 274 `from_scratch` is `true`, in which case the default value is `gp2`. You can only 275 specify `io1` if building based on top of a `source_ami` which is also `io1`. 276 277 - `root_volume_tags` (object of key/value strings) - Tags to apply to the volumes 278 that are *launched*. This is a 279 [template engine](/docs/templates/engine.html), 280 see [Build template data](#build-template-data) for more information. 281 282 - `skip_region_validation` (boolean) - Set to `true` if you want to skip 283 validation of the `ami_regions` configuration option. Default `false`. 284 285 - `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot. 286 They will override AMI tags if already applied to snapshot. This is a 287 [template engine](/docs/templates/engine.html), 288 see [Build template data](#build-template-data) for more information. 289 290 - `snapshot_groups` (array of strings) - A list of groups that have access to 291 create volumes from the snapshot(s). By default no groups have permission to create 292 volumes from the snapshot(s). `all` will make the snapshot publicly accessible. 293 294 - `snapshot_users` (array of strings) - A list of account IDs that have access to 295 create volumes from the snapshot(s). By default no additional users other than the 296 user creating the AMI has permissions to create volumes from the backing snapshot(s). 297 298 - `source_ami_filter` (object) - Filters used to populate the `source_ami` field. 299 Example: 300 301 ``` json 302 "source_ami_filter": { 303 "filters": { 304 "virtualization-type": "hvm", 305 "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*", 306 "root-device-type": "ebs" 307 }, 308 "owners": ["099720109477"], 309 "most_recent": true 310 } 311 ``` 312 313 This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical. 314 NOTE: This will fail unless *exactly* one AMI is returned. In the above 315 example, `most_recent` will cause this to succeed by selecting the newest image. 316 317 - `filters` (map of strings) - filters used to select a `source_ami`. 318 NOTE: This will fail unless *exactly* one AMI is returned. 319 Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html) 320 is valid. 321 322 - `owners` (array of strings) - Filters the images by their owner. You may 323 specify one or more AWS account IDs, "self" (which will use the account 324 whose credentials you are using to run Packer), or an AWS owner alias: 325 for example, "amazon", "aws-marketplace", or "microsoft". 326 This option is required for security reasons. 327 328 - `most_recent` (boolean) - Selects the newest created image when `true`. 329 This is most useful for selecting a daily distro build. 330 331 You may set this in place of `source_ami` or in conjunction with it. If you 332 set this in conjunction with `source_ami`, the `source_ami` will be added to 333 the filter. The provided `source_ami` must meet all of the filtering criteria 334 provided in `source_ami_filter`; this pins the AMI returned by the filter, 335 but will cause Packer to fail if the `source_ami` does not exist. 336 337 - `sriov_support` (boolean) - Enable enhanced networking (SriovNetSupport but not ENA) 338 on HVM-compatible AMIs. If `true`, add `ec2:ModifyInstanceAttribute` to your AWS IAM 339 policy. Note: you must make sure enhanced networking is enabled on your instance. See [Amazon's 340 documentation on enabling enhanced networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). 341 Default `false`. 342 343 - `tags` (object of key/value strings) - Tags applied to the AMI. This is a 344 [template engine](/docs/templates/engine.html), 345 see [Build template data](#build-template-data) for more information. 346 347 ## Basic Example 348 349 Here is a basic example. It is completely valid except for the access keys: 350 351 ``` json 352 { 353 "type": "amazon-chroot", 354 "access_key": "YOUR KEY HERE", 355 "secret_key": "YOUR SECRET KEY HERE", 356 "source_ami": "ami-e81d5881", 357 "ami_name": "packer-amazon-chroot {{timestamp}}" 358 } 359 ``` 360 361 ## Chroot Mounts 362 363 The `chroot_mounts` configuration can be used to mount specific devices within 364 the chroot. By default, the following additional mounts are added into the 365 chroot by Packer: 366 367 - `/proc` (proc) 368 - `/sys` (sysfs) 369 - `/dev` (bind to real `/dev`) 370 - `/dev/pts` (devpts) 371 - `/proc/sys/fs/binfmt_misc` (binfmt\_misc) 372 373 These default mounts are usually good enough for anyone and are sane defaults. 374 However, if you want to change or add the mount points, you may using the 375 `chroot_mounts` configuration. Here is an example configuration which only 376 mounts `/proc` and `/dev`: 377 378 ``` json 379 { 380 "chroot_mounts": [ 381 ["proc", "proc", "/proc"], 382 ["bind", "/dev", "/dev"] 383 ] 384 } 385 ``` 386 387 `chroot_mounts` is a list of a 3-tuples of strings. The three components of the 388 3-tuple, in order, are: 389 390 - The filesystem type. If this is "bind", then Packer will properly bind the 391 filesystem to another mount point. 392 393 - The source device. 394 395 - The mount directory. 396 397 ## Parallelism 398 399 A quick note on parallelism: it is perfectly safe to run multiple *separate* 400 Packer processes with the `amazon-chroot` builder on the same EC2 instance. In 401 fact, this is recommended as a way to push the most performance out of your AMI 402 builds. 403 404 Packer properly obtains a process lock for the parallelism-sensitive parts of 405 its internals such as finding an available device. 406 407 ## Gotchas 408 409 ### Unmounting the Filesystem 410 One of the difficulties with using the chroot builder is that your provisioning 411 scripts must not leave any processes running or packer will be unable to unmount 412 the filesystem. 413 414 For debian based distributions you can setup a 415 [policy-rc.d](http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt) 416 file which will prevent packages installed by your provisioners from starting 417 services: 418 419 ``` json 420 { 421 "type": "shell", 422 "inline": [ 423 "echo '#!/bin/sh' > /usr/sbin/policy-rc.d", 424 "echo 'exit 101' >> /usr/sbin/policy-rc.d", 425 "chmod a+x /usr/sbin/policy-rc.d" 426 ] 427 }, 428 429 // ... 430 431 { 432 "type": "shell", 433 "inline": [ 434 "rm -f /usr/sbin/policy-rc.d" 435 ] 436 } 437 ``` 438 439 ### Using Instances with NVMe block devices. 440 In C5, C5d, M5, and i3.metal instances, EBS volumes are exposed as NVMe block 441 devices [reference](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nvme-ebs-volumes.html). 442 In order to correctly mount these devices, you have to do some extra legwork, 443 involving the `nvme_device_path` option above. Read that for more information. 444 445 A working example for mounting an NVMe device is below: 446 447 ``` 448 { 449 "variables": { 450 "region" : "us-east-2" 451 }, 452 "builders": [ 453 { 454 "type": "amazon-chroot", 455 "region": "{{user `region`}}", 456 "source_ami_filter": { 457 "filters": { 458 "virtualization-type": "hvm", 459 "name": "amzn-ami-hvm-*", 460 "root-device-type": "ebs" 461 }, 462 "owners": ["137112412989"], 463 "most_recent": true 464 }, 465 "ena_support": true, 466 "ami_name": "amazon-chroot-test-{{timestamp}}", 467 "nvme_device_path": "/dev/nvme1n1p", 468 "device_path": "/dev/sdf" 469 } 470 ], 471 472 "provisioners": [ 473 { 474 "type": "shell", 475 "inline": ["echo Test > /tmp/test.txt"] 476 } 477 ] 478 } 479 ``` 480 481 Note that in the `nvme_device_path` you must end with the `p`; if you try to 482 define the partition in this path (e.g. `nvme_device_path`: `/dev/nvme1n1p1`) 483 and haven't also set the `"mount_partition": 0`, a `1` will be appended to the 484 `nvme_device_path` and Packer will fail. 485 486 ## Building From Scratch 487 488 This example demonstrates the essentials of building an image from scratch. A 489 15G gp2 (SSD) device is created (overriding the default of standard/magnetic). 490 The device setup commands partition the device with one partition for use as an 491 HVM image and format it ext4. This builder block should be followed by 492 provisioning commands to install the os and bootloader. 493 494 ``` json 495 { 496 "type": "amazon-chroot", 497 "ami_name": "packer-from-scratch {{timestamp}}", 498 "from_scratch": true, 499 "ami_virtualization_type": "hvm", 500 "pre_mount_commands": [ 501 "parted {{.Device}} mklabel msdos mkpart primary 1M 100% set 1 boot on print", 502 "mkfs.ext4 {{.Device}}1" 503 ], 504 "root_volume_size": 15, 505 "root_device_name": "xvda", 506 "ami_block_device_mappings": [ 507 { 508 "device_name": "xvda", 509 "delete_on_termination": true, 510 "volume_type": "gp2" 511 } 512 ] 513 } 514 ``` 515 516 ## Build template data 517 518 In configuration directives marked as a template engine above, the 519 following variables are available: 520 521 - `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. 522 - `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. 523 - `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. 524 - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.