How to provision machines with MAAS

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:

    1. Go to Machines > Add hardware > Machine.
    2. Fill in the required details.
    3. 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

  1. Navigate to Machines > [Select the machine] > Take Action > Delete.
  2. 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:
    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.

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:
    1. Go to Settings > User scripts > Upload.
    2. Upload your script.

Commission a machine

  • Via Web UI:

    1. Navigate to Machines > machine > Actions > Commission.
    2. 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:

    1. Navigate to Machines > machine > Actions > Test.
    2. 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:

    1. 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:

    1. 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:

    1. Navigate to Machines > machine > Actions > Deploy > Configuration options.
    2. 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:

    1. 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:

    1. Navigate to Machines > machine > Take action > Mark broken.
  • Via CLI:

    maas $PROFILE machines mark-broken $SYSTEM_ID
    

Mark machines as fixed

  • Via Web UI:

    1. Navigate to Machines > machine > Take action > Mark fixed.
  • Via CLI:

    maas $PROFILE machines mark-fixed $SYSTEM_ID
    

Release machines

  • Via Web UI:

    1. Navigate to Machines > machine > Take action > Release.
  • Via CLI:

    maas $PROFILE machines release $SYSTEM_ID