MAAS installation (deb/2.8/UI)

2.7 2.8 2.9 3.0
Snap CLI ~ UI CLI ~ UI CLI ~ UI CLI ~ UI
Packages CLI ~ UI CLI ~ UI CLI ~ UI CLI ~ UI

This article will show you how to:

  1. Prepare for MAAS installation
  2. Install and verify MAAS
  3. Configure MAAS

Note that all headings are hyperlinks that can be bookmarked.

Prepare for MAAS installation

You should take the following steps before installing MAAS for the first time on a new system:

  1. Make sure that the target system meets the minimum hardware requirements.

  2. Make sure you understand how support works currently, for MAAS 2.8.

  3. Make sure that the target system is running Ubuntu 18.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 2.8 is “18.04,” codenamed “bionic.”

If you are upgrading from MAAS 2.3 (or earlier) to MAAS 2.8, do not follow Step 4 below; instead, see Upgrading from MAAS 2.3, below.

  1. If you are currently running Ubuntu 16.04, you can upgrade to bionic 18.04 LTS with the following procedure:

a. Upgrade the release:

sudo do-release-upgrade --allow-third-parties

b. Accept the defaults for any questions asked by the upgrade script.

c. Reboot the machine when requested.

d. 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 18.04(.nn) LTS
Release:	18.04
Codename:	bionic

Upgrading from MAAS 2.3 - 2.8

If you’re upgrading from any version less than MAAS 2.7: 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.

Upgrading from MAAS 2.3 to 2.8

If you are running MAAS version 2.3 and you want to upgrade to MAAS 2.8, the following (untested) procedure may work for you:

  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 2.7 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo add-apt-repository ppa:maas/2.8
  1. Run the release upgrade like this, answering any questions with the given default values:
sudo do-release-upgrade --allow-third-parties
  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 18.04(.nn) LTS
Release:	18.04
Codename:	bionic
  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 latest stable 2.7 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 2.8.

Upgrading from MAAS 2.4, 2.5, or 2.6 to MAAS 2.8

  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 2.8 PPA to your repository list with the following command, ignoring any apparent error messages:

sudo add-apt-repository ppa:maas/2.8
  1. Run the MAAS upgrade like this:
sudo apt update
sudo apt upgrade maas
  1. Check whether your upgrade has been successful by looking at the information on the bottom of the machine list, in your running MAAS install, to make sure you’re running the latest stable 2.8 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 2.8.

Upgrading from MAAS 2.7 to MAAS 2.8

Upgrading from MAAS 2.7 to MAAS 2.8 is standard operating procedure, completed with the following steps:

  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 unexpectedly fail.

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

sudo add-apt-repository ppa:maas/2.8
  1. Run the MAAS upgrade like this:
sudo apt update
sudo apt upgrade maas
  1. Check whether your upgrade has been successful by looking at the information on the bottom of the machine list, in your running MAAS install, to make sure you’re running the latest stable 2.8 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 2.8.

Install and verify MAAS

This section explains how to:

Upgrading from MAAS 2.7

Upgrading from MAAS 2.7 to MAAS 2.8 is accomplished via the following command sequence:

sudo add-apt-repository ppa:maas/2.8
sudo apt update
sudo apt upgrade maas

Install MAAS from packages

You can install a 2.8 stable version of MAAS via the PPA listed on the MAAS launchpad, specifically:

To add the 2.8 PPA, type:

sudo add-apt-repository -yu ppa:maas/2.8

Installation scenarios

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

sudo apt 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.

Creating a MAAS user

Finally, you will need to create a MAAS administrator user to access the web UI:

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

For example, the process might go like this:

The username can be anything. You will also be prompted to supply a password for the user. The command option --password=$PASSWORD can be used to specify one but, depending on your environment, this may pose a security risk.

At this time, MAAS does not make use of the email address. However, it may do so in the future.

Finally, the createadmin option asks 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.

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.

Next steps

Once you have installed your MAAS environment (region + rack controller) and any possible extra rack controllers(s), you are ready to begin your Configuration journey.

Reinitialising MAAS

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

sudo maas init region

The MAAS command takes additional init options; see the MAAS installation technical reference for details.

snap-3-0-ui snap-3-0-cli -->

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.

Enabling 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.”

Networking

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.