About images

MAAS can deploy standard (Ubuntu) or custom images.

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

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.

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.

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

MAAS allows you to upload and deploy custom images beyond the MAAS image repository. 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

You can create MAAS-compatible images in two ways:

  1. Hand-build images (requires deep understanding of curtin/cloud-init).
  2. Use Packer to automate the process.

The former is the recommenced way of building images. For selected operating systems, Canonical provides Packer templates 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

  • 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

  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

  • 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

The MAAS dashboard tracks the number of deployed static images.

Packer

Packer 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

  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

  • 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

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

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

Packer templates

A Packer template (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

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

Last updated 23 days ago.

Help improve this document in the forum.