github.com/StackPointCloud/packer@v0.10.2-0.20180716202532-b28098e0f79b/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"
   105      section below. 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  -   `device_path` (string) - The path to the device where the root volume of the
   125      source AMI will be attached. This defaults to "" (empty string), which
   126      forces Packer to find an open device automatically.
   127  
   128  -   `ena_support` (boolean) - Enable enhanced networking (ENA but not SriovNetSupport)
   129      on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy.
   130      Note: you must make sure enhanced networking is enabled on your instance. See [Amazon's
   131      documentation on enabling enhanced networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). Default `false`.
   132  
   133  -   `force_deregister` (boolean) - Force Packer to first deregister an existing
   134      AMI if one with the same name already exists. Default `false`.
   135  
   136  -   `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
   137      AMIs, which have been deregistered by `force_deregister`. Default `false`.
   138  
   139  -   `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the
   140      AMI with an encrypted boot volume (discarding the initial unencrypted AMI in the
   141      process). Packer will always run this operation, even if the base
   142      AMI has an encrypted boot volume to start with. Default `false`.
   143  
   144  -   `kms_key_id` (string) - The ID of the KMS key to use for boot volume encryption.
   145      This only applies to the main `region`, other regions where the AMI will be copied
   146      will be encrypted by the default EBS KMS key.
   147  
   148  -   `from_scratch` (boolean) - Build a new volume instead of starting from an
   149      existing AMI root volume snapshot. Default `false`. If true, `source_ami` is
   150      no longer used and the following options become required:
   151      `ami_virtualization_type`, `pre_mount_commands` and `root_volume_size`. The
   152      below options are also required in this mode only:
   153  
   154  -   `ami_block_device_mappings` (array of block device mappings) - Add one or
   155      more [block device mappings](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   156      to the AMI. These will be attached when booting a new instance from your
   157      AMI. Your options here may vary depending on the type of VM you use. The
   158      block device mappings allow for the following configuration:
   159  
   160      -   `delete_on_termination` (boolean) - Indicates whether the EBS volume is
   161          deleted on instance termination. Default `false`. **NOTE**: If this
   162          value is not explicitly set to `true` and volumes are not cleaned up by
   163          an alternative method, additional volumes will accumulate after
   164          every build.
   165  
   166      -   `device_name` (string) - The device name exposed to the instance (for
   167          example, `/dev/sdh` or `xvdh`). Required when specifying `volume_size`.
   168  
   169      -   `encrypted` (boolean) - Indicates whether to encrypt the volume or not
   170  
   171      -   `kms_key_id` (string) - The ARN for the KMS encryption key. When
   172          specifying `kms_key_id`, `encrypted` needs to be set to `true`.
   173  
   174      -   `iops` (number) - The number of I/O operations per second (IOPS) that the
   175          volume supports. See the documentation on
   176          [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
   177          for more information
   178  
   179      -   `no_device` (boolean) - Suppresses the specified device included in the
   180          block device mapping of the AMI
   181  
   182      -   `snapshot_id` (string) - The ID of the snapshot
   183  
   184      -   `virtual_name` (string) - The virtual device name. See the documentation on
   185          [Block Device
   186          Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html)
   187          for more information
   188  
   189      -   `volume_size` (number) - The size of the volume, in GiB. Required if not
   190          specifying a `snapshot_id`
   191  
   192      -   `volume_type` (string) - The volume type. gp2 for General Purpose (SSD)
   193          volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic
   194          volumes
   195  
   196  -   `region_kms_key_ids` (map of strings) - a map of regions to copy the ami to,
   197      along with the custom kms key id to use for encryption for that region.
   198      Keys must match the regions provided in `ami_regions`. If you just want to
   199      encrypt using a default ID, you can stick with `kms_key_id` and `ami_regions`.
   200      If you want a region to be encrypted with that region's default key ID, you can
   201      use an empty string `""` instead of a key id in this map. (e.g. `"us-east-1": ""`)
   202      However, you cannot use default key IDs if you are using this in conjunction with
   203      `snapshot_users` -- in that situation you must use custom keys.
   204  
   205  -   `root_device_name` (string) - The root device name. For example, `xvda`.
   206  
   207  -   `mfa_code` (string) - The MFA [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm)
   208      code. This should probably be a user variable since it changes all the time.
   209  
   210  -   `mount_path` (string) - The path where the volume will be mounted. This is
   211      where the chroot environment will be. This defaults to
   212      `/mnt/packer-amazon-chroot-volumes/{{.Device}}`. This is a configuration template
   213      where the `.Device` variable is replaced with the name of the device where
   214      the volume is attached.
   215  
   216  -   `mount_partition` (string) - The partition number containing the
   217      / partition. By default this is the first partition of the volume, (for
   218      example, `xvda1`) but you can designate the entire block device by setting
   219      `"mount_partition": "0"` in your config, which will mount `xvda` instead.
   220  
   221  -   `mount_options` (array of strings) - Options to supply the `mount` command
   222      when mounting devices. Each option will be prefixed with `-o` and supplied
   223      to the `mount` command ran by Packer. Because this command is ran in a
   224      shell, user discretion is advised. See [this manual page for the mount
   225      command](http://linuxcommand.org/man_pages/mount8.html) for valid file
   226      system specific options
   227  
   228  -   `nvme_device_path` (string) - When we call the mount command (by default
   229      `mount -o device dir`), the string provided in `nvme_mount_path` will
   230      replace `device` in that command. When this option is not set, `device` in
   231      that command will be something like `/dev/sdf1`, mirroring the attached
   232      device name. This assumption works for most instances but will fail with c5
   233      and m5 instances. In order to use the chroot builder with c5 and m5
   234      instances, you must manually set `nvme_device_path` and `device_path`.
   235  
   236  -   `pre_mount_commands` (array of strings) - A series of commands to execute
   237      after attaching the root volume and before mounting the chroot. This is not
   238      required unless using `from_scratch`. If so, this should include any
   239      partitioning and filesystem creation commands. The path to the device is
   240      provided by `{{.Device}}`.
   241  
   242  -   `profile` (string) - The profile to use in the shared credentials file for
   243      AWS. See Amazon's documentation on [specifying
   244      profiles](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-profiles)
   245      for more details.
   246  
   247  -   `post_mount_commands` (array of strings) - As `pre_mount_commands`, but the
   248      commands are executed after mounting the root device and before the extra
   249      mount and copy steps. The device and mount path are provided by
   250      `{{.Device}}` and `{{.MountPath}}`.
   251  
   252  -   `root_volume_size` (number) - The size of the root volume in GB for the
   253      chroot environment and the resulting AMI. Default size is the snapshot size
   254      of the `source_ami` unless `from_scratch` is `true`, in which case
   255      this field must be defined.
   256  
   257  -   `skip_region_validation` (boolean) - Set to true if you want to skip
   258      validation of the `ami_regions` configuration option. Default `false`.
   259  
   260  -   `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
   261      They will override AMI tags if already applied to snapshot. This is a
   262      [template engine](/docs/templates/engine.html),
   263      see [Build template data](#build-template-data) for more information.
   264  
   265  -   `snapshot_groups` (array of strings) - A list of groups that have access to
   266      create volumes from the snapshot(s). By default no groups have permission to create
   267      volumes from the snapshot(s). `all` will make the snapshot publicly accessible.
   268  
   269  -   `snapshot_users` (array of strings) - A list of account IDs that have access to
   270      create volumes from the snapshot(s). By default no additional users other than the
   271      user creating the AMI has permissions to create volumes from the backing snapshot(s).
   272  
   273  -   `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
   274      Example:
   275  
   276      ``` json
   277      "source_ami_filter": {
   278        "filters": {
   279          "virtualization-type": "hvm",
   280          "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*",
   281          "root-device-type": "ebs"
   282        },
   283        "owners": ["099720109477"],
   284        "most_recent": true
   285      }
   286      ```
   287  
   288      This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical.
   289      NOTE: This will fail unless *exactly* one AMI is returned. In the above
   290      example, `most_recent` will cause this to succeed by selecting the newest image.
   291  
   292      -   `filters` (map of strings) - filters used to select a `source_ami`.
   293          NOTE: This will fail unless *exactly* one AMI is returned.
   294          Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
   295          is valid.
   296  
   297      -   `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
   298          This is helpful to limit the AMIs to a trusted third party, or to your own account.
   299  
   300      -   `most_recent` (boolean) - Selects the newest created image when true.
   301          This is most useful for selecting a daily distro build.
   302  
   303      You may set this in place of `source_ami` or in conjunction with it. If you
   304      set this in conjunction with `source_ami`, the `source_ami` will be added to
   305      the filter. The provided `source_ami` must meet all of the filtering criteria
   306      provided in `source_ami_filter`; this pins the AMI returned by the filter,
   307      but will cause Packer to fail if the `source_ami` does not exist.
   308  
   309  -   `sriov_support` (boolean) - Enable enhanced networking (SriovNetSupport but not ENA)
   310      on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM
   311      policy. Note: you must make sure enhanced networking is enabled on your instance. See [Amazon's
   312      documentation on enabling enhanced networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking).
   313      Default `false`.
   314  
   315  -   `tags` (object of key/value strings) - Tags applied to the AMI. This is a
   316      [template engine](/docs/templates/engine.html),
   317      see [Build template data](#build-template-data) for more information.
   318  
   319  ## Basic Example
   320  
   321  Here is a basic example. It is completely valid except for the access keys:
   322  
   323  ``` json
   324  {
   325    "type": "amazon-chroot",
   326    "access_key": "YOUR KEY HERE",
   327    "secret_key": "YOUR SECRET KEY HERE",
   328    "source_ami": "ami-e81d5881",
   329    "ami_name": "packer-amazon-chroot {{timestamp}}"
   330  }
   331  ```
   332  
   333  ## Chroot Mounts
   334  
   335  The `chroot_mounts` configuration can be used to mount specific devices within
   336  the chroot. By default, the following additional mounts are added into the
   337  chroot by Packer:
   338  
   339  -   `/proc` (proc)
   340  -   `/sys` (sysfs)
   341  -   `/dev` (bind to real `/dev`)
   342  -   `/dev/pts` (devpts)
   343  -   `/proc/sys/fs/binfmt_misc` (binfmt\_misc)
   344  
   345  These default mounts are usually good enough for anyone and are sane defaults.
   346  However, if you want to change or add the mount points, you may using the
   347  `chroot_mounts` configuration. Here is an example configuration which only
   348  mounts `/proc` and `/dev`:
   349  
   350  ``` json
   351  {
   352    "chroot_mounts": [
   353      ["proc", "proc", "/proc"],
   354      ["bind", "/dev", "/dev"]
   355    ]
   356  }
   357  ```
   358  
   359  `chroot_mounts` is a list of a 3-tuples of strings. The three components of the
   360  3-tuple, in order, are:
   361  
   362  -   The filesystem type. If this is "bind", then Packer will properly bind the
   363      filesystem to another mount point.
   364  
   365  -   The source device.
   366  
   367  -   The mount directory.
   368  
   369  ## Parallelism
   370  
   371  A quick note on parallelism: it is perfectly safe to run multiple *separate*
   372  Packer processes with the `amazon-chroot` builder on the same EC2 instance. In
   373  fact, this is recommended as a way to push the most performance out of your AMI
   374  builds.
   375  
   376  Packer properly obtains a process lock for the parallelism-sensitive parts of
   377  its internals such as finding an available device.
   378  
   379  ## Gotchas
   380  
   381  ### Unmounting the Filesystem
   382  One of the difficulties with using the chroot builder is that your provisioning
   383  scripts must not leave any processes running or packer will be unable to unmount
   384  the filesystem.
   385  
   386  For debian based distributions you can setup a
   387  [policy-rc.d](http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt)
   388  file which will prevent packages installed by your provisioners from starting
   389  services:
   390  
   391  ``` json
   392  {
   393    "type": "shell",
   394    "inline": [
   395      "echo '#!/bin/sh' > /usr/sbin/policy-rc.d",
   396      "echo 'exit 101' >> /usr/sbin/policy-rc.d",
   397      "chmod a+x /usr/sbin/policy-rc.d"
   398    ]
   399  },
   400  
   401  // ...
   402  
   403  {
   404    "type": "shell",
   405    "inline": [
   406      "rm -f /usr/sbin/policy-rc.d"
   407    ]
   408  }
   409  ```
   410  
   411  ### Using Instances with NVMe block devices.
   412  In C5, C5d, M5, and i3.metal instances, EBS volumes are exposed as NVMe block
   413  devices [reference](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nvme-ebs-volumes.html).
   414  In order to correctly mount these devices, you have to do some extra legwork,
   415  involving the `nvme_device_path` option above. Read that for more information.
   416  
   417  A working example for mounting an NVMe device is below:
   418  
   419  ```
   420  {
   421    "variables": {
   422      "region" : "us-east-2"
   423    },
   424    "builders": [
   425      {
   426        "type": "amazon-chroot",
   427        "region": "{{user `region`}}",
   428        "source_ami_filter": {
   429          "filters": {
   430          "virtualization-type": "hvm",
   431          "name": "amzn-ami-hvm-*",
   432          "root-device-type": "ebs"
   433          },
   434          "owners": ["137112412989"],
   435          "most_recent": true
   436        },
   437        "ena_support": true,
   438        "ami_name": "amazon-chroot-test-{{timestamp}}",
   439        "nvme_device_path": "/dev/nvme1n1p",
   440        "device_path": "/dev/sdf"
   441      }
   442    ],
   443  
   444    "provisioners": [
   445      {
   446        "type": "shell",
   447        "inline": ["echo Test > /tmp/test.txt"]
   448      }
   449    ]
   450  }
   451  ```
   452  
   453  Note that in the `nvme_device_path` you must end with the `p`; if you try to
   454  define the partition in this path (e.g. "nvme_device_path": `/dev/nvme1n1p1`)
   455  and haven't also set the `"mount_partition": 0`, a `1` will be appended to the
   456  `nvme_device_path` and Packer will fail.
   457  
   458  ## Building From Scratch
   459  
   460  This example demonstrates the essentials of building an image from scratch. A
   461  15G gp2 (SSD) device is created (overriding the default of standard/magnetic).
   462  The device setup commands partition the device with one partition for use as an
   463  HVM image and format it ext4. This builder block should be followed by
   464  provisioning commands to install the os and bootloader.
   465  
   466  ``` json
   467  {
   468    "type": "amazon-chroot",
   469    "ami_name": "packer-from-scratch {{timestamp}}",
   470    "from_scratch": true,
   471    "ami_virtualization_type": "hvm",
   472    "pre_mount_commands": [
   473      "parted {{.Device}} mklabel msdos mkpart primary 1M 100% set 1 boot on print",
   474      "mkfs.ext4 {{.Device}}1"
   475    ],
   476    "root_volume_size": 15,
   477    "root_device_name": "xvda",
   478    "ami_block_device_mappings": [
   479      {
   480        "device_name": "xvda",
   481        "delete_on_termination": true,
   482        "volume_type": "gp2"
   483      }
   484    ]
   485  }
   486  ```
   487  
   488  ## Build template data
   489  
   490  The available variables are:
   491  
   492  - `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI.
   493  - `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI.
   494  - `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI.
   495  - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.