Adding a VM host (snap/2.8/CLI)

A VM host is simply a machine which can run virtual machines (VMs) by allocating resources across the VMs you want to create. If needed, you can over-commit resources, allocating more resources than actually available, so long as you don’t try to use more than the VM host has available at any one time. Once MAAS has enlisted, commissioned, and acquired a newly-added machine, you can deploy it as a VM host. Alternatively, you can create a VM host from a machine you’ve already got running.

Warning: You must configure your network to support a VM host before following the procedures in this section. You will also want to make sure that you have set up SSH (if needed) before you follow any procedures in this section.

Eight questions you may have:

  1. How do I configure networking for VM hosts?
  2. How do I set up SSH when manually adding a VM host?
  3. How do I add a VM host?
  4. How do I configure a VM host after I’ve added it?
  5. How do I over-commit resources on a host?
  6. How do I add a VM host using MAAS versions below 2.5?
  7. How can I list resources of all VM hosts?
  8. How can I list resources of a VM host?
  9. How can I update a VM host’s configuration?
  10. How can I list a VM host’s connection parameters?

Adding a VM host

To add a VM host:

maas $PROFILE vm-host create type=$VM_HOST_TYPE power_address=$POWER_ADDRESS \
    [power_user=$USERNAME] [power_pass=$PASSWORD] [zone=$ZONE] \

$VM_HOST_TYPE can currently take three values: rsd, virsh, and lxd.

$POWER_ADDRESS typically looks like the following for libvirt:

qemu+ssh://<vm host IP>/system

of like this for LXD (Beta):

Both $USERNAME and $PASSWORD are optional for the virsh power type. $ZONE and $TAGS are optional for all VM hosts.

The power_... parameters will vary with power type. See the API reference for a listing of available power types.

Some examples

For example, to create an RSD VM host, enter:

maas $PROFILE vm-hosts create type=rsd power_address= \
    power_user=admin power_pass=admin

To create a KVM host, enter the following:

maas $PROFILE vm-hosts create type=virsh power_address=qemu+ssh://ubuntu@

MAAS will automatically discover and store the resources your VM host contains. Any existing machines will also appear on the ‘Machines’ page, and MAAS will automatically attempt to commission them.

Using the CLI, it’s possible to update the configuration of a VM host. You can change these configurable parameters with an update command – but first, you’ll want to know how to check the values of configurable parameters, both before and after the change.

List VM-hosts

To begin, you can list your available KVM-hosts with the following command:

maas admin vm-hosts read | jq -r '(["ID, "VM-HOST","SYSID","CORES",
"USED","RAM", "USED","STORAGE", "USED"] | (., map(length*"-"))),
(.[]| [.id,.name,.host.system_id,.total.cores, .used.cores, .total.memory, .used.memory,.total.local_storage, .used.local_storage])
| @tsv' | column -t

List configurable VM host parameters

There are just a few parameters that you can change for a VM host. You can list these, on a per-host basis, using the following two-step procedure:

  1. Run the command above to get the VM host ID (different from the System ID, see the first column in the listing).

  2. Enter the following command to list configurable parameters:

maas admin vm-host read $ID | jq -r '(["ID","NAME","POOL","ZONE",
"CPU-O/C", "RAM-O/C", "TAGS"] | (., map(length*"-"))), (.| [.id,.name,,,.cpu_over_commit_ratio, 
.memory_over_commit_ratio, .tags[]]) | @tsv' | column -t

where $ID is the ID (not System ID) of the VM-host.

Change the VM host’s name

You can change the VM host’s name very simply, with this command:

maas admin vm-host update $ID name=$NEW_NAME

where $ID is the VM host’s ID (not System ID), and $NEW_NAME is the new name you want to assign. You can check that the change was successful by just printing out the ID and name, like this:

maas admin vm-host read $ID | jq -r '(["ID","NAME"] 
| (., map(length*"-"))), (.| [.id,.name]) 
| @tsv' | column -t

Change the VM host’s pool

You can also change the VM host’s pool with a simple command:

maas admin vm-host update $ID pool=$VALID_POOL

where $ID is the VM host’s ID (not System ID), and $VALID_POOL is the name of a pool that already exists. If you mention a pool you haven’t created yet, you’ll get an error like this:

{"pool": ["Select a valid choice. That choice is not one of the available choices."]}
maas admin resource-pools read | jq -r '.[] | (.name)'

If you really want to set your VM host to a new one, you just need to create a new one with this command:

maas admin resource-pools create name=$NEW_POOL_NAME

Then double-check it with catvmpools, and assign your VM host to it using the earlier command.

Over-commit resources

Over-committed resources are those allocated beyond what’s available in the physical resource. Using sliders on the configuration page, you can limit whether MAAS will attempt to overcommit CPU and memory. The input fields to the right of the sliders accept floating-point values from 0 to 10, with a default value of 1.

The following shows four theoretical examples of these ratios and how they affect physical resource allocation:

  1. 8 physical CPU cores * 1 multiplier = 8 virtual CPU cores
  2. 8 physical CPU cores * 0.5 multiplier = 4 virtual CPU cores
  3. 32 physical CPU cores * 10.0 multiplier = 320 virtual CPU cores
  4. 128GB physical memory * 5.5 multiplier = 704G virtual Memory

Over-committing resources allows a user to compose many MAAS-managed machines without worrying about the physical limitations of the host. For example, on a physical host with four cores and 12 GB of memory, you could compose four libvirt machines, each using two cores and 4 GB of memory. This arrangement over commits the available physical resources. Provided you never run all four VMs simultaneously, you would have all the benefits of MAAS-managed VMs without over-taxing your host.

List resources of all VM hosts

maas $PROFILE vm-hosts read

A portion of the sample output:

        "id": 93,
        "capabilities": [
        "name": "civil-hermit",

List resources of a VM host

To list an individual VM host’s resources:

maas $PROFILE vm-host read $VM_HOST_ID

Update VM host configuration

Update overcommit ratios for a KVM host:

maas $PROFILE vm-host update $VM_HOST_ID power_address=qemu+ssh://ubuntu@ \
        power_pass=example cpu_over_commit_ratio=2.5 memory_over_commit_ratio=10.0

Update the default storage pool used by a KVM host:

maas $PROFILE vm-host update $VM_HOST_ID power_address=qemu+ssh://ubuntu@ \
        power_pass=example default_storage_pool=pool2

List VM host connection parameters

To list a VM host’s connection parameters:

maas $PROFILE vm-host parameters $VM_HOST_ID

Example output:

    "power_address": "",
    "power_pass": "admin",
    "power_user": "admin"