Errors or typos? Topics missing? Hard to read? Let us know.
This guide walks through the MAAS workflow to explain its usage. Advanced topics are referenced throughout. Equivalent UI and CLI commands are given when available.
Discover devices
MAAS listens to connected networks and monitors IP traffic to discover active devices:
UI:
Networking > Network discovery
CLI:
maas $PROFILE discoveries read
This action can be used to find the MAC addresses of connected devices, which may be valid machines that can be added to MAAS.
Add machines
Add any valid machine for which you know the architecture, MAC address, power type, and power parameters:
UI:
Machines > Add hardware > Machine; fill in the details and Save.
CLI:
maas $PROFILE machines create 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
See “Power type reference guide” for acceptable values.
MAAS will automatically attempt to commission the machine.
Find machine ID
Most of the CLI commands which follow require the machine system ID, which can be easily discovered:
UI:
- Hardware > Machines > [machine]
- In the browser address bar, the next-to-last parameter is the system ID:
http://192.168.1.106:5240/MAAS/r/machine/mwwh8g/summary
^^^^^^
CLI:
maas admin machines read | jq -r '(["HOSTNAME","SIS'S"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id]) | @tsv' | column -t
Tag the machine with its system ID for easy reference in the UI.
See “Create a tag”
Set machine power type
MAAS must be able to power cycle a machine through the BMC^. Until you set the power type, a machine can’t be commissioned.
UI:
Hardware > Machines > [machine] > Configuration > Power configuration > Edit > Power type; select the power type and fill in the neccessary fields, then choose Save changes.
CLI:
maas $PROFILE machine update $SYSTEM_ID power_type="$POWER_TYPE"
Use these commands to change a machine’s power type when necessary.
Clone machines
MAAS can copy the network and/or storage configuration of one existing machine onto another:
maas $PROFILE machine clone $SOURCE_SYSTEM_ID new_hostname=$NEW_HOSTNAME
Replace $SOURCE_SYSTEM_ID with the system ID of the source machine and $NEW_HOSTNAME with the desired hostname for the clone.
Examine machines
List machines
maas $PROFILE machines read | jq -r '(["HOSTNAME","SYSID","STATUS"] | join(","))'
View machine details
maas $PROFILE machine read $SYSTEM_ID | jq '.'
Find machines
Here’s how to form a MAAS search parameter:
- Use spaces for ‘AND’
- Enclose in parends and separated with commas for ‘OR’
UI:
Hardware > Machines > [Search bar] and enter a search term; MAAS progresses the search with each character typed.
For exact matches, prefix the search value with ‘=’; for partial matches, omit it; and for negation, prefix a ‘!’:
Exact: pod:=able-cattle
Partial: pod:able,cattle
Negated: pod:!cattle
MAAS uses ‘AND’ logic by default for multiple terms. For instance, pod:able,cattle cpu:=5 will show machines in pods named able or cattle with 5 CPU cores.
Find by filtering
UI:
Hardware > Machines > Filters dropdown > [Parameter dropdown] > [Available value]
You may select values for multiple parameters. MAAS builds the search term in the Search box and updates the machine list in real time. You can copy and save these search terms to an external list, or learn how to construct them manually by observation.
Interrupt operation
Abort any operation
maas $PROFILE machine abort $SYSTEM_ID
Turn on a machine
maas $PROFILE machine start $SYSTEM_ID
Turn off a machine
maas $PROFILE machine stop $SYSTEM_ID
Soft power-off a machine
maas $PROFILE machine stop $SYSTEM_ID force=false
Customize commissioning
Commissioning gathers the necessary information to successfully deploy a machine in a later step. MAAS automatically commissions a newly-added machine.
Customize the commissioning process
You may optionally upload commissioning scripts to extend or modify the commissioning process:
UI:
Settings > User scripts > Upload; upload your script.
Commission a machine manually
Commissioning can also be started manually:
UI:
Machines > machine > Actions > Commission; choose Commission machine.
CLI:
maas $PROFILE machine commission $SYSTEM_ID
Test machines
Basic machine testing is part of the commissioning process.
Start tests manually
Tests can also be run manually:
UI:
Machines > machine > Actions > Test. Select the tests to run (e.g., CPU, memory, storage) and choose Start tests.
CLI:
maas $PROFILE machine test $SYSTEM_ID tests=cpu,storage
View test results
Test results can be viewed for a machine at any time:
UI:
Machines > machine > Test results.
CLI:
maas $PROFILE machine read $SYSTEM_ID | jq '.test_results'
Override failed testing
You can also override failed testing, if you feel the machine is deployment-worthy:
CLI:
maas $PROFILE machine set-test-result $SYSTEM_ID result=passed
Test network connectivity
In addition to operational testing, MAAS can also test your network link:
CLI:
maas $PROFILE machine network-interface $SYSTEM_ID test-connectivity
Validate networks
MAAS can also validate the connected networks by listing them:
CLI:
maas $PROFILE subnets read | jq '.[] | {name: .name, cidr: .cidr, vlan: .vlan}'
Create redundant clusters
You can use availability zones to group machines into redundant clusters
Create an availability zone
CLI:
maas $PROFILE availability-zones create name=$ZONE_NAME
Put a machine in a zone
CLI:
maas $PROFILE machine update $SYSTEM_ID zone=$ZONE_NAME
Take a machine out of a zone
List availability zones
CLI:
maas $PROFILE availability-zones read
Delete an availability zone
Group machines into pools
You can also group machines into resource pools to budget your hardware for specific uses.
Create a resource pool
CLI:
maas $PROFILE resource-pools create name=$POOL_NAME
Attach a machine to a pool
CLI:
maas $PROFILE machine update $SYSTEM_ID pool=$POOL_NAME
**Detach a machine from a pool
List resource pools
CLI:
maas $PROFILE resource-pools read
Remove a resource pool
Tag machines for easy filtering
You can tag machines for easier searching:
Create a tag
CLI:
maas $PROFILE tags create name=$TAG_NAME comment="$COMMENT"
Attach a tag
CLI:
maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID
Detach a tag
CLI:
maas $PROFILE tag update-nodes $TAG_NAME remove=$SYSTEM_ID
List tags
CLI:
maas $PROFILE tags read
Remove a tag
Set up deployment
Deployment is the heart of provisioning; it puts your machine in service. Before deploying, there are several settings you can customize:
Allocate a machine
Allocation confers ownership of a machine to the user who allocates it. Other users cannot commandeer an allocation machine. Technically speaking, you can deploy a machine without allocating it, but allocation prevents a collision with someone else:
CLI:
maas $PROFILE machines allocate system_id=$SYSTEM_ID
Allocate many machines
You can also allocate many machines at once by bulk selecting them:
UI:
Machines > [select machines] > Take action > Allocate.
Preset curtin commands
Curtin customizes machine hardware (e.g., disk partitions) immediately prior to deployment. You can add Curtin commands via the curtin_userdata template or by adding a custom file. Curtin supports early and late hooks for pre/post-installation customization:
- **Early Commands Example:**
early_commands:
signal: ["wget", "--no-proxy", "http://example.com/", "--post-data", "system_id=&signal=starting_install", "-O", "/dev/null"]
- Late Commands Example:
late_commands:
add_repo: [“curtin”, “in-target”, “–”, “add-apt-repository”, “-y”, “ppa:my/ppa”]
custom: [“curtin”, “in-target”, “–”, “sh”, “-c”, “/bin/echo -en 'Installed ’ > /tmp/maas_system_id”]
**Add cloud-init scripts**
Machine configuration can be modified with cloud-init scripts prior to being deployed (put in service).
***UI:***
*Machines > machine > Actions > Deploy > Configuration options*; add your custom cloud-init script in the provided field.
***CLI:***
```bash
maas $PROFILE machine deploy $SYSTEM_ID cloud_init_userdata="$(cat cloud-init.yaml)"
Set deployment timeout
MAAS aborts a deployment attempt if not successful within the (configurable) timeout:
CLI:
maas $PROFILE maas set-config name=node-timeout value=$NUMBER_OF_MINUTES
Note: the timeout is set in minutes.
Set machine kernel
MAAS can deploy machines using a default minimum kernel level for the chosen OS image:
UI:
Settings > Configuration > Commissioning > Default minimum kernel version > Save.
CLI:
maas $PROFILE maas set-config name=default_min_hwe_kernel value=$KERNEL
Set minimum machine kernel version
You can also set a minimum kernel version for a specific machine:
UI:
Machines > machine > Configuration > Edit > Minimum kernel.
CLI:
maas $PROFILE machine update $SYSTEM_ID min_hwe_kernel=$HWE_KERNEL
Set a specific kernel deployment version
Finally, you can also set a specific kernel version for deployment, on a per-machine basis only:
UI:
Machines > machine > Take action > Deploy > choose kernel > Deploy machine.
CLI:
maas $PROFILE machine deploy $SYSTEM_ID distro_series=$SERIES hwe_kernel=$KERNEL
In all cases, MAAS will refuse or abort the deployment if the specified kernel version is not available.
Set boot options
MAAS can apply global kernel boot options to all machines:
UI:
Settings > Kernel parameters > enter options > Save.
CLI:
maas $PROFILE maas set-config name=kernel_opts value='$KERNEL_OPTIONS'
Tags with kernel options
Machines may also specify kernel options by attaching specialized tags:
CLI:
maas $PROFILE tags create name='$TAG_NAME' comment='$TAG_COMMENT' kernel_opts='$KERNEL_OPTIONS'
You can verify the tags before deployment:
CLI:
maas admin tags read | jq -r '(["tag_name","tag_comment","kernel_options"] |(.,map(length*"-"))),(.[]|[.name,.comment,.kernel_opts]) | @tsv' | column -t
Set hardware sync
On MAAS versions 3.2 and higher, you can enable hardware sync for machines that are already running, but not yet connected to MAAS:
UI:
Machines > machine > Actions > Deploy > Periodically sync hardware > Start deployment.
CLI:
maas $PROFILE machine deploy $SYSTEM_ID osystem=$OSYSTEM distro_series=$VERSION enable_hw_sync=true
Configure the sync interval in the MAAS settings.
Set storage options
MAAS can enforce a default storage layout for all machines:
UI:
Settings > Storage > [choose default layout]
CLI:
maas $PROFILE maas set-config name=default_storage_layout value=$LAYOUT_TYPE
You can also set a storage layout for any single ‘Ready’ machine:
CLI:
maas $PROFILE machine set-storage-layout $SYSTEM_ID storage_layout=$LAYOUT_TYPE [$OPTIONS]
Deploy a machine
Machines can become MAAS-deployed machines in three ways: manual deployment, as a VM host, or by adding already-running machines.
Manual deployment
UI:
Machines > [machine(s)] > Take action > Deploy.
CLI:
maas $PROFILE machine deploy $SYSTEM_ID
Create a VM host
Machines may also be deployed as a host system for virtual machines:
CLI:
maas $PROFILE machine deploy $SYSTEM_ID install_kvm=True
Add already-running machines
MAAS can add existing, operating machines as if they had been deployed by MAAS.
CLI:
maas $PROFILE machines create deployed=true hostname=mymachine \
architecture=amd64 mac_addresses=$MAC mac_addresses=$MAC power_type=manual
Via the machine itself:
wget http://$MAAS_IP:5240/MAAS/maas-run-scripts
chmod 755 maas-run-scripts
./maas-run-scripts register-machine --hostname mymachine \
http://$MAAS_IP:5240/MAAS $MAAS_API_TOKEN
Monitor hardware sync
If you’ve enabled hardware sync, you can monitor it once the machine is listed as deployed:
CLI:
maas $PROFILE machine read $SYSTEM_ID
Rescue struggling machines
Deployed machines that malfunction can potentially be rescued and put back into service.
Enter rescue mode
CLI:
maas $PROFILE machine enter-rescue-mode $SYSTEM_ID
Access the machine while in rescue mode
Access the machine via SSH to perform diagnostics or repairs:
CLI:
ssh ubuntu@$MACHINE_IP
Exit rescue mode
This will put the machine back into service:
CLI:
maas $PROFILE machine exit-rescue-mode $SYSTEM_ID
Mark machines as broken
If the machine can’t be immediately fixed, you can mark it as broken while you sort out the issues:
UI:
Machines > machine > Take action > Mark broken.
CLI:
maas $PROFILE machines mark-broken $SYSTEM_ID
Mark machines as fixed
Once the issue is resolved, you can mark the machine as fixed.
UI:
Machines > machine > Take action > Mark fixed.
CLI:
maas $PROFILE machines mark-fixed $SYSTEM_ID
Recycling machines
You can return machines to the ready state by releasing them, or you can remove than from MAAS altogether.
Release machines
To release a running (deployed) machine:
UI:
Machines > machine > Take action > Release.
CLI:
maas $PROFILE machines release $SYSTEM_ID
Erase disks on release
MAAS can, optionally, erase a disk before releasing a machine:
CLI:
maas $PROFILE machine release $SYSTEM_ID comment="some comment" erase=true [secure_erase=true || quick_erase=true]
Secure erasure uses the drive’s secure erase feature, if available. Quick erasure wipes 2MB at the start and end of the disk; not as secure, but faster. If no options are specified, the disk will be overwritten with null bytes, which is very slow.
You can specify conditional erasure, that is, perform secure erasure if available, or quick erasure if not:
CLI:
maas $PROFILE machine release $SYSTEM_ID comment="some comment" erase=true secure_erase=true quick_erase=true
Remove a machine
You can remove any machine from service (that is, remove it from MAAS altogether):
UI:
Machines > [Select the machine] > Take Action > Delete and confirm the deletion.
CLI:
maas $PROFILE machine delete $SYSTEM_ID
Replace $SYSTEM_ID with the system ID of the machine to be removed. You can also force deletion from the CLI, if the machine is stuck in an invalid state:
CLI:
maas $PROFILE machine delete $SYSTEM_ID force=true
Verify removal
To confirm that are machine has been removed:
UI:
Hardware > Machines; scan the list or use the Search bar to check.
CLI:
maas $PROFILE machines read | jq -r '.[].hostname'
If the machine wasn’t removed, ensure it’s not in a locked or allocated state.
Last updated 20 hours ago.