Errors or typos? Topics missing? Hard to read? Let us know.
This guide provides step-by-step procedures for provisioning machines using MAAS. For more details on concepts and advanced configurations, refer to [Provisioning Explanation].
Plan
Before starting, gather the following information:
- Network setup: IP ranges, VLANs, DHCP configurations.
- Hardware details: Machine architectures, MAC addresses, power types.
- User roles: Define who will manage machines and their access levels.
- Controller deployment: Determine locations and configurations for rack and region controllers.
Configure controllers
Here is a thumbnail reminder of MAAS installation. For detailed instructions, refer to [Install guide].
Install controllers
-
Region and rack controller installation:
sudo snap install maas sudo maas init
-
Rack controller only:
sudo snap install maas sudo maas init rack --maas-url $MAAS_URL --secret $SECRET
Configure region and rack
-
List rack controllers:
maas $PROFILE rack-controllers read | jq -r '.[] | .hostname'
-
Move rack controller to another instance
maas $PROFILE rack-controller delete $SYSTEM_ID
Manage machines
Machines can be added, removed, listed and profiled within MAAS.
Add a machine
-
Via Web UI:
- Go to Machines > Add hardware > Machine.
- Fill in the required details.
- Click Save.
-
Via 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
Remove a machine
Bare-metal and virtual machines can be removed from MAAS in a similar manner.
Remove a machine via Web UI
- Navigate to Machines > [Select the machine] > Take Action > Delete.
- Confirm the deletion.
Remove a machine via CLI
-
Basic deletion:
maas $PROFILE machine delete $SYSTEM_ID
Replace
$SYSTEM_ID
with the system ID of the machine to be removed. -
Force deletion (if the machine is stuck or in an invalid state):
maas $PROFILE machine delete $SYSTEM_ID force=true
Verify removal
- List machines to confirm the machine is gone:
maas $PROFILE machines read | jq -r '.[].hostname'
This will ensure the machine is removed from MAAS completely. If it is not working as expected, ensure the machine is not in a locked or allocated state before attempting deletion.
List machines
- Via CLI:
maas $PROFILE machines read | jq -r '(["HOSTNAME","SYSID","STATUS"] | join(","))'
View machine details
- Via CLI:
maas $PROFILE machine read $SYSTEM_ID | jq '.'
Clone machine configuration
- Via CLI:
Replacemaas $PROFILE machine clone $SOURCE_SYSTEM_ID new_hostname=$NEW_HOSTNAME
$SOURCE_SYSTEM_ID
with the system ID of the source machine and$NEW_HOSTNAME
with the desired hostname for the clone.
Abort machine operations
- Via CLI:
maas $PROFILE machine abort $SYSTEM_ID
Manage machine power
Power on machines
- Via CLI:
maas $PROFILE machine start $SYSTEM_ID
Power off machines
- Via CLI:
maas $PROFILE machine stop $SYSTEM_ID
Soft power-off machines
- Via CLI:
maas $PROFILE machine stop $SYSTEM_ID force=false
Commission machines
Commissioning gathers the necessary information to successfully deploy a machine in a later step. See [link to commissioning] for a detailed explanation.
Upload commissioning scripts
- Via Web UI:
- Go to Settings > User scripts > Upload.
- Upload your script.
Commission a machine
-
Via Web UI:
- Navigate to Machines > machine > Actions > Commission.
- Click Commission machine.
-
Via CLI:
maas $PROFILE machine commission $SYSTEM_ID
Test machines
Basic machine testing is part of the commissioning process. See [testing link] for more details.
Run machine tests
-
Via Web UI:
- Navigate to Machines > machine > Actions > Test.
- Select the tests to run (e.g., CPU, memory, storage) and click Start tests.
-
Via CLI:
maas $PROFILE machine test $SYSTEM_ID tests=cpu,storage
View test results
-
Via Web UI:
- Navigate to Machines > machine > Test results.
-
Via CLI:
maas $PROFILE machine read $SYSTEM_ID | jq '.test_results'
Override failed testing
- Via CLI:
maas $PROFILE machine set-test-result $SYSTEM_ID result=passed
Test networks
In addition to operational testing, MAAS can also test your network links.
Test network connectivity
- Via CLI:
maas $PROFILE machine network-interface $SYSTEM_ID test-connectivity
Validate network configurations
- Via CLI:
maas $PROFILE subnets read | jq '.[] | {name: .name, cidr: .cidr, vlan: .vlan}'
Group machines
Availability Zones
-
List availability zones:
maas $PROFILE availability-zones read
-
Create an availability zone:
maas $PROFILE availability-zones create name=$ZONE_NAME
-
Assign a machine to an availability zone:
maas $PROFILE machine update $SYSTEM_ID zone=$ZONE_NAME
Resource pools
-
List resource pools:
maas $PROFILE resource-pools read
-
Create a resource pool:
maas $PROFILE resource-pools create name=$POOL_NAME
-
Assign a machine to a resource pool:
maas $PROFILE machine update $SYSTEM_ID pool=$POOL_NAME
Tags
-
List tags:
maas $PROFILE tags read
-
Create a tag:
maas $PROFILE tags create name=$TAG_NAME comment="$COMMENT"
-
Assign a tag to a machine:
maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID
-
Remove a tag from a machine:
maas $PROFILE tag update-nodes $TAG_NAME remove=$SYSTEM_ID
Allocate machines
Allocation confers ownership of a machine to the user who allocates it. Other users cannot commandeer an allocation machine.
Allocate a specific machine
- Via CLI:
maas $PROFILE machines allocate system_id=$SYSTEM_ID
Allocate multiple machines
-
Via Web UI:
- Go to Machines > machine > Take action > Allocate.
-
Via CLI:
maas $PROFILE machines allocate
Deploy machines
Deployment puts a machine in service, after loading the desired OS image and configuration (see [deployment]). Much of the machine configuration can be modified with custom cloud-init scripts (see [cloud-init scripts]).
Configure custom cloud-init scripts
-
Add cloud-init script via Web UI:
- Navigate to Machines > machine > Actions > Deploy > Configuration options.
- Add your custom cloud-init script in the provided field.
-
Example cloud-init script:
#cloud-config packages: - nginx runcmd: - systemctl enable nginx - systemctl start nginx
-
Add cloud-init script via CLI:
maas $PROFILE machine deploy $SYSTEM_ID cloud_init_userdata="$(cat cloud-init.yaml)"
Set deployment timeout
- Via CLI:
maas $PROFILE maas set-config name=node-timeout value=$NUMBER_OF_MINUTES
Deploy machines
-
Via Web UI:
- Navigate to Machines > machine > Take action > Deploy.
-
Via CLI:
maas $PROFILE machine deploy $SYSTEM_ID
Deploy a machine as a KVM host
- Via CLI:
maas $PROFILE machine deploy $SYSTEM_ID install_kvm=True
Add running machines
MAAS can add existing, operating machines as if they had been deployed by MAAS.
-
Via 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
Manage machine states
There are a few other machine states that assist in provisioning machines with MAAS.
Enter rescue mode
- Via CLI:
maas $PROFILE machine enter-rescue-mode $SYSTEM_ID
What to do in rescue mode
- Access the machine via SSH and perform diagnostics or repairs.
- Example command to SSH:
ssh ubuntu@$MACHINE_IP
Exit rescue mode
- Via CLI:
maas $PROFILE machine exit-rescue-mode $SYSTEM_ID
Mark machines as broken
-
Via Web UI:
- Navigate to Machines > machine > Take action > Mark broken.
-
Via CLI:
maas $PROFILE machines mark-broken $SYSTEM_ID
Mark machines as fixed
-
Via Web UI:
- Navigate to Machines > machine > Take action > Mark fixed.
-
Via CLI:
maas $PROFILE machines mark-fixed $SYSTEM_ID
Release machines
-
Via Web UI:
- Navigate to Machines > machine > Take action > Release.
-
Via CLI:
maas $PROFILE machines release $SYSTEM_ID