MAAS bootstrap tutorial
An evolving example may be useful to introduce you to MAAS, and it doesn’t have to be comprehensive – just coherent and plausible. For this example, we’ll use the latest MAAS snap from the UI.
Begin by installing (but not initialising) the MAAS snap:
sudo snap install maas
maas (3.2/stable) <some-build-string> from Canonical installed
The MAAS initialisation mode “region+rack” will do fine for this install. No need to add the complexity of separate rack controllers just yet. It’s not quite time to initialise, though; we need to choose production vs. proof-of-concept. For now, let’s go with the production configuration, since there’s more to see and do.
A production setup starts with a local PostgreSQL install, from packages. And, like most Debian installs, that starts with an update, to grab any packages that might be needed for the install to succeed:
sudo apt update -y
[sudo] password for stormrider:
Hit:1 http://dl.google.com/linux/chrome/deb stable InRelease
Hit:2 http://us.archive.ubuntu.com/ubuntu focal InRelease
Get:3 http://security.ubuntu.com/ubuntu focal-security InRelease [107 kB]
Get:4 http://us.archive.ubuntu.com/ubuntu focal-updates InRelease [111 kB]
Get:5 http://us.archive.ubuntu.com/ubuntu focal-backports InRelease [98.3 kB]
Get:6 http://us.archive.ubuntu.com/ubuntu focal-updates/main amd64 Packages [310 kB]
Get:7 http://security.ubuntu.com/ubuntu focal-security/main amd64 DEP-11 Metadata [21.2 kB]
Get:8 http://us.archive.ubuntu.com/ubuntu focal-updates/main i386 Packages [187 kB]
Get:9 http://us.archive.ubuntu.com/ubuntu focal-updates/main amd64 DEP-11 Metadata [196 kB]
Get:10 http://us.archive.ubuntu.com/ubuntu focal-updates/universe amd64 Packages [142 kB]
Get:11 http://us.archive.ubuntu.com/ubuntu focal-updates/universe i386 Packages [77.6 kB]
Get:12 http://security.ubuntu.com/ubuntu focal-security/universe amd64 DEP-11 Metadata [35.8 kB]
Get:13 http://us.archive.ubuntu.com/ubuntu focal-updates/universe Translation-en [71.7 kB]
Get:14 http://us.archive.ubuntu.com/ubuntu focal-updates/universe amd64 DEP-11 Metadata [176 kB]
Get:15 http://us.archive.ubuntu.com/ubuntu focal-updates/multiverse amd64 DEP-11 Metadata [2,468 B]
Get:16 http://us.archive.ubuntu.com/ubuntu focal-backports/universe amd64 DEP-11 Metadata [1,972 B]
Fetched 1,538 kB in 2s (827 kB/s)
Reading package lists... Done
Building dependency tree
Reading state information... Done
325 packages can be upgraded. Run 'apt list --upgradable' to see them.
Then I can install PostgreSQL, probably version 12:
sudo apt install -y postgresql
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages were automatically installed and are no longer required:
enchant geoip-database gir1.2-mutter-5 gsfonts libbind9-161 libcroco3 libdns-export1107
libdns1107 libdns1109 libenchant1c2a libfprint0 libgeoip1 libgnome-desktop-3-18 libirs161
libisc-export1104 libisc1104 libisc1105 libisccc161 libisccfg163 liblwres161 libmicrodns0
libmutter-5-0 liboauth0 libpoppler90 libpython3.7 libpython3.7-minimal libpython3.7-stdlib
linux-image-5.3.0-40-generic linux-modules-5.3.0-40-generic
linux-modules-extra-5.3.0-40-generic ubuntu-software ubuntu-system-service
Use 'sudo apt autoremove' to remove them.
Suggested packages:
postgresql-doc
The following NEW packages will be installed:
postgresql
0 upgraded, 1 newly installed, 0 to remove and 325 not upgraded.
Need to get 4,004 B of archives.
After this operation, 67.6 kB of additional disk space will be used.
Get:1 http://us.archive.ubuntu.com/ubuntu focal/main amd64 postgresql all 12+214 [4,004 B]
Fetched 4,004 B in 0s (13.2 kB/s)
Selecting previously unselected package postgresql.
(Reading database ... 227326 files and directories currently installed.)
Preparing to unpack .../postgresql_12+214_all.deb ...
Unpacking postgresql (12+214) ...
Setting up postgresql (12+214) ...
Yep, version 12. Now we need to set up a PostgreSQL user:
sudo -u postgres psql -c "CREATE USER \"maascli\" WITH ENCRYPTED PASSWORD 'maascli'"
CREATE ROLE
We also need a suitable MAAS database:
sudo -u postgres createdb -O "maascli" "maasclidb"
Note that there’s no system response (the old UNIX rule of “no news is good news”). Next, we need to add the database to the PostgreSQL HBA configuration, by editing /etc/postgres/12/main/pg_hba.conf, adding a line to the bottom of the file:
sudo vi /etc/postgresql/12/main/pg_hba.conf
host maasclidb maascli 0/0 md5
Finally, we can initialise MAAS, like this:
sudo maas init region+rack --database-uri "postgres://maascli:maascli@localhost/maasclidb"
MAAS URL [default=http://192.168.43.251:5240/MAAS]:
This command offers me a bit of important feedback, the MAAS URL, which will be needed for the CLI login. That’s followed by a running commentary on the steps MAAS is taking to start up.
It all ends with the following admonition:
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
Well, that’s an easy call. Let’s just run “createadmin” real quick:
sudo maas createadmin
[sudo] password for stormrider:
Username: admin
Password:
Again:
Email: admin@admin.com
Import SSH keys [] (lp:user-id or gh:user-id): xxxxxxxxxxx
So imagine that you’re the IT administrator for a new, 100-bed hospital that’s under construction, intended to serve a suburban community of 5,000 people. Call it “Metaphorical General Hospital” (MGH). Your job is to design a flexible data centre for this facility. You’ve decided to start with MAAS as your tool of choice, and for this planning exercise, you’ll use VMs in a VM host. You’re trying to get to this setup:
First, there’s some planning work do to.
You’ll need to start with a little network thinking (and design). Talking through requirements with the staff, you come up with a random list of functions:
| Charts | Provider orders | Provider documentation |
| Pharmacy | Narcotics control | Insurance collections |
| Housekeeping | Nursing orders | Med reconciliation |
| Timeclock | Patient collections | Med/surgical supplies |
| Office supplies | Patient registration | Insurance reconciliation |
| Payroll | Medication admin | Continuing education |
| Food service | Instrumentation | Information technology |
You can handle this lowest level with individual machines. With MAAS, you’ll be able to modify how many machines are performing which functions, somewhat on-the-fly, but let’s assume that you start by creating (at least) one VM for each function. Since you can reassign machines at will, you aren’t going to name them for their functions; instead, you’re just going to use the MAC address of each machine to uniquely identify it.
Try it!
Assuming you’ve installed libvirt↗ on the machine where you’ll be running MAAS, you can create virtual machines like this:
Open the Virtual Machine Manager application. You’ll see a screen that looks something like this:
Click on “New Virtual Machine,” which brings you to a corresponding dialog:
Select the “Network Boot (PXE)” option and click the “Forward” button:
Choose the “Generic…” operating system by typing the first letters of “Generic” in the text box and selecting the relevant choice when it becomes available, then go Forward:
For CPU and memory, you can usually accept the defaults:
The storage values have a noticeable effect on local disk usage, so note that, generally, a VM only requires about 5.0 GiB, given an example exercise like this:
In the next screen, you’ll have the chance to set a name; here, we’ve used a pseudo-MAC address, although you can name the machine whatever you want (and then return later to set the name to match the MAC address, if desired):
Selecting “Finish” will create the virtual machine and attempt to boot it – which will fail, since no device currently knows about this VM (and hence can’t boot it). Not to worry; you’re not done yet:
Select the “information” button (blue circle, white lowercase “i”) to switch to the VM configuration screens, then select the “Boot Options” choice from the left-hand menu:
Turn off the “IDE” item under “Boot device order:”
When you select “Apply,” a dialog will pop up to remind you that you need to restart this VM for changes to take effect:
Switch to the “NIC…” option and set the “Network source” and “Device model” as shown, then select “Apply” and respond to the dialog:
You’ll next select the drop-down arrow next to the “on/off” menu bar option and select “Force reset,” then answer the prompt in the affirmative:
You now have a VM that you can add to MAAS. If you want more than one, you can simply right-click on the one you’ve just created and select “Clone:”
NOTE: Pro Tip: Cloned VMs tend to use considerably less host disk space than newly-created ones.
Another VM will instantiate, using the name of the cloned VM with an added “-clone” suffix:
You can create VMs as desired, remembering to mind your overall disk usage on your host system.
Let’s assume that once you’re done adding VMs, you have around 20 up and ready, all named after their assigned MAC address:
No need to create a lot of VMs for this example (unless you just want to do so).
Once you’ve created the necessary VMs, you’ll want to manually add machines to MAAS that correspond to your VMs.
Try it!
Creating a machine from a VM requires about a dozen pieces of information, most of which you can gather from the VM itself:
In the left column, you’re only required to enter a machine name and the machine’s MAC address:
Here, we’ve assigned a variant of the MAC address as the machine name. Note that the machine name cannot include colons (“:”), we’ve substituted dashes. In the right column, it’s necessary to choose the power type. When enlisting VMs, the correct power type is “Virsh,” as shown below:
For default configurations, the Virsh Address is “qemu+ssh://[your-login-id]@192.168.122.1/system;” replace “[your-login-id]” with your username or login ID on the machine where you’re hosting MAAS and the Virtual Machine Manager. Likewise, the password is your normal login password for the same host. Finally, you can retrieve the Virsh VM ID from the “Overview” screen of the VM itself:
As you add machines, they automatically commission:
When finished, the commissioned machines with be at the “Ready” state.
Assigning machines to specific functions is something you can do after you commission and deploy them. (Later on, we’ll discuss ways to load user apps and data onto the machines using the MAAS API.) Once you’ve got machines running apps, you want to keep up-to-date about which machine is doing what, when you’re looking at the machine list. You’ll want to assign tags to machines.
Try it!
Adding a tag to a machine is simple. Just decide which machine you want to tag:
You’ll want to click on the machine name (in this case, the MAC address), and then choose “Configuration” on the next screen that comes up. This will bring you to a screen from which you can edit some parameters about the machine:
Click on “Edit,” and then add a tag name to the “Tags” field. Tags are automatically remembered by MAAS, so the next time you want to enter the same tag, an auto-complete field will appear, as shown below:
Select “Save changes” to add the tag(s) to the machine. When you return to the machine list, you’ll note that the tag is now associated with that machine:
Tags can will help you keep up with which machine(s) are covering which functions as you apply your apps. You can search and filter by tags, and you can utilise tags from within the API, as well.
As you look at the list of functions you’ve created, and talk more with the staff, you discover that some of these functions fit together more closely than others. With some effort, you work out the following update to your network design:
| Provider services | ||
| Charts | Provider orders | Provider documentation |
| Nursing services | ||
| Nursing orders | Continuing education | |
| Nursing meds | ||
| Medication administration | Narcotics control | |
| Prescriber controls | ||
| Pharmacy | Narcotics control | Medication reconciliation |
| Staff compensation | ||
| Timeclock | Payroll | |
| Supplies & services | ||
| Medical and surgical supplies | Office and general supplies | |
| Business office | ||
| Patient registration | Insurance reconciliation | |
| Collections | ||
| Patient collections | Insurance collections | |
| Patient support | ||
| Housekeeping | Food service | |
| Staff support | ||
| Instrumentation | Information technology |
You’re aware that the number of machines you’ll need use for each of the individual functions with vary according to real-world events in the hospital. Still, you’d prefer to budget machines for these different functions, so that you know you can meet the needs of each. The easiest way to handle this? Creating resource pools and naming them after the (new) top-level headings in your outline. That way, you can reserve some number of machines for those functions, learning over time the right number of machines to allocate to each activity.
Try it!
Notice at the top of the machine list, there is a tab labelled, “Resource pools:”
In this example, there are already some resource pools defined to match the different functions above, except for one: Provider services. Click the “Resource pools” tab to go there:
To add the “Provider services” (ProServ) pool, click on “Add pool:”
Fill in the fields for “Name” (which is a required field, with no spaces), and for “Description.” In this case, we’ve filled them in with “ProServ” and “Provider services:”
Click on “Add pool” to add this resource pool to the list, then click on “Machines” to return to the machine list. Once there, it’s simple to add machines to a particular pool. In the column marked “POOL/NOTE,” you’ll see that your machines are in the “default” pool when created. If you click on “default” there, you’ll bring up a drop-down of already-created resource pools:
Just choose the one you want for this machine (in our example, ProServ) and you’re done:
Here’s a snippet of the updated machine list, with all machines added to the appropriate resource pool:
Resource pools are mostly for your use, helping you to budget servers within a given category. Untagged servers can be in a pool, so if you’ve got five servers in the “Prescriber controls” resource pool, you can tag them with “Pharmacy,” “Medication reconciliation,” etc., as you use them. It will also be obvious when you’re running low on servers for that pool, and need to either provision more or move some unused ones from another pool.
Another optional identifier for machines is the “Note” field. While it can be long, a portion of it shows up on the machine list, which makes it useful for adding special identifiers or groupings. In this example, we’ve added a vague identifier which might help an IT admin remember server locations or access rights.
Try it!
You can edit notes by clicking on a machine name in the machine list, switching to the “Configuration” tab, and selecting the “Edit” button. These choices will bring you to a screen like this one:
From here, you can add free-form text into the “Note” field:
When you save the changes and return to the machine list, you’ll notice that the NOTE field for that machine now contains your changes:
Looking over your design, you notice that some of these resource pools must have their network traffic “fire-walled” from others – for example, Provider services and Nursing services shouldn’t be readily visible to Staff compensation or Food service. Likewise, the relevant monitoring agencies require that facilities manage medications as a separate activity. The traditional way to separate these networks (other than creating entirely separate networks) would be a VLAN. Luckily, MAAS supports multiple VLANS. Adding one higher level to your design, you find yourself with this updated network topology:
| Caregiver services | |
| Provider services | Nursing services |
| Medication management | |
| Nursing meds | Prescriber controls |
| Accounts payable | |
| Staff compensation | Supplies & services |
| Accounts receivable | |
| Business office | Collections |
| Patient support | |
| Housekeeping | Food service |
| Staff support | |
| Instrumentation | Information technology |
Each of these higher-level groupings is ideal for a VLAN, so you create six of them, one for each division:
Try it!
Adding a functional VLAN requires some additional (common) networking aspects, which we’ll cover later. In the meantime, though, here’s the short version of adding and naming the VLAN itself.
From anywhere on the MAAS page, select “Subnets” from the top menu-bar, which brings you to this screen:
Using the “Add” drop-down, select “VLAN:”
You’ll arrive at this screen, which allows you to specify the VLAN:
Enter the Name and ID of the VLAN, and select the fabric to enclose it (in this case, the “default” fabric):
When you’re satisfied with your choices, select “Add VLAN” to complete the operation.
Ignoring the networking aspects (for now), these VLANs should help isolate major functions and provide a level of data integrity and access control for your new hospital network.
Considering your network design so far, you notice that some of the VLANs need to be able to communicate with each other some of the time. In fact, you decide on three pairs of VLANs to cover this new networking situation:
| Patient management | |
| Caregiver services | Medication management |
| Accounting | |
| Accounts payable | Accounts receivable |
| Facilities | |
| Patient support | Staff support |
You want to incorporate these highest-level groupings into your network, but how? MAAS provides the answer with fabrics. A fabric is a set of interconnected VLANs that can communicate, so you simply create three fabrics, each covering one of these top-level categories.
Try it!
You can add a fabric by selecting the “Subnets” tab, clicking on the “Add” drop-down, and choosing “Fabric:”
You’ll see the “Add fabric” dialog appear. Enter the desired fabric name and click “Add fabric:”
Here you’ll notice three new fabrics, one for each of the top-level groupings in your example network design:
Next, you’ll want to assign your VLANs to this fabric. Begin by clicking on any VLAN you want to move, which will bring you to a summary screen for that VLAN:
You can click “Edit” and choose the desired fabric from the drop-down list:
Finally, click “Save summary” to move this VLAN to the desired fabric. The end result of assigning our example VLANs to the three fabrics is shown below.
