---
description: |
    The azure-chroot Packer builder is able to create Azure Managed Images leveraging
    a VM in Azure.
layout: docs
page_title: 'Azure chroot - Builders'
sidebar_current: 'docs-builders-azure-chroot'
---

# 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](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/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](/docs/builders/azure-arm.html),
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](https://en.wikipedia.org/wiki/Chroot) is set
up and made available to the [provisioners](/docs/provisioners/index.html).
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](/docs/builders/azure.html) for more
information.

<%= partial "partials/builder/azure/common/client/_Config-not-required.html" %>

### Azure chroot builder specific options

#### Required:
<%= partial "partials/builder/azure/chroot/_Config-required.html" %>

#### Optional:
<%= partial "partials/builder/azure/chroot/_Config-not-required.html" %>

## 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`:

```json
{
  "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:

```json
{
  "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.

```json
{
  "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"
  }]
}
```