MAAS is only useful once it has images available to provision its nodes. Therefore, one key post-install task is to select and import images from the boot source. Once MAAS imports images, it will update them on an hourly basis, via a default sync mechanism. This page explains how to select and import the images that MAAS requires to provision its nodes.
This article will help you learn:
- How to use image streams
- How to import standard images from maas.io
- How to use other image mirrors to download images
- How to import and provision non-Ubuntu images
You can also mirror images locally, build your own custom images, or even work with VMWare images. And there’s some background info on images available if you need it.
How to use MAAS image streams
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.
How to change the stream with the UI
To switch to the candidate stream:
-
Select Images.
-
Select Change source.
-
Select Custom.
-
Set the URL to
http://images.maas.io/ephemeral-v3/candidate. -
Select Connect.
MAAS uses the stable stream by default. To switch back to it, simply repeat the above procedure, but set the URL to maas.io.
How to change the stream with the CLI
To switch to a stream with the CLI, enter the following commands:
BOOT_SOURCE_ID=$(maas $PROFILE boot-sources read | jq '.[] | select(.url | contains("images.maas.io/ephemeral-v3")) | .id')
maas $PROFILE boot-source update $BOOT_SOURCE_ID url=$STREAM_URL
How to import standard images from maas.io
The Images page shows what images and architectures have been selected and downloaded. By default, MAAS will automatically grab the most recent Ubuntu LTS releases (and amd64 architecture).
You can tell MAAS to sync images hourly, at the region level, using a toggle switch in the top-right corner of the screen. See Boot image sources) for more details. We highly recommended syncing images hourly. Syncing at the rack controller level (from regiond) occurs every 5 min and cannot be disabled.
To remove an image, simply un-select it and click Save selection.
How to use other image mirrors to download images
You can also host Ubuntu images on a mirror. To use these mirrors:
-
Select Images.
-
Select Change source.
-
Select Custom.
-
Enter the mirror URL.
-
Select Connect to bring the mirror online.
Advanced options, such as using a GPG key or keyring to validate the mirror path (snap installation location: /snap/maas/current/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg), are revealed by Selecting Show advanced options.
Optionally, a local mirror can be set up as the boot source. MAAS will then use it instead of the standard internet-based server. Local mirroring significantly reduces the time required import images. See Local image mirror for instructions.
How to import and provision non-Ubuntu images
It is also possible to import and provision images other than Ubuntu. Images supported and provided by MAAS will appear in Images >> Other Images. These images can be imported and used just like the Ubuntu images above.
You can tell MAAS to sync images hourly, at the region level. See Boot image sources) for more details. We highly recommended syncing images hourly. Syncing at the rack controller level (from regiond) occurs every 5 min and cannot be disabled.
This article will help you learn:
- How to get started with the MAAS CLI
- How to list boot sources
- How to select images
- How to list image selections
- How to import newly-selected images
- How to list currently available images
- How to delete a boot source
- How to edit a boot source
You can also mirror images locally, build your own custom images, or even work with VMWare images. And there’s some background info on images available if you need it.
How to list boot sources
If you want to download boot sources, i.e., the locations from which you may download images, try the following:
maas $PROFILE boot-sources read
Although multiple boot sources may be listed, MAAS can only practically work with a single boot source.
How to select images
Use the boot-source-selections command to select images from a boot source. After selecting new images, you will need to import them.
maas $PROFILE boot-source-selections create $SOURCE_ID \
os="ubuntu" release="$SERIES" arches="$ARCH" \
subarches="$KERNEL" labels="*"
For example, to select all kernels for 64-bit Trusty from a boot source with an id of ‘1’:
maas $PROFILE boot-source-selections create 1 \
os="ubuntu" release="trusty" arches="amd64" \
subarches="*" labels="*"
Hardware enablement (HWE)
For example, to get just the latest amd64 HWE kernel available for Trusty, which, at time of writing, is from Xenial:
maas $PROFILE boot-source-selections create 1 \
os="ubuntu" release="trusty" arches="amd64" \
subarches="hwe-x" labels="*"
For Xenial kernels (and starting with MAAS 2.1), notation has changed. To select the latest amd64 HWE kernel available for Xenial:
maas $PROFILE boot-source-selections create 1 \
os="ubuntu" release="xenial" arches="amd64" \
subarches="hwe-16.04" labels="*"
How to list image selections
To list image selections for a boot source:
maas $PROFILE boot-source-selections read $SOURCE_ID
How to import newly-selected images
To import newly-selected images (boot resources):
maas $PROFILE boot-resources import
Once newly-selected images are imported, a sync mechanism is enabled (by default) to keep them up to date. The refresh time interval is 60 minutes.
Available images resulting from this action are reflected in the web UI.
How to list currently available images
To list currently available/imported images (boot resources):
maas $PROFILE boot-resources read
How to delete a boot source
To delete a boot source (the location from which you can download images):
maas $PROFILE boot-source delete $SOURCE_ID
If you delete the sole boot source, then the fields ‘Sync URL’ and ‘Keyring Path’ in the web UI will take on null values.
How to edit a boot source
You can edit an existing boot source by changing the GPG keyring file ($KEYRING_FILE) and the location ($URL).
Update the boot source:
maas $PROFILE boot-source update $SOURCE_ID \
url=$URL keyring_filename=$KEYRING_FILE
At this time MAAS only supports a boot source containing official MAAS images. As a result, you can only edit a boot source if you have set up a mirror of its images. The location can change, but the keyring remains constant:
KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg
How to add a boot source
To avoid unnecessary complexity, you should probably delete any existing boot sources before adding a new one.
Presented below are a couple of use cases for adding a boot source:
- Use a local image mirror (official images)
- If you deleted the default image, recreate it
The general syntax is:
maas $PROFILE boot-sources create \
url=$URL keyring_filename=$KEYRING_FILE
The output will include a new numeric ID that identifies the boot source ($SOURCE_ID).
Since MAAS can only practically work with a single boot source, so you will need to delete any existing sources. Note that the location (URL) is the only variable. The only supported keyring is:
KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg
If you added a sole boot source, then the fields ‘Sync URL’ and ‘Keyring Path’ in the web UI will reflect its values.
How to use a local image mirror
Once the mirror is set up according to Local image mirror it is just a matter of specifying the mirror location (URL). Since the images come from the default source, you should use the default keyring. If you are following the above mirror document, the variable values should be:
- URL=https://$MIRROR/maas/images/ephemeral-v3/stable/
- KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg
Where $MIRROR is the mirror server’s hostname or IP address.
How to recreate the default boot source
Recreate the default boot source if it was ever deleted using the following variable values:
- URL=https://images.maas.io/ephemeral-v3/stable/
- KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg
How to configure agent caching
The MAAS agent cache size can be tuned to optimise performance for your workload. A larger cache can improve speeds for repeated deployments of resource intensive images. But large caches waste space if they contain rarely used images.
To configure agent caching:
- Open /etc/maas/agent.yaml on the agent with sudo permissions
- Update image_cache_size parameter to desired value in bytes
- Save changes and restart agent for new size to take effect
- Monitor cache metrics and tune further if needed
Be sure to monitor caching metrics before and after sizing changes to validate improvements. Cache tuning is an iterative process.
How to monitor resource performance
Proactive monitoring helps detect and diagnose performance issues with boot resource distribution early. Sync failures and slow transfers impact cluster-wide availability. Here are some pointers to key metrics:
- Check region sync status and fix failures
- Review sync speed metrics for issues
- Analyse cache hit/miss rates and tune cache
- Inspect deployment logs for resource download times
- Verify migrations completed on all regions
- Ensure agents have adequate disk space
Address any metrics deviations or failures quickly to minimise disruption. Resource distribution is critical for smooth MAAS operation.
How to import custom resources
Importing custom boot resources requires careful preparation and testing to avoid conflicts. Resources should be validated before use in production deployments. Here’s a thumbnail sketch of the import processes:
- Clone MAAS Packer templates as base for custom images
- Build and test resources before import
- Import into MAAS via CLI with unique name/title
- Check logs to validate successful import
- Deploy test nodes and validate functionality
Don’t assume imported resources will work without testing. Eliminate issues beforehand to avoid production disruptions.