» Azure Builder (chroot)

Type: azure-chroot

The azure-chroot builder is able to build Azure managed disk (MD) images. For more information on managed disks, see Azure Managed Disks Overview.

The difference between this builder and the azure-arm builder is that this builder is able to build a managed disk image without launching a new Azure VM for every build, but instead use an already-running Azure VM. This can dramatically speed up image builds. It also allows for more deterministic image content and enables some capabilities that are not possible with the azure-arm builder.

This is an advanced builder If you're just getting started with Packer, it is recommend to start with the azure-arm builder, which is much easier to use.

» How Does it Work?

This builder works by creating a new MD from either an existing source or from scratch and attaching it to the (already existing) Azure VM where Packer is running. Once attached, a chroot is set up and made available to the provisioners. After provisioning, the MD is detached, snapshotted and a MD image is created.

Using this process, minutes can be shaved off the image creation process because Packer does not need to launch a VM instance.

There are some restrictions however: * The host system must be a similar system (generally the same OS version, kernel versions, etc.) as the image being built. * If the source is a managed disk, it must be made available in the same region as the host system. * The host system SKU has to allow for all of the specified disks to be attached.

» Configuration Reference

There are many configuration options available for the builder. We'll start with authentication parameters, then go over the Azure chroot builder specific options.

» Authentication options

None of the authentication options are required, but depending on which ones are specified a different authentication method may be used. See the shared Azure builders documentation for more information.

  • cloud_environment_name (string) - One of Public, China, Germany, or USGovernment. Defaults to Public. Long forms such as USGovernmentCloud and AzureUSGovernmentCloud are also supported.

  • client_id (string) - The application ID of the AAD Service Principal. Requires either client_secret, client_cert_path or client_jwt to be set as well.

  • client_secret (string) - A password/secret registered for the AAD SP.

  • client_cert_path (string) - The path to a certificate that will be used to authenticate as the specified AAD SP.

  • client_jwt (string) - A JWT bearer token for client auth (RFC 7523, Sec. 2.2) that will be used to authenticate the AAD SP. Provides more control over token the expiration when using certificate authentication than when using client_cert_path.

  • object_id (string) - The object ID for the AAD SP. Optional, will be derived from the oAuth token if left empty.

  • tenant_id (string) - The Active Directory tenant identifier with which your client_id and subscription_id are associated. If not specified, tenant_id will be looked up using subscription_id.

  • subscription_id (string) - The subscription to use.

» Azure chroot builder specific options

» Required:

  • source (string) - Either a managed disk resource ID or a publisher:offer:sku:version specifier for plaform image sources.

  • image_resource_id (string) - The image to create using this build.

» Optional:

  • from_scratch (bool) - When set to true, starts with an empty, unpartitioned disk. Defaults to false.

  • command_wrapper (string) - How to run shell commands. This may be useful to set environment variables or perhaps run a command 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}}.

  • pre_mount_commands ([]string) - 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}}.

  • mount_options ([]string) - 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 discretion is advised. See this manual page for the mount command for valid file system specific options.

  • mount_partition (string) - The partition number containing the / partition. By default this is the first partition of the volume.

  • 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 where the .Device variable is replaced with the name of the device where the volume is attached.

  • post_mount_commands ([]string) - 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}}.

  • chroot_mounts ([][]string) - This is a list of 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 ([]string) - Paths to files on the running Azure instance that will be copied into the chroot environment prior to provisioning. Defaults to /etc/resolv.conf so that DNS lookups work. Pass an empty list to skip copying /etc/resolv.conf. You may need to do this if you're building an image that uses systemd.

  • temporary_os_disk_name (string) - The name of the temporary disk that will be created in the resource group of the VM that Packer is running on. Will be generated if not set.

  • os_disk_size_gb (int32) - Try to resize the OS disk to this size on the first copy. Disks can only be englarged. If not specified, the disk will keep its original size. Required when using from_scratch

  • os_disk_storage_account_type (string) - The storage SKU to use for the OS Disk. Defaults to Standard_LRS.

  • os_disk_cache_type (string) - The cache type specified in the resulting image and for attaching it to the Packer VM. Defaults to ReadOnly

  • os_disk_skip_cleanup (bool) - If set to true, leaves the temporary disk behind in the Packer VM resource group. Defaults to false

  • image_hyperv_generation (string) - The Hyper-V generation type. Defaults to V1.

» Chroot Mounts

The chroot_mounts configuration can be used to mount specific 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 which only mounts /prod and /dev:

{
  "chroot_mounts": [
    ["proc", "proc", "/proc"],
    ["bind", "/dev", "/dev"]
  ]
}

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.

» Additional template function

Because this builder runs on an Azure VM, there is an additional template function available called vm, which returns the following VM metadata:

  • name
  • subscription_id
  • resource_group
  • location
  • resource_id

This function can be used in the configuration templates, for example, use "{{ vm `subscription_id` }}" to fill in the subscription ID of the VM in any of the configuration options.

» Examples

Here are some examples using this builder. This builder requires privileged actions, such as mounting disks, running chroot and other admin commands. Usually it needs to be run with root permissions, for example:

sudo -E packer build example.json

» Using a VM with a Managed Identity

On a VM with a system-assigned managed identity that has the contributor role on its own resource group, the following config can be used to create an updated Debian image:

{
  "builders": [{
    "type": "azure-chroot",

    "image_resource_id": "/subscriptions/{{vm `subscription_id`}}/resourceGroups/{{vm `resource_group`}}/providers/Microsoft.Compute/images/MyDebianOSImage-{{timestamp}}",
    "source": "credativ:Debian:9:latest"
  }],
  "provisioners": [{
    "inline": [
      "apt-get update",
      "apt-get upgrade -y"
    ],
    "inline_shebang": "/bin/sh -x",
    "type": "shell"
  }]
}

» Using a Service Principal

Here is an example that creates a Debian image with updated packages. Specify all environment variables (ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_SUBSCRIPTION_ID) to use a service principal. The identity you choose should have permission to create disks and images and also to update your VM. Set the ARM_IMAGE_RESOURCEGROUP_ID variable to an existing resource group in the subscription where the resulting image will be created.

{
  "variables": {
    "client_id": "{{env `ARM_CLIENT_ID`}}",
    "client_secret": "{{env `ARM_CLIENT_SECRET`}}",
    "subscription_id": "{{env `ARM_SUBSCRIPTION_ID`}}",
    "resource_group": "{{env `ARM_IMAGE_RESOURCEGROUP_ID`}}"
  },
  "builders": [{
    "type": "azure-chroot",

    "client_id": "{{user `client_id`}}",
    "client_secret": "{{user `client_secret`}}",
    "subscription_id": "{{user `subscription_id`}}",

    "image_resource_id": "/subscriptions/{{user `subscription_id`}}/resourceGroups/{{user `resource_group`}}/providers/Microsoft.Compute/images/MyDebianOSImage-{{timestamp}}",

    "source": "credativ:Debian:9:latest"
  }],
  "provisioners": [{
    "inline": [
      "apt-get update",
      "apt-get upgrade -y"
    ],
    "inline_shebang": "/bin/sh -x",
    "type": "shell"
  }]
}