Try out the MAAS CLI

Hopefully, you’ve had a chance to get started with MAAS; if not, you may want to back up and start there, since this tutorial picks up where that one left off.

A real-world example might help you learn more about MAAS. Luckily, it doesn’t have to be comprehensive – just coherent and plausible. Just to give you a sneak peek, we’ll be building a hospital data centre that ultimately looks something like this:

FQDN               POWER  STATUS     OWNER  TAGS     POOL       NOTE     ZONE
----               -----  ------     -----  ----     ----       ----     ----
52-54-00-15-36-f2  off    Ready      -      Orders   Prescrbr   @md-all  Medications
52-54-00-17-64-c8  off    Ready      -      HRMgmt   StaffComp  @tmclck  Payroll
52-54-00-1d-47-95  off    Ready      -      MedSupp  SuppServ   @storag  Inventory
52-54-00-1e-06-41  off    Ready      -      PatPrtl  BusOfc     @bzstns  BizOffice
52-54-00-1e-a5-7e  off    Ready      -      Pharm    Prescrbr   @rxonly  Pharmacy
52-54-00-2e-b7-1e  off    Allocated  admin  NursOrd  NurServ    @nstns   Nursing
52-54-00-2e-c4-40  off    Allocated  admin  MedAdmn  NurServ    @rxonly  Nursing
52-54-00-2e-ee-17  off    Deployed   admin  Charts   ProServ    @md-all  Physician

We’ll be using the command line interface (CLI) for most of this example, but you can do the same things with the UI – as we’ll demonstrate near the end. Also, we’ll be collapsing a lot of peripheral learning opportunities into little detail sections, like this one:

Using `jq` to make pretty listings You can generate a list similar to this for your machines with the `jq` command:
maas admin machines read | jq -r '(["FQDN","POWER","STATUS",
"OWNER", "TAGS", "POOL", "NOTE", "ZONE"] | (., map(length*"-"))),
(.[] | [.hostname, .power_state, .status_name, .owner // "-", 
.tag_names[0] // "-", .pool.name, .description // "-", .zone.name]) | @tsv' | column -t

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.

Machines

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 (the “cattle, not pets” cloud model of server naming).

Creating some sample VMs

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:”

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, you have around 20 machines 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).

Manually adding machines

Once you’ve created the necessary VMs, you’ll want to manually add machines to MAAS that correspond to your VMs.

FQDN               POWER  STATUS  OWNER  TAGS     POOL     NOTE  ZONE
----               -----  ------  -----  ----     ----     ----  ----
52-54-00-15-36-f2  off    Ready   -      virtual  default  -     default
52-54-00-17-64-c8  off    Ready   -      virtual  default  -     default
52-54-00-1d-47-95  off    Ready   -      virtual  default  -     default
52-54-00-1e-06-41  off    Ready   -      virtual  default  -     default
52-54-00-1e-a5-7e  off    Ready   -      virtual  default  -     default
52-54-00-2e-b7-1e  off    Ready   -      virtual  default  -     default
52-54-00-2e-c4-40  off    Ready   -      virtual  default  -     default
52-54-00-2e-eke-17  off    Ready   -      virtual  default  -     default
52-54-00-2f-6d-3c  off    Ready   -      virtual  default  -     default
52-54-00-4a-2a-30  off    Ready   -      virtual  default  -     default
52-54-00-4e-60-b2  off    Ready   -      virtual  default  -     default
52-54-00-52-93-10  off    Ready   -      virtual  default  -     default
52-54-00-5d-b5-a1  off    Ready   -      virtual  default  -     default
52-54-00-60-1e-6f  off    Ready   -      virtual  default  -     default
52-54-00-60-8d-4b  off    Ready   -      virtual  default  -     default
52-54-00-62-22-e3  off    Ready   -      virtual  default  -     default
52-54-00-65-2e-20  off    Ready   -      virtual  default  -     default
52-54-00-6a-ac-23  off    Ready   -      virtual  default  -     default
52-54-00-6f-b4-af  off    Ready   -      virtual  default  -     default
52-54-00-71-0c-53  off    Ready   -      virtual  default  -     default
52-54-00-77-4e-53  off    Ready   -      virtual  default  -     default
52-54-00-98-42-ef  off    Broken  -      -        default  -     default
52-54-00-9b-e4-9a  off    Ready   -      virtual  default  -     default
52-54-00-9c-51-00  off    Ready   -      virtual  default  -     default

Creating a machine from a VM requires six pieces of information:

  1. the machine architecture (e.g., amd64)
  2. the machine’s MAC address
  3. the power type (in this case, “virsh”)
  4. the power ID
  5. the power address (which also contains a username)
  6. the power password

Once you’ve collected this information, you’ll want to create a new KVM like this:

maas admin machines create \
architecture=amd64 hostname=52-54-00-15-36-f2 \ 
mac_addresses=52:54:00:15:36:f2 \
power_type=virsh power_parameters_power_id=f677a842-571c-4e65-adc9-11e2cf92d363 \
power_parameters_power_address=qemu+ssh://stormrider@192.168.123.1/system \
power_parameters_power_pass=xxxxxxxx

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. You can gather most of this information from the KVM itself:

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.

Tags

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, so you’ll want to assign tags to machines.

FQDN               POWER  STATUS  OWNER  TAGS     POOL     NOTE  ZONE
----               -----  ------  -----  ----     ----     ----  ----
52-54-00-15-36-f2  off    Ready   -      Orders   default  -     default
52-54-00-17-64-c8  off    Ready   -      HRMgmt   default  -     default
52-54-00-1d-47-95  off    Ready   -      MedSupp  default  -     default
52-54-00-1e-06-41  off    Ready   -      PatPrtl  default  -     default
52-54-00-1e-a5-7e  off    Ready   -      Pharm    default  -     default
52-54-00-2e-b7-1e  off    Ready   admin  NursOrd  default  -     default
52-54-00-2e-c4-40  off    Ready   admin  MedAdmn  default  -     default
52-54-00-2e-ee-17  off    Ready   admin  Charts   default  -     default

Adding a tag to a machine is simple. First, you must create the tag:

maas $PROFILE tags create name=$TAG_NAME comment='$TAG_COMMENT'

Next you add the tag to a machine with the following command:

maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID

If you need to find the $SYSTEM_ID of your machines, you can use this command:

maas admin machines read | jq -r '(["HOSTNAME","SYSID"]
| (., map(length*"-"))),
(.[] | [.hostname, .system_id]) | @tsv' | column -t

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.

Resource pools

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.

Just like tags, you must first create a resource pool before assigning a machine to it.
Here’s an example that demonstrates how to create a new resource pool named “myresource” in a single command; note that the description field is optional, but often very helpful:

maas $PROFILE resource-pools create name=myresource description="A new resource pool."

Once you’ve created the pool you want, you can add a machine that pool with the following command:

maas $PROFILE machine update $SYSTEM_ID pool=$POOL_NAME

Here’s a snippet of your updated machine list, with all machines added to the appropriate resource pool:

FQDN               POWER  STATUS  OWNER  TAGS     POOL       NOTE  ZONE
----               -----  ------  -----  ----     ----       ----  ----
52-54-00-15-36-f2  off    Ready   -      Orders   Prescrbr   -     default
52-54-00-17-64-c8  off    Ready   -      HRMgmt   StaffComp  -     default
52-54-00-1d-47-95  off    Ready   -      MedSupp  SuppServ   -     default
52-54-00-1e-06-41  off    Ready   -      PatPrtl  BusOfc     -     default
52-54-00-1e-a5-7e  off    Ready   -      Pharm    Prescrbr   -     default
52-54-00-2e-b7-1e  off    Ready   admin  NursOrd  NurServ    -     default
52-54-00-2e-c4-40  off    Ready   admin  MedAdmn  NurServ    -     default
52-54-00-2e-ee-17  off    Ready   admin  Charts   ProServ    -     default

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.

Notes

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.

FQDN               POWER  STATUS  OWNER  TAGS     POOL       NOTE     ZONE
----               -----  ------  -----  ----     ----       ----     ----
52-54-00-15-36-f2  off    Ready   -      Orders   Prescrbr   @md-all  default
52-54-00-17-64-c8  off    Ready   -      HRMgmt   StaffComp  @tmclck  default
52-54-00-1d-47-95  off    Ready   -      MedSupp  SuppServ   @storag  default
52-54-00-1e-06-41  off    Ready   -      PatPrtl  BusOfc     @bzstns  default
52-54-00-1e-a5-7e  off    Ready   -      Pharm    Prescrbr   @rxonly  default
52-54-00-2e-b7-1e  off    Ready   admin  NursOrd  NurServ    @nstns   default
52-54-00-2e-c4-40  off    Ready   admin  MedAdmn  NurServ    @rxonly  default
52-54-00-2e-ee-17  off    Ready   admin  Charts   ProServ    @md-all  default

To add a note to a machine, you’ll first need to determine its system ID (see above). Once you have that, you can add or change a note like this:

maas $PROFILE machine update $SYSTEM_ID description="note"

It helps very much to keep your notes short, since only a few characters are visible on the machine list.

VLANs

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:

FABRIC    VLAN                   DHCP
------    ----                   ----
fabric-0  Accounts_Receivable    false
fabric-0  Staff_Support          false
fabric-0  Patient_Support        false
fabric-0  Accounts_Payable       false
fabric-0  Medication_Management  false
fabric-0  Caregiver_Services     false
fabric-0  untagged               false
`jq` magic

You can generate this list with the command:

maas admin vlans read $FABRIC_ID | jq -r '(["FABRIC","VLAN","DHCP"] | (., map(length*"-"))), (.[] | [.fabric, .name, .dhcp_on]) | @tsv' | column -t

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.

To create additional VLANs, choose the fabric where you want them to be added, and enter the following command, once for each new VLAN:

maas admin vlans create $FABRIC_ID name=$VLAN_NAME vid=$VLAN_ID

For example, to create the “Caregiver Services” VLAN with VID 100 on fabric 0, enter the following command:

maas admin vlans create 0 name="Caregiver_Services" vid=100

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.

Fabrics

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.

This is also a good opportunity to try out the MAAS UI. In your browser, go to the MAAS URL that you generated when you installed MAAS. Login as your defiend user, and select the “Subnets” tab. You can add a fabric by 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.

@billwear, I’m sure you are aware, but just a heads up that the UI and CLI snap pages all refer to installing with apt.

Issue with markdown formatting of hyperlink

Location in document - Importing images section

What should fix it up

Looks like the markdown formatting for the hyperlink to the main jq GitHub repository is broken. Changing the markdown formatting of the hyperlink should help fix it up:

[jq](https://stedolan.github.io/jq/)

If you use the above markdown formatting, the hyperlink will look like this: jq

thanks, @nuccitheboss! nice catch. sometimes those slip through.

1 Like