Snap >>> | UI/2.7 | UI/2.8 | CLI/2.7 | CLI/2.8 |
Packages >>> | UI/2.7 | UI/2.8 | CLI/2.7 | CLI/2.8 |
Welcome to the installation guide and compact tutorial for MAAS. This pre-flight checklist will help you get MAAS running quickly. Collapsible sections unclutter the page, and detailed doc references help you dig deeper. Quick questions kick off each section, help you skip to your desired topic.
Start with the links above: Choose your preferred install method (snap vs. debian packages), interface (web UI vs. command line interface/CLI), and version (2.7 vs. 2.8) – then select the matching link to instantly customize this material.
Quick questions you may have:
- How do I upgrade my existing MAAS?
- How do I install and configure MAAS?
- How do I add machines to MAAS?
- How do I deploy and manage machines with MAAS?
Upgrade an existing MAAS
It’s easy to upgrade your 2.7 snap to 2.8 – but you’ll want to confirm whether you’re running MAAS in a single node (region+rack) or on multiple nodes (separate region and rack controllers).
For a region+rack configuration
Upgrade your 2.7 snap to 2.8 with this command:
$ sudo snap refresh --channel=2.8 maas
After entering your password, the snap will refresh from the 2.8 channel. You will not need to re-initialize MAAS.
For a multi-node MAAS deployment
If you are using a multi-node maas deployment with separate regions and racks, you should first run this command on each of your rack nodes:
$ sudo snap refresh --channel=2.8 maas
Finally, run the same command on your region node(s).
Installing and configuring MAAS
Installing and configuring the MAAS 2.8 snap is relatively straightforward, but there are choices to make. For example, you’ll want to decide whether to install a test/proof-of-concept configuration, or just go ahead and set up a production configuration. Use this section to help you get MAAS up and running, so that you can start adding and deploying machines.
Quick questions you may have:
- How do I prepare to install MAAS?
- How do I install MAAS?
- How do I initialize MAAS?
- How do I configure MAAS and get it running?
Preparing to install MAAS
Preparing for MAAS requires a little up-front work. First, you need to confirm that your intended host meets the hardware requirements for MAAS; then there are a few setup steps you’ll want to complete to prevent delays later on.
Quick questions you might have:
- What are the requirements for a test environment?
- What are the requirements for a production environment?
- What setup steps should I complete before installation?
MAAS host requirements
The minimum requirements for your MAAS host(s) vary widely, depending on local implementation and usage. Below, you will find resource estimates based on both the MAAS components and the Ubuntu Server operating system. 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:
- A region controller (including PostgreSQL) installed on one host, with 4.5 GB memory, 4.5 GHz CPU, and 45 GB of disk space.
- 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.
- A rack controller installed on a third host, with 2.5 GB memory, 2.5 GHz CPU, and 40 GB of disk space.
- 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:
- the number of connecting clients (client activity)
- how you decide to distribute services
- whether or not you use high availability/load balancing.
- 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).
Setting up for MAAS
There are a few preliminary steps that will smooth out your MAAS usage:
-
Disable bind9 - If
bind9
is running on the system where you’re going to host MAAS, you need to disable it. The bind9 daemon interferes with MAAS, producing some unusual and hard-to-debug errors. You can see if it’s running with the commandps aux | grep named
. - Set your machines to netboot - MAAS uses PXE to remotely boot your machines via their NICs, so you’ll need to have your machines set to netboot, or MAAS can’t access and use them.
- Turn on machines that should auto-enlist - If you want MAAS to find and enlist your machines automatically, you need to turn them on.
- OR gather the UUIDs and MAC addresses for your machines - If you’re going to manually enroll machines, you’ll need this information.
- AND determine the power type - If you’re manually enrolling machines, you’ll also want to be able to tell MAAS how power them up. Follow the link to learn more about power types.
If you have installed bind9
or have it running, you will need to uninstall it before installing MAAS. You can check with ps aux | grep named
to see if it’s running. The bind9
daemon interferes with MAAS operation and creates a number of unusual, hard-to-debug errors – but don’t worry, MAAS provides DNS and can work with existing DNS servers.
Installing MAAS
Snaps are containerised software packages. To install MAAS from a snap simply enter the following:
$ sudo snap install maas --channel=2.8
After entering your password, the snap will download and install from the 2.8 channel – though MAAS needs initialising before it’s ready to go.
Initialising MAAS
MAAS 2.8 supports essentially three initialisation modes and two configurations: a test or proof-of-concept configuration, and a production configuration. MAAS 2.8 separates the PostgreSQL database from the MAAS snap for scalability reasons, so the steps are a bit different than previous versions. In the case of the production configuration, native PostgreSQL on the localhost is used for the MAAS database. For the test configuration, a PostgreSQL snap is provided to encapsulate the test database. Read on to determine your desired modes before initialising.
Quick questions you may have:
- What are the initialisation modes for MAAS 2.8?
- How do I initialise MAAS in a test configuration?
- How do I initialise MAAS for production?
MAAS initialisation modes
MAAS supports the following modes, which dictate what services will run on the local system:
Mode | Region | Rack | Database | Description |
---|---|---|---|---|
all * |
X | X | X | Deprecated (see warning below) |
region |
X | Region API server only | ||
rack |
X | Rack controller only | ||
region+rack |
X | X | Region API server and rack controller | |
none |
Deinitializes MAAS and stops services |
all mode being deprecated: The MAAS initialisation mode “all” is deprecated in MAAS version 2.8.0 and will be removed in MAAS version 2.9.0.
Initialising MAAS as a test configuration
We want to provide a more compact version for those who may be testing MAAS. To achieve this, we’re providing a separate snap, called maas-test-db
, which provides a PostgreSQL database for use in testing and evaluating MAAS. The following instructions will help you take advantage of this test configuration.
Once MAAS is installed, you can use the --help
flag with maas init
to get relevant instructions:
$ sudo 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:///
We’ll quickly walk through these instructions to confirm your understanding. First, install the maas-test-db
snap:
sudo snap install maas-test-db
Note that this step installs a a running PostgreSQL and a MAAS-ready database instantiation. When it’s done, you can double check with a built-in PostgreSQL shell:
$ maas-test-db.psql
psql (10.6)
Type "help" for help.
postgres=# \l
This will produce a list of databases, one of which will be maasdb
, owned by maas
. Note that this database is still empty because MAAS is not yet initialized and, hence, is not yet using the database. Once this is done, you can run the maas init
command:
sudo maas init region+rack --database-uri maas-test-db:///
After running for a moment, the command will prompt you for a MAAS URL; typically, you can use the default:
MAAS URL [default=http://10.45.222.159:5240/MAAS]:
When you’ve entered a suitable URL, or accepted the default, the following prompt will appear:
MAAS has been set up.
If you want to configure external authentication or use
MAAS with Canonical RBAC, please run
sudo maas configauth
To create admins when not using external authentication, run
sudo maas createadmin
Let’s assume you just want a local testing user named admin
:
$ sudo maas createadmin
Username: admin
Password: ******
Again: ******
Email: admin@example.com
Import SSH keys [] (lp:user-id or gh:user-id): gh:yourusername
At this point, MAAS is basically set up and running. You can confirm this with sudo maas status
. If you need an API key, you can obtain this with sudo maas apikey --username yourusername
. Now you will be able to test and evaluate MAAS by going to the URL you entered or accepted above and entering your admin
username and password.
Initialise MAAS for a production configuration
To install MAAS in a production configuration, you need to setup PostgreSQL, as described below.
Setting up PostgreSQL from scratch
To set up PostgreSQL, even if it’s running on a different machine, you can use the following procedure:
-
You will need to install PostgreSQL on the machine where you want to keep the database. This can be the same machine as the MAAS region/rack controllers or a totally separate machine. If PostgreSQL (version 10 or better) is already running on your target machine, you can skip this step. To install PostgreSQL, run these commands:
sudo apt update -y sudo apt install -y postgresql
-
You want to make sure you have a suitable PostgreSQL user, which can be accomplished with the following command, where
$MAAS_DBUSER
is your desired database username, and$MAAS_DBPASS
is the intended password for that username. Note that if you’re executing this step in a LXD container (as root, which is the default), you may get a minor error, but the operation will still complete correctly.sudo -u postgres psql -c "CREATE USER \"$MAAS_DBUSER\" WITH ENCRYPTED PASSWORD '$MAAS_DBPASS'"
-
Create the MAAS database with the following command, where
$MAAS_DBNAME
is your desired name for the MAAS database (typically known asmaas
). Again, if you’re executing this step in a LXD container as root, you can ignore the minor error that results.sudo -u postgres createdb -O "$MAAS_DBUSER" "$MAAS_DBNAME"
-
Edit
/etc/postgresql/10/main/pg_hba.conf
and add a line for the newly created database, replacing the variables with actual names. You can limit access to a specific network by using a different CIDR than0/0
.host $MAAS_DBNAME $MAAS_DBUSER 0/0 md5
-
You can then initialise MAAS via the following command:
sudo maas init region+rack --database-uri "postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME"
You should use localhost
for $HOSTNAME
if you’re running PostgreSQL on the same box as MAAS.
Don’t worry; if you leave out any of the database parameters, you’ll be prompted for those details.
Checking MAAS service status
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
With MAAS installed and initialised, you can now open the web UI in your browser and begin your Configuration journey.
Example of MAAS initialisation
The following demonstrates the region+rack
mode, a popular initialisation choice for MAAS:
sudo maas init region+rack
maas
will ask for the MAAS URL:
MAAS URL [default=http://10.55.60.1:5240/MAAS]: http://192.168.122.1:5240/MAAS
If you also need to create an admin user, you can use:
sudo maas createadmin
which takes you through the following exchange:
Create first admin account:
Username: admin
Password: ******
Again: ******
Email: admin@example.com
Import SSH keys [] (lp:user-id or gh:user-id): lp:petermatulis
You will use the username and password created above to access the web UI. If you enter a Launchpad or GitHub account name with associated SSH key, MAAS will import them automatically.
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.
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.
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
Additional `init` 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
Logging in to MAAS
MAAS post-install configuration
Downloading OS images for MAAS
Adding admin SSH keys to MAAS
Setting up MAAS networking
Importing SSH keys to machines
Adding physical machines
Adding virtual machines
Commissioning machines
Acquiring machines
Deploying machines
SSH access to deployed machines
Releasing deployed machines
Marking machines as broken
As explained in the Introduction, the installation of MAAS consists of the installation of a rack controller and a region controller which, in turn, provide a multitude of services. Go ahead and install MAAS!
Access the web UI
You will be using the web UI so now is the time to log in and take a look around! Proceed to the web UI now. This will involve the creation of an administrator user. Notice how the web UI (API server) is accessed via port 5240 and not port 80.
Although the web UI may be accessed via port 80, this is not guaranteed to work in future versions of MAAS.
The initial access of the web UI will kick off an optional configuration journey whose purpose is to get the essential aspects of MAAS configured right away.
Completing the journey will remove the need to perform equivalent deeds below so you’ll need to adjust accordingly.
Zones
For zones, many people won’t need to change anything as a default zone is provided out of the box. However, they are still worth reading about, especially if the default one does not suffice.
Networking
Firstly, in terms of IP addresses, understand what a reserved range is by reading Concepts and terms. Create one (not reserved dynamic range) if you need one.
Secondly, configure a default gateway and a nameserver that your machines will use. See Networking for how to do this.
Import boot images
Read up on images as they’re quite important. Continue reading until you have discovered how to import them. You will see that you have the choice to use the CLI to do this. Either way: achievement unlocked!
The import process can take a while. Consider moving on and coming back. Just ensure that the import has completed prior to adding a machine.
Once installed, by default, MAAS will begin downloading images for the latest Ubuntu LTS.
Access the MAAS CLI
Even if you’ve imported images with the web UI, it would be wise (and cool?) to give the CLI a spin in case you ever need to use it later. Although we strive to make the web UI feature-equivalent to the CLI, some things can still only be done with the CLI.
Enable DHCP
You won’t get far without DHCP since it is required in order to make PXE work, which, in turn, is necessary to introduce your systems to MAAS. But you knew that. Anyway, DHCP is installed - it just needs enabling. Read about DHCP and continue until you have enabled it.
Users and SSH keys
You already have an administrative user but MAAS can also have regular users (who log in to the interface or use the CLI). What users you create depends on how you intend to use MAAS.
Additionally, in order for a user to log into a MAAS-deployed machine that user must have their public SSH key installed on it.
Study User accounts to learn about how to create more users and how to add their public SSH keys to MAAS. Once that’s done, every deployed machine will automatically have that key installed.
Add a machine
It’s time to actually do something! MAAS manages machines, but at this time it doesn’t have any. Go forth and add a machine now. Obviously, you need a spare physical system (but KVM works too). In the web UI, confirm that the import of images has finished!
Go to the ‘Machines’ page in the web UI. A successfully added machine will soon appear there with a status of New. It will also have a funny name. Whatever, you’re still a rock star!
Edit power type
A machine needs to power cycle while being managed by MAAS. The next step is therefore to tell MAAS how to do this. That is, you need to edit the power type of the machine’s BMC.
Commission a machine
Commissioning a machine involves MAAS testing it to ensure that it is able to communicate properly with the region API server. Commission your machine now.
Deploy a machine
Lots of folks would have Juju take over at this point. Juju acts as a sort of command & control centre for adding services/applications on top of MAAS machines (among other “clouds”). If you’re just not there and/or you want to quickly test things out you can use the web UI to deploy a machine directly.
SSH to the machine
If you imported your SSH key then you should now be able to ssh to the deployed machine by connecting to the ‘ubuntu’ account. The machine’s page in the web UI will inform you of its IP address. Mission accomplished!