Offline docs (switch to live docs)                         UI-only         CLI-only

How to create VM hosts

In order to deploy a VM host in your MAAS network, you first need to set up a bridge to connect between your VM host and MAAS itself. Once that’s done, you can add and manage VM hosts – and subsequently, create VMs to act as MAAS machines. This article explains:

To enable VM host networking features, MAAS must match the VM host IP address of a potential VM host with a known device (a machine or controller). For example, if a machine not known to MAAS is set up as a VM host, enhanced interface selection features will not be available.

NOTE: It’s essential to enforce usage of IP addresses to avoid domain name conflicts, should different controllers resolve the same domain name with different IP addresses. You should also avoid using 127.0.0.1 when running multiple controllers, as it would confuse MAAS.

How to set up a VM host bridge with the web UI

You can use the MAAS UI to configure a bridge to connect a VM host to MAAS:

Select the machine you want to use as a VM host, switch to the “Network” tab. Select the network where you want to create the bridge and click “Create bridge:”

Configure the bridge on a subnet MAAS controls. You may use any IP mode for the bridge:

When you’re done, it should look something like this:

Then you can deploy Ubuntu.

How to set up a VM host bridge with netplan

You can also use netplan to configure a VM host bridge:

Open your netplan configuration file. This should be in /etc/netplan. It could be called 50-cloud-init.yaml, netplan.yaml, or something else. Modify the file to add a bridge, using the example below to guide you:

network:
    bridges:
        br0:
            addresses:
            - 10.0.0.101/24
            gateway4: 10.0.0.1
            interfaces:
            - enp1s0
            macaddress: 52:54:00:39:9d:f9
            mtu: 1500
            nameservers:
                addresses:
                - 10.0.0.2
                search:
                - maas
            parameters:
                forward-delay: 15
                stp: false
    ethernets:
        enp1s0:
            match:
                macaddress: 52:54:00:39:9d:f9
            mtu: 1500
            set-name: enp1s0
        enp2s0:
            match:
                macaddress: 52:54:00:df:87:ac
            mtu: 1500
            set-name: enp2s0
        enp3s0:
            match:
                macaddress: 52:54:00:a7:ac:46
            mtu: 1500
            set-name: enp3s0
    version: 2

Apply the new configuration with netplan apply.

How to set up a VM host bridge with libvirt

It is also possible to use libvirt↗ to configure a virtual bridge. This method will also work for LXD VM hosts running on Ubuntu. Be aware that other methods may be required if you are configuring LXD on an OS other than Ubuntu.

By default, libvirt creates a virtual bridge, virbr0, through which VMs communicate with each other and the Internet. DHCP, supplied by libvirt, automatically assigns an IP address to each VM. However, to enable network booting in MAAS, you’ll need to provide DHCP in MAAS and either:

You can set up such a maas network like this:

cat << EOF > maas.xml
<network>
 <name>maas</name>
 <forward mode='nat'>
   <nat>
     <port start='1024' end='65535'/>
   </nat>
 </forward>
 <dns enable="no" />
 <bridge name='virbr1' stp='off' delay='0'/>
 <domain name='testnet'/>
 <ip address='172.16.99.1' netmask='255.255.255.0'>
 </ip>
</network>
EOF
virsh net-define maas.xml

Note that this network also has NAT port forwarding enabled to allow VMs to communicate with the Internet at large. Port forwarding is very useful in test environments.

How to set up SSH for use by libvirt

For MAAS to successfully communicate with libvirt on your VM host machine – whether you’re running from snap or package, or running rack controllers in LXD containers or on localhost – this example command must succeed from every rack controller:

virsh -c qemu+ssh://$USER@$VM_HOST_IP/system list --all

Here, $USER is a user on your VM host who is a member of the libvirtd Unix group on the VM host, and $VM_HOST_IP is the IP of your VM host. Note that insufficient permissions for $USER may cause the virsh command to fail with an error such as failed to connect to the hypervisor. Check the $USER group membership to make sure $USER is a member of the libvirtd group.

How to set up SSH (libvirt only)

If you installed MAAS via snap, then create the needed SSH keys this way:

sudo mkdir -p /var/snap/maas/current/root/.ssh
cd /var/snap/maas/current/root/.ssh
sudo ssh-keygen -f id_rsa

Finally, on the VM host, you’ll need to add id_rsa.pub to the authorized_keys file in /home/<vm-host-user-homedir-name>/.ssh/, where <vm-host-user-homedir-name> is the name of your VM host user.

How to add a VM host

After installing MAAS, the ‘KVM’ page is typically empty:

If you want to add a LXD (or libvirt)↗ KVM host to a machine which is already installed, you can do so with the ‘Add KVM’ button:

How to authenticate LXD VM hosts via certificates

Suppose that you’re creating a new LXD KVM, beginning from the top tab in MAAS:

Select “Add KVM”, which brings you to the definition screen:

From here, you’ll continue by choosing your authentication method.

How to let MAAS create a certificate for you

If you choose “Generate new certificate”, as shown above, you’ll come to a screen like this one:

You can still choose to use the LXD trust password (entered when you ran lxd init during LXD installation). You can also, though, choose to use the certificate MAAS has just generated for you. To do that, select the entire contents of the text box, copy it, and paste it into a terminal window – then hit “Enter”:

$ lxc config trust add - <<EOF
> -----BEGIN CERTIFICATE-----
> MIIErTCCApUCEQCGa86XdjYUGm8h8YOh4HAEMA0GCSqGSIb3DQEBDQUAMAAwHhcN
> MjEwOTI0MjE1NDQ4WhcNMzEwOTIyMjE1NDQ4WjApMScwJQYDVQQDDB5teTBuZXh0
> LTMuMS4wLWJldGExLWt2bUB3YWxkZW4wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAw
> ggIKAoICAQC1tmJbSYx3Jb5JcuqLvyO6P0RtYWCbjVYOSAIM1PKHZJRvako6QhjR
> 6wWNcVLAjDJIMuEBysrI8mcAv9D/AfT2qLQ/5mg7anbxfrd3YXG2nc70QJazpFaw
> INDc85wrdJD5NEd50iaka+PztIAWzoZWQr/pLb7hUDnArzSHp5J+w0dRCUh54SyW
> Du4mLpDks5UqMeONO1o7lbaQuBdzGtR4btdmvOkJfg/Pu3i/rzFZ1vvn1JhZTX96
> +xH7tJQiqOk0SXG7F2RmbYiYDhAkiysbMoyOHBCf/qFWq4Vtd/VMxOAT1WERrgWn
> 8nL5kRBozV94QocJaOe+GUSWLHsRpsVa8jiAj3LS2CFQfpaEsrzLSlQOeN2rNB9z
> DO9yGXGql4tUpgtyEvxB/zVrIGd04iTC3D4S9b1KyzTbSsyjTc/XJhUStnn49ySW
> Iwv1eHa2jMvIjRVm5sRfpf0EOZW27HLI1AqDOXR0DmlM2mWvndjvfacX+41I8vuG
> +RPq0ZjDhwfRmUaLiebzcExwPmSHAxqiaV+t0n6ivDWTNk6cNc38rZBh3x6I7JMR
> /85Rc1blLSF7QBMA1HxheCUYzBPTKsdE2btygq9vShRXCdSekV0jGoL1g0n6T59r
> +9nHShgc/Bzk42kcddQySlrqWWHrXX6Z2N1R3eYpuvSEaKsnsjqjwwIDAQABMA0G
> CSqGSIb3DQEBDQUAA4ICAQA4d1Xqi941ssyJoiovTzBgMDSp9kqjpB83BRqbF9oZ
> fQGkezn2jF7SnaXbTyR/K+nir5Rms8OZfUxyZJwYh/YCdnIF8hzC32mLJbP6jcJV
> LS0OD+EipwyRLSe9g2it68TtAhhVXKPx3tGQWWiXtJOF631sJRcRUZATc9nco5H2
> 91GKog4LdFeKD3ArOq1GkE9r95WauTV37x0c474XBt2mVcEvFW50oZbIBPaWLt8E
> q8NG0KYkfIHkhXDGqPDkUtdPJlkiGwqXdaqghuG31a4Or9IKcNmDlli47apaWWJW
> /gqZfFALbOrSJHg10PCqNsfoKmQr2YZzPlTjG39RA7sA1XR6y+lQZqwcXnXk2iAE
> n62OkRUrYVXzBo99zk5jQJVEg6zhfPH9zl6Jmn/vBu0p6RqmqNLTTlMOio8VOp9e
> 9Gyb9uRwzwZ9zgydgI4bHMvcIAq+46wTruOfXBNATWLC2YqXbc+9QqemJebcXULW
> Wf7Sc+SHHx2cVb4OUvUD8keZN37No/2vfZ9NI2SJOI4SxlV2yf6ZRyb7MYIwpm1h
> YTzyS+ywUN4C8p1PsU5iT8DGdcg7Kcso4/DDZeZkLKNeCKizkdMreF7qV0qHTW8z
> PyfZHcR/xWMkjxYZoFu4rVyxpsUJYItJNUNk6vZvSnSDfC2e2JJFfMws+fntNy14
> /w==
> -----END CERTIFICATE-----
> EOF
$

The certificate will be created for you. When you click the “Check authentication” button, you will be brought to this screen:

from which you can continue with normal LXD KVM setup.

How to use your own, existing certificate

Suppose that, after identifying your LXD KVM, you choose “Provide certificate and private key”. When you do so, the screen will extend to allow you to upload these items:

Paste or upload your certificate and private key, then click “Next” to validate your authentication criteria, before continuing through the normal LXD KVM creation process. If your certificate and/or key aren’t usable for some reason, MAAS will return an error (in this case, the private key was entered as gibberish, to produce an error output):

Upon selecting “Authenticate” (assuming successful authentication), you will receive a project selection screen similar to this:

You must either enter a new project name (which cannot contain spaces or special characters), or you must select an existing project. If you’re not really planning on using projects, selecting the “default” project will allow you to continue working as you have in the past.

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

How to configure a VM host

VM hosts have several configuration options. Modify these by selecting the ‘Configuration’ tab and editing options directly. These options include a VM host’s location, password, network zone, resource pool, and memory and CPU overcommit sliders.

LXD clusters

MAAS 3.1 allows MAAS to take advantage of the existing LXD clustering capability.

About LXD clusters

LXD clusters within the context of MAAS are a way of viewing and managing existing VM host clusters and composing VMs within said cluster. MAAS will not create a new cluster, but will discover an existing cluster when you provide the info for adding a single clustered host.

How to add LXD clusters

MAAS assumes you have already configured a cluster within the context of LXD. You then need to configure said cluster with a single trust MAAS will use to communicate with said cluster. Adding a LXD cluster is similar to adding a single LXD host, in that you provide authentication the same way for a single host within the cluster, and then select a project. The only difference is the name you provide will be used for the cluster instead of the individual host. MAAS will then connect to the provided host and discover the other hosts within the cluster, and rename the initially defined host with the cluster member name configured in LXD.

First, add an LXD KVM:

Next, set up credentials and get your MAAS certificate trusted by LXD:

Once it is connected, you can select the project in that cluster:

If the KVM host address is part of a cluster, it will show as a Cluster on the listing page.

How to compose VMs in LXD clusters

Composing a VM in a LXD cluster via MAAS is similar to composing a VM for a single VM host. MAAS does not provide any sort of scheduling of said VM, and will instead target the host you select for composing the VM.

From the KVM host listing page, click on the + icon to add a VM to a specific host:

If you are in a specific KVM host page, you can click + add virtual machine:

How to delete LXD clusters

To delete a LXD cluster, delete any one VM host within the cluster, this will delete the cluster and all members within the cluster: