Multi-node with MAAS

This tutorial shows how to install a multi-node MicroStack cluster using MAAS as machine provider. It will deploy an OpenStack 2024.1 (Caracal) cloud.

Some steps provide estimated completion times. They are based on an average internet connection.

Prerequisite knowledge

A MAAS cluster is needed so familiarity with the MAAS machine provisioning system is a necessity. You should also be acquainted with these MAAS concepts:

Some knowledge of OpenStack networking will be helpful.

Hardware requirements

You will need a total of five machines. One to act as a client host and four to make up the MAAS cluster.


The client machine will act as an administrative host. It does not require significant resources and it need not be dedicated to this task.

All the commands in this tutorial are run on the client.

Important: For environments constrained by a proxy server, the client machine must first be configured accordingly. See section Configure for the proxy at the OS level on the Manage a proxied environment page before proceeding.

MAAS cluster

The MAAS cluster will consist of four machines (the MAAS nodes): one will manage software orchestration and three will host the actual cloud (the cloud nodes). MAAS needs to be set up in advance.

Orchestration node

The requirements for the orchestration node are:

  • physical or virtual machine
  • a dual-core processor
  • a minimum of 4 GiB of free memory
  • 128 GiB of storage available on the root disk
  • one network interface

Cloud nodes

The requirements for each of the three cloud nodes are:

  • physical machine running
  • a 16+ core amd64 processor
  • a minimum of 32 GiB of free memory
  • 500 GiB of SSD storage available on the root disk
  • a least one un-partitioned disk of at least 200 GiB in size
  • two network interfaces
    • primary: for access to the OpenStack control plane
    • secondary: for remote access to cloud VMs

Summary of MAAS nodes

In this tutorial, the four MAAS nodes that comprise the MAAS cluster are described in this way:

Machine FQDN Storage device Purpose
sunbeam00 orchestration node
sunbeam01 /dev/sdb cloud node
sunbeam02 /dev/sdb cloud node
sunbeam03 /dev/sdb cloud node

Ensure that your MAAS cluster is built before proceeding.

Prepare cloud networking

Some planning in your environment and a corresponding configuration in MAAS is needed. This affects the primary and secondary network interfaces on the three cloud nodes.

Primary interface

In this tutorial, a single subnet will be used for the primary network interface on all four MAAS nodes:

Ensure you have a subnet connected to the primary interface.

Note: The Network traffic isolation with MAAS page contains background information on the purpose of using multiple subnets.

Secondary interface

The secondary network interface must be set as ‘Unconfigured’ in MAAS and be connected to a subnet that has unused (available) IP addresses. This requirement permits the VMs to be contacted by remote hosts and comprises the “external networking” of the cloud.

In this tutorial, the following values are used:

External networking parameter Value
default gateway
address range -

The number of addresses needed is dependent upon the number of VMs you wish to be remotely contactable (simultaneously). When used in this way, the addresses are known as “floating IP addresses”.

You will be asked at a later step, via an interactive prompt, what addressing to use for external networking.

Configure MAAS

Several aspects of MAAS need to be configured. Perform the steps in the following sections within the MAAS web UI.

Configure MAAS Reserved IP Ranges

Two particular cloud networks need to be assigned their own (labelled) Reserved IP Range with a minimum number of available IP addresses. A label is created by using the Comment field for the range. Its name is based upon the chosen MAAS resource pool, which for this tutorial is my_cloud (created later).

This is what is needed:

  1. a range for network internal (minimum of five addresses) and with label my_cloud-internal-api
  2. a range for network public (minimum of ten addresses) and with label my_cloud-public-api

In this tutorial, the ranges are defined in this way:

Cloud network Reserved IP Range label IP range
internal my_cloud-internal-api -
public my_cloud-public-api -

Configure your ranges now.

Create network space

Create the network space that all the MAAS nodes will use.

In this tutorial, a single space is used, called myspace.

The space will be mapped to cloud networks in a later step.

Caution: While MAAS supports _ in space names, sunbeam and juju do not. Avoid using _ in space names.

Create the MAAS resource pool

Create a resource pool that all the MAAS nodes will reside in.

Important: Use a resource pool that is dedicated for the deployment to prevent MicroStack from unintentionally taking control of the wrong MAAS nodes.

In this tutorial, the resource pool is called my_cloud.

The pool assignment will be made in a later step.

Prepare the client

Duration: 5 minutes

Prepare the client host by installing and configuring software.

Begin by installing the openstack snap:

sudo snap install openstack --channel 2024.1/edge

MicroStack can generate a script to ensure that the client has all of the required dependencies installed and is configured correctly for use in MicroStack - you can review this script using:

sunbeam prepare-node-script --client

or the script can be directly executed in this way:

sunbeam prepare-node-script --client | bash -x

The script will ensure some software requirements are satisfied on the host. In particular, it will:

  • install orchestration software (i.e. Juju)
  • create any necessary data directories

Prepare the MAAS nodes

In this tutorial, the four MAAS nodes look like this:

Machine Resource pool Machine tag Storage device Storage tag Network tag
sunbeam00 my_cloud juju-controller
sunbeam01 my_cloud control, compute, storage /dev/sdb ceph compute
sunbeam02 my_cloud control, compute, storage /dev/sdb ceph compute
sunbeam03 my_cloud control, compute, storage /dev/sdb ceph compute

To prepare the MAAS nodes for the deployment, use the above information to perform the following:

  1. assign the resource pool (to the machines)
  2. assign the machine tags (to the machines)
  3. assign the storage tags (to the storage devices)
  4. assign the network tags (to the secondary interfaces)

The tags must be named as per the above table.

Add the MAAS deployment

Adding the MAAS deployment informs the orchestration node about the MAAS cluster.

To do this you will need to pass options that describe the deployment. They are:

  • name: an arbitrary name (e.g. my_maas)
  • token: a MAAS API key (e.g. z6sbVdQTuKWPFCFvPF:WkRdtsJnwXu38aRHUz:77SqG9DmaugFRHNT4SFtyGqubmLawNBJ)
  • url: the MAAS URL (e.g.
  • resource-pool: the chosen MAAS resource pool (e.g. my_cloud)

Add the MAAS deployment now:

sunbeam deployment add maas --name my_maas --token <token> --url <maas url> --resource-pool my_cloud

The above command will check for the following:

  • working authentication
  • uniqueness of the deployment name
  • existence of the resource pool

Map network spaces to cloud networks

Certain machines need access to certain cloud networks.

In this tutorial, because we’re using a single subnet (and space) for the primary network interface on each cloud node, map the same space (myspace) to each supported cloud network:

sunbeam deployment space map myspace data
sunbeam deployment space map myspace internal
sunbeam deployment space map myspace management
sunbeam deployment space map myspace public
sunbeam deployment space map myspace storage
sunbeam deployment space map myspace storage-cluster

These mappings tell MicroStack where to route certain types of cloud traffic.

Validate the added deployment

MicroStack expects a correctly configured MAAS, which includes adequate networking.

To check whether your environment is ready, use the deployment validate command:

sunbeam deployment validate

Example output:

Checking machines, roles, networks and storage... OK
Checking zone distribution... OK
Checking networking... OK
Report saved to '/home/ubuntu/snap/openstack/common/reports/validate-deployment-sbc01-<...>.yaml'

A report will be generated under $HOME/snap/openstack/common/reports if a failure is detected. A sample failure looks like this:

- diagnostics: A machine root disk needs to be at least 500GB to be a part of an openstack
  machine: sunbeam01
  message: root disk is too small
  name: Root disk check
  passed: false

Note: A validation error will lessen the chances of a successful deployment but it will not block an attempted deployment.

Initialise the orchestration layer

Duration: 30 minutes

Set up the orchestration layer using the cluster bootstrap command. This will provision the MAAS node that is assigned the juju-controller tag:

sunbeam cluster bootstrap

You will first be prompted whether or not to enable network proxy usage. If ‘Yes’, several sub-questions will be asked.

Use proxy to access external network resources? [y/n] (y):
Enter value for http_proxy: ():
Enter value for https_proxy: ():
Enter value for no_proxy: ():

Note that proxy settings can also be supplied by using a manifest (see Deployment manifest).

Deploy the cloud

Duration: 30 minutes
This estimate does not take into account base-level provisioning (operating system install). This can take a while for some systems (e.g. bare metal).

Deploy the cloud using the cluster deploy command. This will provision the remaining three MAAS nodes:

sunbeam cluster deploy

Configure the cloud

Duration: 5 minutes

Configure the deployed cloud using the configure command:

sunbeam configure --openrc demo-openrc

The --openrc option specifies a regular user (non-admin) cloud init file (demo-openrc here).

A series of questions will now be asked interactively. Below is a sample session. The values in square brackets, when present, provide acceptable values. A value in parentheses is the default value. We use the values for “external networking” given earlier:

CIDR of network to use for external networking (
IP address of default gateway for external network (
Populate OpenStack cloud with demo user, default images, flavors etc [y/n] (y):
Username to use for access to OpenStack (demo):
Password to use for access to OpenStack (mt********):
Network range to use for project network (
Enable ping and SSH access to instances? [y/n] (y):
Start of IP allocation range for external network (
End of IP allocation range for external network (
Network type for access to external network [flat/vlan] (flat):
Writing openrc to demo-openrc ... done

The network range for the initial project defaults to This is for OpenStack internal purposes (“private networking”) and should suffice for most clouds.

These questions are explained in more detail on the Interactive configuration prompts page in the reference section.

Launch a VM

Duration: 2 minutes
The first launch will take longer than any subsequent launches due to caching.

Verify the cloud by launching a VM called ‘test’ based on the ‘ubuntu’ image (Ubuntu 22.04 LTS). The launch command is used:

sunbeam launch ubuntu --name test

Sample output:

Launching an OpenStack instance ...
Access instance with `ssh -i /home/ubuntu/.config/openstack/sunbeam ubuntu@`

Connect to the VM over SSH using the provided command.

Related how-tos

Now that OpenStack is set up, be sure to check out the following how-to guides:

Last updated 3 days ago. Help improve this document in the forum.