How to import images (snap/3.1/CLI)

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.

Three questions you may have:

  1. How do I import standard images from maas.io?
  2. How do I use other image mirrors to download images?
  3. How do I import and provision non-Ubuntu images?

Note that it is possible to build your own images in a limited sense: see MAAS Image Builder.

Importing 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). Below, we have selected two additional releases:

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.

Click the ‘Save selection’ button to initiate the import. MAAS will present existing images along with the newly-selected ones. The latter will have their status updated as the import is processed:

To remove an image, un-select it and click ‘Save selection’.

Image mirrors

You can also host Ubuntu images on a mirror. Configure this mirror by selecting ‘Custom’ beneath ‘Choose source’. Enter the mirror URL and click ‘Connect’.

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 clicking ‘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.

Other images

It is also possible to import and provision images other than Ubuntu. Images supported and provided by MAAS will appear beneath the ‘Other Images’ section. Currently, images for CentOS 6.6, CentOS 7.0, and CentOS 8.0 are available. 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.

Eight questions you may have:

  1. How do I get started with the MAAS CLI?
  2. How do I list boot sources?
  3. How do I select images?
  4. How do I list image selections?
  5. How do I import newly-selected images?
  6. How do I list currently available images?
  7. How do I delete a boot source?
  8. How do I edit a boot source?

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.

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="*"

List image selections

To list image selections for a boot source:

maas $PROFILE boot-source-selections read $SOURCE_ID

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.

List currently available images

To list currently available/imported images (boot resources):

maas $PROFILE boot-resources read

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.

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

Add a boot source

To avoid unnecessary complexity, you should probably delete any existing boot sources before adding a new one.

Presented below are two use cases for adding a boot source:

  1. Use a local image mirror (official images)
  2. 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.

Using 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:

  1. URL=https://$MIRROR/maas/images/ephemeral-v3/stable/
  2. KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg

Where $MIRROR is the mirror server’s hostname or IP address.

Recreate the default boot source

Recreate the default boot source if it was ever deleted using the following variable values:

  1. URL=https://images.maas.io/ephemeral-v3/stable/
  2. KEYRING_FILE=/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg

I think this doesn’t make sense. If you want to update a bootsource, are you saying that you have to update the GPG keyring file? or is that an example?

For example, I wanted to update a boot source (architectures), and I did this:

anton@maas:~$ maas admin boot-source-selection update 1 1 arches="amd64" arches="arm64"
Success.
Machine-readable output follows:
{
    "os": "ubuntu",
    "release": "focal",
    "arches": [
        "amd64",
        "arm64"
    ],
    "subarches": [
        "*"
    ],
    "labels": [
        "*"
    ],
    "boot_source_id": 1,
    "id": 1,
    "resource_uri": "/MAAS/api/2.0/boot-sources/1/selections/1/"
}

which isn’t about the keyring. I found this section a bit confusing. I’m happy to add my example as a second example, but wondering if we should clean up the explanation about what updating is about?

now I realised I was confused by boot sources and boot source selections. I’ve updated the docs based off what I learned.