Machines (snap/2.7/CLI)

Machines are the heart of MAAS. They are the backbone of your data centre application(s), providing the functions that are relevant to your customers. MAAS manages their transit through a life-cycle, from adding and enlistment, through commissioning, allocation, and deployment, finally being released back to the pool, or retired altogether. You can move them around, create redundant versions (even in other geographies you can access), and basically rearrange them to the extent that your network allows.

Three questions you may have:

  1. How are the machine states and actions related?
  2. How can I view the machine list?
  3. How can I view machine details?

For example, in the illustration below, you see a typical small hospital data centre, including servers ready and allocated for functions like Pharmacy, Orders, Charts, and so on:

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

These example machines would typically be duplicated in several different geographies, with a quick way to switch to a redundant node, should anything go wrong (e.g., high availability). We used the word node there because, In the network language of MAAS, machines are one of several different types of nodes. A node is simply a network-connected object or, more specifically, an object that can independently communicate on a network. MAAS nodes include controllers, network devices, and of course, machines.

Looking back at the example above, you can see that there are several columns in the machine list:

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

These particular columns list eight details for each machine:

  1. FQDN | MAC: The fully qualified domain name or the MAC address of the machine.
  2. Power: ‘On’, ‘Off’ or ‘Error’ to highlight an error state.
  3. Status: The current status of the machine, such as ‘Ready’, ‘Commissioning’ or ‘Failed testing’.
  4. Owner: The MAAS account responsible for the machine.
  5. Tags: Any tags assigned to a machine; these tags not only help identify how the machine is being used, they can also be used to modify kernel parameters as the machine is being (re-)deployed.
  6. Pool: The resource pool to which this machine is assigned; these help to reserve machines for specific functions or groups of functions.
  7. Note: Any notes you’ve elected to assign to this machine.
  8. Zone: The availabilty zone in which this machine is placed.

You can change the visible columns by changing the way you execute the relevant CLI command; for example, this listing can be generated with the following command:

maas $PROFILE machines read | jq -r '(["HOSTNAME","POWER","STATUS",
"OWNER", "TAGS", "POOL", "NOTE","ZONE"] | (., map(length*"-"))),
(.[] | [.hostname, .power_state, .status_name, .owner // "-", 
.tag_names[0] // "-", .pool.name, .note, .zone.name]) | @tsv' | column -t

You could easily produce a different set of columns by using this command, for example:

maas $PROFILE machines read | jq -r '(["HOSTNAME","SYSID","POWER","STATUS",
"OWNER", "TAGS", "POOL", "VLAN","FABRIC","SUBNET"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id, .power_state, .status_name, .owner // "-", 
.tag_names[0] // "-", .pool.name,
.boot_interface.vlan.name, .boot_interface.vlan.fabric,
.boot_interface.links[0].subnet.name]) | @tsv' | column -t

producing a listing something like this:

HOSTNAME           SYSID   POWER  STATUS     OWNER  TAGS     POOL     VLAN      FABRIC   SUBNET
--------           -----   -----  ------     -----  ----     ----     ----      ------   ------
52-54-00-15-36-f2  hfqgmw  off    Allocated  admin  virtual  default  untagged  default  192.168.123.0/24
52-54-00-17-64-c8  bdn3qn  off    Allocated  admin  virtual  default
52-54-00-1d-47-95  8d8bxk  off    Allocated  admin  virtual  default  untagged  default  192.168.123.0/24
52-54-00-1e-06-41  wennwm  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-1e-a5-7e  ekf7ae  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-b7-1e  y47pka  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-c4-40  cbgkxg  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-ee-17  ap3ttw  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2f-6d-3c  c3aybg  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-4a-2a-30  4a33wk  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-4e-60-b2  a488pw  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-52-93-10  hhnq8x  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-5d-b5-a1  hxy44m  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-60-1e-6f  bk7mck  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-60-8d-4b  typh3r  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-62-22-e3  774dk8  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-65-2e-20  t8me3x  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-6a-ac-23  tybxhr  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-6f-b4-af  bs7ye8  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-71-0c-53  hp7pp4  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-77-4e-53  nq36ky  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-98-42-ef  gagbqp  off    Broken     -      -        default  untagged  default
52-54-00-9b-e4-9a  apkp4n  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-9c-51-00  rxfkqt  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24

Machine life-cycle

One of the most important things to understand about machines is their life-cycle. Machines can be discovered or added, commissioned by MAAS, acquired, deployed, released, marked broken, tested, put into rescue mode, and deleted. In addition, pools, zones, and tags can be set for machines.

All of these states and actions represent the possible life-cycle of a machine. This life-cycle isn’t strict or linear – it depends on how you use a machine – but it’s useful to give a general overview of how machines tend to change states. In the discussion that follows, states and actions are shown in bold type.

  1. Machines start as servers in your environment, attached to a network or subnet MAAS can manage.

  2. If machines are configured to netboot, MAAS can discover them and present them to you for possible commissioning, changing their state to New.

  3. When you select a machine that is marked New, you can choose to commission it. If you add a machine manually, it is automatically commissioned.

  4. Machines that have successfully commissioned can be acquired and deployed. Machines that don’t successfully commission can be marked broken (and later recovered when the issues are resolved).

  5. Resolving problems with machines usually involve testing the machine.

  6. Once you’ve deployed a machine, and you’re done with it, you can release it.

  7. You can place a machine in rescue mode, which allows you to SSH to a machine to make configuration changes or do other maintenance. Once you’re done, you can exit rescue mode*.

  8. Any time a machine is on, you have the option to select it and power off that machine.

  9. You can abort any operation that’s in progress.

  10. You also have the option to set tags, availability zone, or resource pool at various stages along the way.

Since these actions are not necessarily sequential, and the available actions change as the machine state changes, it’s not very useful to make a state diagram or flowchart. Instead, consider the following table:

Action/State New Ready Acquired Deployed Locked Rescue Broken
Commission X X X
Acquire X
Deploy X X
Release X X
Power on X X
Power off
Test X X X X X
Rescue mode X X X X X
Exit rescue X
Mark broken X X
Mark fixed X
Lock X
Unlock X
Tag X X X X X X
Set zone X X X X X X
Set…pool X X X X X X
Delete X X X X X X

When a machine is in the state listed in a column, it is possible to take the row actions marked with an “X.” You access these actions from the “Take action” menu in the upper right corner of the machine listing. Note that some actions, such as “Mark broken” or “Lock,” may be hidden when they are not available.

View the machine list

You can view a basic machine list with a command such as this one:

maas $PROFILE machines read | jq -r '(["HOSTNAME","SYSID","POWER","STATUS",
"OWNER", "TAGS", "POOL", "VLAN","FABRIC","SUBNET"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id, .power_state, .status_name, .owner // "-", 
.tag_names[0] // "-", .pool.name,
.boot_interface.vlan.name, .boot_interface.vlan.fabric,
.boot_interface.links[0].subnet.name]) | @tsv' | column -t \
| sort -k 1

This action will display a table similar to this one, listing all the machines that are currently visible to your MAAS installation:

HOSTNAME           SYSID   POWER  STATUS     OWNER  TAGS     POOL     VLAN      FABRIC   SUBNET
--------           -----   -----  ------     -----  ----     ----     ----      ------   ------
52-54-00-15-36-f2  hfqgmw  off    Allocated  admin  virtual  default  untagged  default  192.168.123.0/24
52-54-00-17-64-c8  bdn3qn  off    Allocated  admin  virtual  default
52-54-00-1d-47-95  8d8bxk  off    Allocated  admin  virtual  default  untagged  default  192.168.123.0/24
52-54-00-1e-06-41  wennwm  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-1e-a5-7e  ekf7ae  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-b7-1e  y47pka  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-c4-40  cbgkxg  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-ee-17  ap3ttw  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2f-6d-3c  c3aybg  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-4a-2a-30  4a33wk  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-4e-60-b2  a488pw  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-52-93-10  hhnq8x  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-5d-b5-a1  hxy44m  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-60-1e-6f  bk7mck  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-60-8d-4b  typh3r  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-62-22-e3  774dk8  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-65-2e-20  t8me3x  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-6a-ac-23  tybxhr  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-6f-b4-af  bs7ye8  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-71-0c-53  hp7pp4  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-77-4e-53  nq36ky  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-98-42-ef  gagbqp  off    Broken     -      -        default  untagged  default
52-54-00-9b-e4-9a  apkp4n  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-9c-51-00  rxfkqt  off    Ready      -      virtual  default  untagged  default  192.168.123.0/24

During commissioning and deployment, you can re-read the table to reflect the changing state of each machine:

HOSTNAME           SYSID   POWER  STATUS         OWNER  TAGS     POOL     VLAN      FABRIC   SUBNET
--------           -----   -----  ------         -----  ----     ----     ----      ------   ------
52-54-00-15-36-f2  hfqgmw  off    Allocated      admin  virtual  default  untagged  default  192.168.123.0/24
52-54-00-17-64-c8  bdn3qn  off    Allocated      admin  virtual  default
52-54-00-1d-47-95  8d8bxk  off    Allocated      admin  virtual  default  untagged  default  192.168.123.0/24
52-54-00-1e-06-41  wennwm  off    Commissioning  -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-1e-a5-7e  ekf7ae  off    Commissioning  -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-b7-1e  y47pka  off    Deployed       -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-c4-40  cbgkxg  off    Deploying      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2e-ee-17  ap3ttw  off    Deploying      -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-2f-6d-3c  c3aybg  off    Ready          -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-4a-2a-30  4a33wk  off    Ready          -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-4e-60-b2  a488pw  off    Ready          -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-52-93-10  hhnq8x  off    Ready          -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-5d-b5-a1  hxy44m  off    Ready          -      virtual  default  untagged  default  192.168.123.0/24
52-54-00-60-1e-6f  bk7mck  off    Ready          -      virtual  default  untagged  default  192.168.123.0/24

You can also add machines; at the command line, enter the following information:

maas $PROFILE machines create \
> architecture=$ARCH \
> max_addresses=$MAC_ADDRESS \
> power_type=$POWER_TYPE \
> power_parameters_power_id=$POWER_ID \
> power_parameters_power_address=$POWER_ADDRESS \
> power_parameters_power_pass=$POWER_PASSWORD

When you enter the command (substituting the $… parameters for your own particulars), the screen will pause for a moment, and then return a stream of JSON relating to the added machine.

Here’s an example with a local laptop MAAS install, using KVMs as virtual machines:

stormrider@wintermute:~$ maas admin machines create \
> architecture=amd64 \
> max_addresses=52:54:00:6f:b4:af \
> power_type=virsh \
> power_parameters_power_id=50f6cca2-5d89-43b9-941c-90c9fcd7c156 \
> power_parameters_power_address=qemu+ssh://stormrider@192.168.123.1/system \
> power_parameters_power_pass=xxxxxxx

The variable fields in the machines create command (the $… items) are as follows, in this example:

> architecture=$ARCH \
> mac_addresses=$MAC_ADDRESS \
> power_type=$POWER_TYPE \
> power_parameters_power_id=$POWER_ID \
> power_parameters_power_address=$POWER_ADDRESS \
> power_parameters_power_pass=$POWER_PASSWORD

$ARCH: This field refers to the architecture of the machine being added, amd64 in the local laptop example.

$MAC_ADDRESS: This is the MAC address of the boot-enabled NIC for the machine being added. Note that the MAC address entered here must use a colon (":") separator, although some MAC addresses are written with dash ("-") separators.

$POWER_TYPE: You must select the power type supported by the machine you are adding, and fill in additional required fields that appear. See Power management for details on the available power types and the relevant parameters for each type. In this example, we’ve used a “virsh” power type (a libvirt KVM), but your choice will depend on your hardware.

$POWER_ID: This is generally the UUID of the machine being added.

$POWER_ADDRESS/$POWER_PASSWORD: In the case of a KVM, these are the only parameters that need to be entered. See Power types in the API reference for details on the available power types and the relevant parameters for each type.

You can commission, acquire, or deploy a machine these commands:

maas $PROFILE machine commission $SYSTEM_ID

maas $PROFILE machines allocate system_id=$SYSTEM_ID

maas $PROFILE machine deploy $SYSTEM_ID

The $SYSTEM_ID is the text in the “SYSID” field in the machine listing above. These commands are described in more detail later on in this section of articles.

View machine details

Enter a command similar to the following to get a detailed view of a machine’s status and configuration:

maas $PROFILE machine read $SYSTEM_ID | \
jq -r '([.hostname, .status_name, "Power", .power_state]),
[(120*"-")],
(["OVERVIEW", "|", "CPU", "", "", .architecture, "|", "MEMORY", "|", "STORAGE"]),
([.status_name, "|", "\(.cpu_count) core(s)", "", "", "", "|", "\(.memory) MB", "|",
"\(.blockdevice_set[].partitions[].size/(1024*1024*1024)) GiB"]),
(["", "", "|", .hardware_info.cpu_model, "|","","|"]), ([(120*"-")]),
(["Owner", "", "Domain", "", "Zone", "", "Resource pool", "", "Power type", "", "Tags"]),
([.owner // "-", "", .domain.name, "", .zone.name, "", .pool.name,
"", "", .power_type, "", "", .tag_names[0]]) | @tsv'

The above command produces output similar to this:

52-54-00-15-36-f2	Allocated	Power: off
---------------------------------------------------------------------------------------
OVERVIEW        | CPU                    amd64/generic  | MEMORY   | STORAGE
Allocated       | 1 core(s)                             | 1024 MB  | 4.9921875 GiB
                | Intel Core Processor (Skylake, IBRS)  |          |
---------------------------------------------------------------------------------------
Owner        Domain       Zone        Resource pool        Power type        Tags
admin        maas         default     default              virsh             virtual

You can customize this command at length by examining the entire JSON output stream, like this:

maas $PROFILE machine read $SYSTEM_ID | jq .

Summary

This article has offered you a cursory glimpse into machines and how they are configured and managed in MAAS. Read on through this section of the documentation to learn more.