---
title: About images
description: Canonical makes open source secure, reliable and easy to use, providing
  support for Ubuntu and a portfolio of enterprise-grade technologies. Founded in
  2004, Canonical operates globally with team members in over 80 countries.
url: https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md
---

*Submit*

# About images

MAAS can deploy standard (Ubuntu) or custom images.

## [Standard images](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-standard-images)

MAAS standard images come from a SimpleStreams source. Canonical provides two SimpleStreams for MAAS images: candidate and stable. Both streams contain Ubuntu images, CentOS images, bootloaders extracted from the Ubuntu archive, and release notifications. Either stream can be used in any version of MAAS greater than 2.1 – but not all images are supported in older versions.

### [The stable stream](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-the-stable-stream)

The stable stream contains images and bootloaders which have been tested with the latest version of MAAS. This is the default stream which should be used in production environments.

This stream is available [here](http://images.maas.io/ephemeral-v3/stable).

### [The candidate stream](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-the-candidate-stream)

The candidate stream contains images and bootloaders which have not been explicitly tested with MAAS. Canonical’s automated build process publishes all these files here before they are tested with MAAS. This stream is useful when testing a bug fix before an image or bootloader has been promoted to stable. Think of the candidate stream as a preview: it should never be used in a production environment; and users are encouraged to provide feedback on any issues they find with this stream.

This stream is available [here](http://images.maas.io/ephemeral-v3/candidate).

### [The retired daily stream](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-the-retired-daily-stream)

Previously there was only one MAAS stream available, daily. This stream has been replaced by the stable stream. Any client using this stream will be automatically redirected to the stable stream.

## [Custom images](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-custom-images)

MAAS allows you to upload and deploy custom images beyond the [MAAS image repository](http://images.maas.io). However, generic ISO images require modifications before they can be used. A valid MAAS image must include:

* A **curtin hook script** to write and boot the image.
* **Cloud-init** (or equivalent) for provisioning network, storage, users, and software.

### [Preparing custom images](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-preparing-custom-images)

You can create MAAS-compatible images in two ways:

1. **Hand-build images** (requires deep understanding of curtin/cloud-init).
2. **Use [Packer](https://www.packer.io)** to automate the process.

The former is the recommenced way of building images. For selected operating systems, Canonical provides [Packer templates](https://github.com/canonical/packer-maas) to easy the process.

Custom images cannot be distributed by Canonical due to licensing. The users must build these and upload them to MAAS themselves. These templates are available in a *as-is* basis.

### [How MAAS handles custom images](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-how-maas-handles-custom-images)

* MAAS stores uploaded images in the Region controllers, preserving the original format.
* It distinguishes between Ubuntu and non-Ubuntu images, applying the correct pre-seed configs.
* **Custom images always boot with an ephemeral Ubuntu OS before deployment.**
* The `base_image` field ensures compatibility between the ephemeral OS and the custom image.

### [Deployment & boot process](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-deployment-boot-process)

1. **An ephemeral OS (matching the custom image version) boots first.**
2. **MAAS loads the image’s kernel, bootloader, and root filesystem.**
3. **Curtin writes the full custom image to disk.**
4. **After writing, MAAS executes any curtin hook present in the image**

For non-Ubuntu images, an Ubuntu ephemeral OS still boots first before switching to the custom OS.

### [Network & storage configuration](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-network-storage-configuration)

* **Networking:** MAAS-configured network settings apply automatically if supported by cloud-init.
* **Storage:** Root partitions can be resized, and additional block devices can be attached/formatted.
* **Verification:** MAAS aborts installation if `cloud-init` or `netplan` is missing.

### [Static image metrics](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-static-image-metrics)

The MAAS dashboard tracks the number of deployed static images.

## [Packer](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-packer)

[Packer](https://www.packer.io/docs) automates OS image creation for MAAS deployment. It uses **HCL2 templates** to define build, provisioning, and post-processing steps.

> *Note: Packer is the recommended approach to build custom images. Use `cloud-init` or `curtin` instead of custom images for minimal customizations.*

### [Packer workflow](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-packer-workflow)

1. **Define a template** (HCL2 format).
2. **Select a builder** (e.g., QEMU, Anaconda).
3. **Run provisioners** (install software, configure settings).
4. **Apply post-processors** (e.g., compressing into `.tar.gz`).

Packer outputs **artifacts** (loadable images). In MAAS, these are simply called **images**.

### [Packer image creation process](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-packer-image-creation-process)

* **Builders** create base OS images.
* **Provisioners** customize images (`curtin` hooks, `cloud-init`, packages).
* **Post-processors** finalize the image for deployment (e.g., compression).

### [Dependencies for Ubuntu images](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-dependencies-for-ubuntu-images)

To build an Ubuntu image with `packer-maas`, install:

```
sudo apt install qemu-utils qemu-system ovmf cloud-image-utils
```

### [Packer templates](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-packer-templates)

A [Packer template](https://github.com/canonical/packer-maas) (written in HCL2) defines the entire image-building process. It includes:

* **Variables** (image type, architecture, file paths).
* **Source declaration** (how the image is built).
* **Provisioners** (installation/configuration scripts).
* **Post-processors** (final adjustments before deployment).

Most templates supplied by Canonical also include a `Makefile` file. It’s strongly advised to use these files to to build the image.

#### Example: Ubuntu packer template

```
packer {
  required_version = ">= 1.7.0"
  required_plugins {
    qemu = {
      version = "~> 1.0"
      source  = "github.com/hashicorp/qemu"
    }
  }
}

variable "ubuntu_series" {
  type        = string
  default     = "focal"
  description = "Ubuntu version to build."
}

source "qemu" "cloudimg" {
  iso_url        = "https://cloud-images.ubuntu.com/${var.ubuntu_series}/current/${var.ubuntu_series}-server-cloudimg-amd64.img"
  disk_size      = "4G"
  memory         = 2048
  cpus           = 2
  headless       = true
}

build {
  sources = ["source.qemu.cloudimg"]

  provisioner "shell" {
    scripts = ["./scripts/setup.sh"]
  }

  post-processor "shell-local" {
    inline = [
      "tar -czf ubuntu-custom.tar.gz /path/to/image"
    ]
  }
}
```

### [Uploading packer images to MAAS](https://canonical-com-2934.demos.haus/maas/docs/about-images?format=md#p-17467-uploading-packer-images-to-maas)

Once built, upload a Packer-generated image via:

```
maas $ADMIN boot-resources create \
    name='custom/ubuntu-packer' \
    title='Ubuntu Packer' \
    architecture='amd64/generic' \
    filetype='tgz' \
    content@=ubuntu-custom.tar.gz
```

---

[Previous

Controllers](https://canonical-com-2934.demos.haus/maas/docs/about-controllers)
[Next

Performance](https://canonical-com-2934.demos.haus/maas/docs/about-maas-performance)

Last updated 1 year, 3 months ago. [Help improve this document in the forum](https://discourse.maas.io/t/about-images/7904).