How to install MAAS (deb/3.1/UI)

2.9 3.0 3.1
DEB CLI ~ UI CLI ~ UI CLI ~ UI
SNAP CLI ~ UI CLI ~ UI CLI ~ UI

MAAS initialisation modes reference

MAAS supports the following modes, which dictate what services will run on the local system:

Mode Region Rack Database Description
region X Region API server only
rack X Rack controller only
region+rack X X Region API server and rack controller
none Reinitialises MAAS and stops services

About SSH keys

MAAS uses your Launchpad or Github SSH keys to access machines that have been deployed. Normally, you enter this key during the initialisation of MAAS. If you don’t have a key associated with either of these services, you will have an opportunity to paste your public key into the MAAS SSH key list, after you’ve started MAAS for the first time as part of the welcome screens.

About the MAAS URL

All run modes (except none) prompt for a MAAS URL, interpreted differently depending on the mode:

  • region: Used to create a new region controller.
  • rack: Used to locate the region controller.

About the shared secret

The ‘rack’ and ‘region+rack’ modes will additionally ask for a shared secret that will allow the new rack controller to register with the region controller.

How to install MAAS

This article will show you:

Note that all headings are hyperlinks for bookmarking.

How to check system requirements for MAAS

Before installing MAAS for the first time, you should make sure that the target system meets the minimum requirements for the machines that run MAAS, which vary widely depending on local implementation and usage. Below, you will find resource estimates based on MAAS components and operating system (Ubuntu Server). We consider both a test configuration (for proof of concept) and a production environment.

Requirements for a test environment

Here is a proof-of-concept scenario, with all MAAS components installed on a single host. This scenario assumes two complete sets of images (latest two Ubuntu LTS releases) for a single architecture (amd64).

Memory (MB) CPU (GHz) Disk (GB)
Region controller (minus PostgreSQL) 512 0.5 5
PostgreSQL 512 0.5 5
Rack controller 512 0.5 5
Ubuntu Server (including logs) 512 0.5 5

Based on this table, the approximate requirements for this scenario are 2 GB memory, 2 GHz CPU, and 20 GB of disk space.

Requirements for a production environment

Here is a production scenario designed to handle a high number of sustained client connections. This scenario implements both high availability (region and rack) and load balancing (region). MAAS reserves extra space for images (database and rack controller), while some images, such as those for Microsoft Windows, may require a lot more – so plan accordingly.

Memory (MB) CPU (GHz) Disk (GB)
Region controller (minus PostgreSQL) 2048 2.0 5
PostgreSQL 2048 2.0 20
Rack controller 2048 2.0 20
Ubuntu Server (including logs) 512 0.5 5

So, based on the above, the approximate requirements for this scenario are:

  1. A region controller (including PostgreSQL) installed on one host, with 4.5 GB memory, 4.5 GHz CPU, and 45 GB of disk space.
  2. A duplicate region controller (including PostgreSQL) on a second host, also with 4.5 GB memory, 4.5 GHz CPU, and 45 GB of disk space.
  3. A rack controller installed on a third host, with 2.5 GB memory, 2.5 GHz CPU, and 40 GB of disk space.
  4. A duplicate rack controller on a fourth host, also with 2.5 GB memory, 2.5 GHz CPU, and 40 GB of disk space.

The tables above refer to MAAS infrastructure only. They do not cover the resources needed by subsequently-added nodes. Note that machines should have IPMI-based BMC controllers for power cycling, see Power management for more details.

Some examples of factors that influence hardware specifications include:

  1. the number of connecting clients (client activity)
  2. how you decide to distribute services
  3. whether or not you use high availability/load balancing.
  4. the number of images that you choose to store (disk space affecting PostgreSQL and the rack controller)

Also, this discussion does not take into account a possible local image mirror, which would be a large consumer of disk space.

One rack controller should only service 1000 machines or less, regardless of how you distribute them across subnets. There is no load balancing at the rack level, so you will need additional, independent rack controllers. Each controller must service its own subnet(s).

How to ugprade from MAAS 3.0 to MAAS 3.1

To upgrade from MAAS 3.0 to MAAS 3.1:

  1. Back up your MAAS server completely; the tools and media are left entirely to your discretion. Just be sure that you can definitely restore your previous configuration, should this procedure fail to work correctly.

  2. Add the MAAS 3.1 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo apt-add-repository ppa:maas/3.1
  1. Run the MAAS upgrade like this:
sudo apt update
sudo apt upgrade maas
  1. Check your running MAAS install (by looking at the information on the bottom of the machine list) to make sure you’re running the 3.1 release.

  2. If this didn’t work, you will need to restore from the backup you made in step 1, and consider obtaining separate hardware to install MAAS 3.1.

How to upgrade from 2.8 or lower to MAAS 3.1

If you are running MAAS 2.8 or lower, you can upgrade directly to MAAS 3.1. You must first make sure that the target system is running Ubuntu 20.04 LTS or higher, by executing the following command:

lsb_release -a

The response should look something like this:

Distributor ID:	Ubuntu
Description:	Ubuntu xx.yy
Release:	xx.yy
Codename:	$RELEASE_NAME

The minimum “xx.yy” required for MAAS 3.0 is “20.04,” code-named “focal.”

If you are currently running Ubuntu bionic 18.04 LTS, you can upgrade to focal 20.04 LTS with the following procedure:

  1. Upgrade the release:
sudo do-release-upgrade --allow-third-party
  1. Accept the defaults for any questions asked by the upgrade script.

  2. Reboot the machine when requested.

  3. Check whether the upgrade was successful:

lsb_release -a

A successful upgrade should respond with output similar to the following:

Distributor ID:	Ubuntu
Description:	Ubuntu 20.04(.nn) LTS
Release:	20.04
Codename:	focal

If you’re upgrading from MAAS version 2.8 or lower to version 3.1: While the following procedures should work, note that they are untested. Use at your own risk. Start by making a verifiable backup; see step 1, below.

  1. Back up your MAAS server completely; the tools and media are left entirely to your discretion. Just be sure that you can definitely restore your previous configuration, should this procedure fail to work correctly.

  2. Add the MAAS 3.1 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo apt-add-repository ppa:maas/3.1
  1. Run the release upgrade like this, answering any questions with the given default values:
sudo do-release-upgrade --allow-third-party
  1. Check whether your upgrade has been successful by entering:
lsb_release -a

If the ugprade was successful, this command should yield output similar to the following:

No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 20.04(.nn) LTS
Release:	20.04
Codename:	focal
  1. Check your running MAAS install (by looking at the information on the bottom of the machine list) to make sure you’re running the 3.1 release.

  2. If this didn’t work, you will need to restore from the backup you made in step 1, and consider obtaining separate hardware to install MAAS 3.1.

How to do a fresh install of MAAS 3.1 from packages

The recommended way to set up an initial MAAS environment is to put everything on one machine:

sudo apt-add-repository ppa:maas/3.0
sudo apt update
sudo apt-get -y install maas

Executing this command leads you to a list of dependent packages to be installed, and a summary prompt that lets you choose whether to continue with the install:

Choosing “Y” proceeds with a standard apt package install.

Distributed environment

For a more distributed environment, you can place the region controller on one machine:

sudo apt install maas-region-controller

and the rack controller on another:

sudo apt install maas-rack-controller
sudo maas-rack register

These two steps will lead you through two similar apt install sequences.

How to create a MAAS user

You will need to create a MAAS administrator user to access the web UI:

sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS

$PROFILE is the administrative MAAS username you wish to create. $EMAIL_ADDRESS is an email address you may type in at random (currently, MAAS does not use this email address).

The createadmin option will ask for an SSH key. If you have an SSH key associated with your launchpad or github accounts, you can enter the username here to use the associated key. For launchpad, just enter lp:username, and for github, enter gh:username at the prompt. In both cases, the actual username has to be supplied after the lp: or gh: prefix.

How to check the status of MAAS services

You can check the status of running services with:

sudo maas status

Typically, the output looks something like this:

bind9                            RUNNING   pid 7999, uptime 0:09:17
dhcpd                            STOPPED   Not started
dhcpd6                           STOPPED   Not started
ntp                              RUNNING   pid 8598, uptime 0:05:42
postgresql                       RUNNING   pid 8001, uptime 0:09:17
proxy                            STOPPED   Not started
rackd                            RUNNING   pid 8000, uptime 0:09:17
regiond:regiond-0                RUNNING   pid 8003, uptime 0:09:17
regiond:regiond-1                RUNNING   pid 8008, uptime 0:09:17
regiond:regiond-2                RUNNING   pid 8005, uptime 0:09:17
regiond:regiond-3                RUNNING   pid 8015, uptime 0:09:17
tgt                              RUNNING   pid 8040, uptime 0:09:15

How to re-initialise MAAS

It is also possible to re-initialise MAAS to switch modes. For example, to switch from rack to region:

sudo maas init region

How to list additional MAAS initialisation options

The init command can takes optional arguments. To list them, as well as read a brief description of each, you can enter:

sudo maas init --help

How to configure MAAS

Once you’ve successfully installed MAAS (regardless of method), you can now login here:

http://${API_HOST}:5240/MAAS

where $API_HOST is the hostname or IP address of the region API server, which was set during installation. You will see a screen like this:

Log in at the prompts, with the login information you created when initialising MAAS.

Configuration

After a fresh MAAS installation, the web UI presents a couple of welcome screens. From these screens, you can set many system-wide options, including connectivity, image downloads, and authentication keys.

Your main concerns for this experiment are the DNS forwarder, the Ubuntu image import section, and the SSH public key, though you might want to set the region name to something memorable, since this text will appear at the bottom of every MAAS screen in this install domain. Set the DNS forwarder to something obvious, e.g., 8.8.8.8, Google’s DNS server. Set this to your own internal DNS server if you know the IP address.

Select an Ubuntu image to import, noting that you may be required to select at least one LTS version, depending upon the version of MAAS that snap installed. In this example, we’ve already chosen an image, and downloading is partially complete.

When you click on “Continue,” the screen will shift to a screen labelled, “SSH keys for admin:”

In the source drop-down, select “Launchpad,” “Github,” or “Upload.” If you choose one of the first two, you will need to enter your username for that service. For example, if you want to upload your SSH public key from Launchpad, you would enter:

lp:<username>

Likewise, if you want to upload your github public SSH key, you would enter:

gh:<username>

If you want to use your existing public key from your home directory, you can select “Upload”and then copy your entire public key from .ssh/id_rsa.pub (or wherever you may have stored the key):

and paste it into the block labelled “Public key.” Finally, press the “Import” button to import this key:

With this complete, you’ll see that MAAS has been successfully set up. Click ‘Go to the Dashboard’ to proceed.

Note that you may have to wait a few moments for your selected images to sync locally.

How to enable DHCP

Before moving forward with MAAS, you’ll want to enable DHCP. You can do this very easily from the web UI by selecting “Subnets” from the top menu, choosing the VLAN on which you want to enable DHCP, and select the button marked, “Enable DHCP.”

About network discovery

The Dashboard landing page lists non-registered devices that MAAS detected automatically on the network. This network discovery process allows you to easily add or map devices already connected to your network – devices that you may not necessarily want to manage with MAAS.

sudo maas status doesn’t seem to apply to MAAS 3.1:

sudo maas status

usage: maas [-h] COMMAND ...

optional arguments:
  -h, --help      show this help message and exit

drill down:
  COMMAND
    login         Log in to a remote API, and remember its description and credentials.
    logout        Log out of a remote API, purging any stored credentials.
    list          List remote APIs that have been logged-in to.
    refresh       Refresh the API descriptions of all profiles.
    init          Initialize controller.
    apikey        Used to manage a user's API keys. Shows existing keys unless --generate or
                  --delete is passed.
    configauth    Configure external authentication.
    createadmin   Create a MAAS administrator account.
    changepassword
                  Change a MAAS user's password.

https://maas.io/

argument COMMAND: invalid choice: 'status' (choose from 'login', 'logout', 'list', 'refresh', 'init', 'apikey', 'configauth', 'createadmin', 'changepassword')

maas init in MAAS 3.1 apparently doesn’t support the region | rack | rack+region argument available in previous versions.

sudo maas init --help
usage: maas init [-h] [--skip-admin] [--admin-username USERNAME] [--admin-password PASSWORD]
                 [--admin-email EMAIL] [--admin-ssh-import LP_GH_USERNAME]
                 [--candid-agent-file CANDID_AGENT_FILE] [--candid-domain CANDID_DOMAIN]
                 [--candid-admin-group CANDID_ADMIN_GROUP] [--rbac-url RBAC_URL]
                 [--rbac-service-name RBAC_SERVICE_NAME]

Initialize controller.

optional arguments:
  -h, --help            show this help message and exit
  --skip-admin          Skip the admin creation.
  --admin-username USERNAME
                        Username for the admin account.
  --admin-password PASSWORD
                        Force a given admin password instead of prompting.
  --admin-email EMAIL   Email address for the admin.
  --admin-ssh-import LP_GH_USERNAME
                        Import SSH keys from Launchpad (lp:user-id) or Github (gh:user-id) for the
                        admin.
  --candid-agent-file CANDID_AGENT_FILE
                        Agent file containing Candid authentication information
  --candid-domain CANDID_DOMAIN
                        The authentication domain to look up users in for the external Candid
                        server.
  --candid-admin-group CANDID_ADMIN_GROUP
                        Group of users whose members are made admins in MAAS
  --rbac-url RBAC_URL   The URL for the Canonical RBAC service to use.
  --rbac-service-name RBAC_SERVICE_NAME
                        Optionally, the name of the RBAC service to register this MAAS as. If not
                        provided, a list with services that the user can register will be
                        displayed, to choose from.

There is no reference to external Postgresql db configuration in MAAS 3.1 docs and the --database-uri option referenced here apparently doesn’t apply for the above mentioned reason (maas init doesn’t support it).

ah. looks like there is massive inconsistency between MAAS 3.1 snap and apt packages. the documentation above, ostensibly for the apt package, seems to be a clone of the snap package docs but the apt package is completely different.

this is the help from the snap package for maas init:

maas init --help
usage: maas init [-h] {region+rack,region,rack} ...

Initialise MAAS in the specified run mode.

optional arguments:
  -h, --help            show this help message and exit

run modes:
  {region+rack,region,rack}
    region+rack         Both region and rack controllers
    region              Region controller only
    rack                Rack controller only

When installing region or rack+region modes, MAAS needs a
PostgreSQL database to connect to.

If you want to set up PostgreSQL for a non-production deployment on
this machine, and configure it for use with MAAS, you can install
the maas-test-db snap before running 'maas init':

    sudo snap install maas-test-db
    sudo maas init region+rack --database-uri maas-test-db:///