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:
- Hand-build images (requires deep understanding of curtin/cloud-init).
- 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
- An ephemeral OS (matching the custom image version) boots first.
- MAAS loads the image’s kernel, bootloader, and root filesystem.
- Curtin writes the full custom image to disk.
- 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
ornetplan
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
orcurtin
instead of custom images for minimal customizations.
Packer workflow
- Define a template (HCL2 format).
- Select a builder (e.g., QEMU, Anaconda).
- Run provisioners (install software, configure settings).
- 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 2 days ago.