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:
- How are the machine states and actions related?
- How can I view the machine list?
- 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:
- FQDN | MAC: The fully qualified domain name or the MAC address of the machine.
- Power: ‘On’, ‘Off’ or ‘Error’ to highlight an error state.
- Status: The current status of the machine, such as ‘Ready’, ‘Commissioning’ or ‘Failed testing’.
- Owner: The MAAS account responsible for the machine.
- 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.
- Pool: The resource pool to which this machine is assigned; these help to reserve machines for specific functions or groups of functions.
- Note: Any notes you’ve elected to assign to this machine.
- 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.
-
Machines start as servers in your environment, attached to a network or subnet MAAS can manage.
-
If machines are configured to netboot, MAAS can discover them and present them to you for possible commissioning, changing their state to New.
-
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.
-
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).
-
Resolving problems with machines usually involve testing the machine.
-
Once you’ve deployed a machine, and you’re done with it, you can release it.
-
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*.
-
Any time a machine is on, you have the option to select it and power off that machine.
-
You can abort any operation that’s in progress.
-
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.