MAAS provides the capability to customise machines.
How to customise machine storage
This section will show you:
Note that layouts can be set globally and on a per-machine basis. For additional information on storage layouts, see the Storage layouts reference article.
How to set global storage layouts
All machines will have a default layout applied when commissioned. An administrator can configure the default layout on the ‘Settings’ page, under the ‘Storage’ tab.
All machines will have a default layout applied when commissioned. To set the default storage layout for all machines:
maas $PROFILE maas set-config name=default_storage_layout value=$LAYOUT_TYPE
For example, to set the default layout to Flat:
maas $PROFILE maas set-config name=default_storage_layout value=flat
Important: The new default will only apply to newly-commissioned machines.
The new default will only apply to newly-commissioned machines.
How to set per-machine storage layouts
An administrator can change the layout for a single machine as well as customise that layout providing this is done while the machine has a status of ‘Ready’. This is only possible via the CLI: to see how, click the “CLI” option for your version and delivery method above.
An administrator can set a storage layout for a machine with a status of ‘Ready’ like this:
maas $PROFILE machine set-storage-layout $SYSTEM_ID storage_layout=$LAYOUT_TYPE [$OPTIONS]
For example, to set an LVM layout where the logical volume has a size of 5 GB:
maas $PROFILE machine set-storage-layout $SYSTEM_ID storage_layout=lvm lv_size=5368709120
You must specify all storage sizes in bytes.
This action will remove the configuration that may exist on any block device.
Only an administrator can modify storage at the block device level (providing the machine has a status of ‘Ready’).
How to set the default erasure configuration
-
Click on Settings" → Storage.
-
Set or clear Erase machines’ disks prior to releasing. If you set this option, users will be compelled to use disk erasure: that option will be pre-filled in the machine’s view and the user will be unable to remove the option.
How to erase disks
When using the MAAS CLI, you can erase a disk when releasing an individual machine. Note that this option is not available when releasing multiple machines, so you’ll want to make sure you’re using:
maas $PROFILE machine release...
and not:
maas $PROFILE machines release...
Note the difference in singular and plural “machine/machines” in the commands. Releasing a machine requires that you have the system_id of the machine to be released, which you can obtain with a command like this one:
maas admin machines read | jq -r '(["HOSTNAME","SYSID","POWER","STATUS",
"OWNER", "TAGS", "POOL", "VLAN","FABRIC","SUBNET"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id, .power_state, .status_name, .owner // "-",
.tag_names[0] // "-", .pool.name,
.boot_interface.vlan.name, .boot_interface.vlan.fabric,
.boot_interface.links[0].subnet.name]) | @tsv' | column -t
The basic form of the release command, when erasing disks on releasing, is:
maas $PROFILE machine release $SYSTEM_ID comment="some comment" erase=true [secure_erase=true ||/&& quick_erase=true]
Parameters secure_erase and quick_erase are both optional, although if you don’t specify either of them, the entire disk will be overwritten with null bytes. Note that this overwrite process is very slow.
Secure erasure uses the drive’s secure erase feature, if it has one. In some cases, this can be much faster than overwriting the entire drive. Be aware, though, that some drives implement secure erasure as a complete drive overwrite, so this method may still be very slow. Additionally, if you specify secure erasure and the drive doesn’t have this feature, you’ll get a complete overwrite anyway – again, possibly very slow.
Quick erasure wipes 2MB at the start and end of the drive to make recovery both inconvenient and unlikely to happen by accident. Note, though, that quick erasure is not secure.
How to specify conditional erasure types
If you specify both erasure types, like this:
maas $PROFILE machine release $SYSTEM_ID comment="some comment" erase=true secure_erase=true quick_erase=true
then MAAS will perform a secure erasure if the drive has that feature; if not, it will perform a quick erasure. Of course, if you’re concerned about completely erasing the drive, and you’re not sure whether the disk has secure erase features, the best way to handle that is to specify nothing, and allow the full disk to be overwritten by null bytes:
maas $PROFILE machine release $SYSTEM_ID comment="some comment" erase=true
How to list block devices
To view all block devices on a machine use the read operation. This list both physical and virtual block devices, as you can see in the output from the following command:
maas admin block-devices read <node-id>
Output:
Success.
Machine-readable output follows:
[
{
"id": 10,
"path": "/dev/disk/by-dname/vda",
"serial": ",
"block_size": 4096,
"available_size": 0,
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/",
"filesystem": null,
"id_path": "/dev/vda",
"size": 5368709120,
"partition_table_type": "MBR",
"model": ",
"type": "physical",
"uuid": null,
"used_size": 5365563392,
"used_for": "MBR partitioned with 1 partition",
"partitions": [
{
"bootable": false,
"id": 9,
"resource_uri":"/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/partition/9",
"path": "/dev/disk/by-dname/vda-part1",
"uuid": "aae082cd-8be0-4a64-ab49-e998abd6ea43",
"used_for": "LVM volume for vgroot",
"size": 5360320512,
"type": "partition",
"filesystem": {
"uuid": "a56ebfa6-8ef4-48b5-b6bc-9f9d27065d24",
"mount_options": null,
"label": null,
"fstype": "lvm-pv",
"mount_point": null
}
}
],
"tags": [
"rotary"
],
"name": "vda"
},
{
"id": 11,
"path": "/dev/disk/by-dname/lvroot",
"serial": null,
"block_size": 4096,
"available_size": 0,
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/11/",
"filesystem": {
"uuid": "7181a0c0-9e16-4276-8a55-c77364d137ca",
"mount_options": null,
"label": "root",
"fstype": "ext4",
"mount_point": "/"
},
"id_path": null,
"size": 3221225472,
"partition_table_type": null,
"model": null,
"type": "virtual",
"uuid": "fc8ba89e-9149-412c-bcea-e596eb7c0d14",
"used_size": 3221225472,
"used_for": "ext4 formatted filesystem mounted at /",
"partitions": [],
"tags": [],
"name": "vgroot-lvroot"
}
]
How to read a block device
If you want to read just one block device instead of listing all block devices the read operation on the block device endpoint provides that information. To display the details on device ‘11’ from the previous output, for example, we could enter:
maas admin block-device read <node-id> 11
The above command generates the following output:
Success.
Machine-readable output follows:
{
"available_size": 0,
"path": "/dev/disk/by-dname/vgroot-lvroot",
"name": "vgroot-lvroot",
"used_for": "ext4 formatted filesystem mounted at /",
"type": "virtual",
"used_size": 3221225472,
"filesystem": {
"uuid": "7181a0c0-9e16-4276-8a55-c77364d137ca",
"mount_point": "/",
"mount_options": null,
"fstype": "ext4",
"label": "root"
},
"id_path": null,
"id": 11,
"partition_table_type": null,
"block_size": 4096,
"tags": [],
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/11/",
"uuid": "fc8ba89e-9149-412c-bcea-e596eb7c0d14",
"serial": null,
"partitions": [],
"size": 3221225472,
"model": null
}
It is also possible to use the name of the block device, such as ‘sda’ or ‘vda’, instead of its ‘id’:
s admin block-device read <node-id> vda
MAAS allows the name of a block device to be changed. If the block device name has changed then the API call needs to use the new name.
Using the ID is safer as it never changes.
How to create a block device
MAAS gathers the required information itself on block devices when re- commissioning a machine. If this doesn’t provide the required information, it is also possible - though not recommended - for an administrator to use the API to manually add a physical block device to a machine.
maas admin block-devices create <node-id> name=vdb model="QEMU" serial="QM00001" size=21474836480 block_size=4096
Depending on your configuration, output should be similar to the following:
Success.
Machine-readable output follows:
{
"available_size": 21474836480,
"path": "/dev/disk/by-dname/vdb",
"name": "vdb",
"used_for": "Unused",
"type": "physical",
"used_size": 0,
"filesystem": null,
"id_path": ",
"id": 12,
"partition_table_type": null,
"block_size": 4096,
"tags": [],
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/12/",
"uuid": null,
"serial": "QM00001",
"partitions": [],
"size": 21474836480,
"model": "QEMU"
}
The serial number is what MAAS will use when a machine is deployed to find the specific block device. It’s important that this be correct. In a rare chance that your block device does not provide a model or serial number you can provide an id_path. The id_path should be a path that is always the same, no matter the kernel version.
How to update a block device
An administrator can also update the details held on a physical block device, such as its name, from the API:
maas admin block-device update <node-id> 12 name=newroot
Output from this command will show that the ‘name’ has changed:
Success.
Machine-readable output follows:
{
"block_size": 4096,
"size": 21474836480,
"filesystem": null,
"model": "QEMU",
"name": "newroot",
"partitions": [],
"tags": [],
"used_size": 0,
"path": "/dev/disk/by-dname/newroot",
"id_path": ",
"uuid": null,
"available_size": 21474836480,
"id": 12,
"used_for": "Unused",
"type": "physical",
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/12/",
"partition_table_type": null,
"serial": "QM00001"
}
How to delete a block device
Physical and virtual block devices can be deleted by an administrator, while ordinary users can only delete virtual block devices:
maas admin block-device delete <node-id> 12
How to format a block device
An entire block device can be formatted by defining a filesystem with the ‘format’ API call:
maas admin block-device format <node-id> 11 fstype=ext4
Successful output from this command will look similar to this:
Success.
Machine-readable output follows:
{
"block_size": 4096,
"size": 3221225472,
"filesystem": {
"label": ",
"fstype": "ext4",
"mount_options": null,
"uuid": "75e42f49-9a45-466c-8425-87a40e4f4148",
"mount_point": null
},
"model": null,
"name": "vgroot-lvroot",
"partitions": [],
"tags": [],
"used_size": 3221225472,
"path": "/dev/disk/by-dname/vgroot-lvroot",
"id_path": null,
"uuid": "fc8ba89e-9149-412c-bcea-e596eb7c0d14",
"available_size": 0,
"id": 11,
"used_for": "Unmounted ext4 formatted filesystem",
"type": "virtual",
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/11/",
"partition_table_type": null,
"serial": null
}
You cannot format a block device that contains partitions or is used to make another virtual block device.
How to unformat a block device
You can remove the filesystem from a block device with the ‘unformat’ API call:
maas admin block-device unformat <node-id> 11
The output from this command should show the filesystem is now ‘null’:
Success.
Machine-readable output follows:
{
"available_size": 3221225472,
"path": "/dev/disk/by-dname/vgroot-lvroot",
"name": "vgroot-lvroot",
"used_for": "Unused",
"type": "virtual",
"used_size": 0,
"filesystem": null,
"id_path": null,
"id": 11,
"partition_table_type": null,
"block_size": 4096,
"tags": [],
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/11/",
"uuid": "fc8ba89e-9149-412c-bcea-e596eb7c0d14",
"serial": null,
"partitions": [],
"size": 3221225472,
"model": null
}
How to mount a block device
If a block device has a filesystem, you can use the ‘maas’ command to mount a block devices at a given mount point:
maas admin block-device mount <node-id> 11 mount_point=/srv
The mount point is included in the successful output from the command:
Success.
Machine-readable output follows:
{
"available_size": 0,
"path": "/dev/disk/by-dname/vgroot-lvroot",
"name": "vgroot-lvroot",
"used_for": "ext4 formatted filesystem mounted at /srv",
"type": "virtual",
"used_size": 3221225472,
"filesystem": {
"uuid": "6f5965ad-49f7-42da-95ff-8000b739c39f",
"mount_point": "/srv",
"mount_options": ",
"fstype": "ext4",
"label": "
},
"id_path": null,
"id": 11,
"partition_table_type": null,
"block_size": 4096,
"tags": [],
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/11/",
"uuid": "fc8ba89e-9149-412c-bcea-e596eb7c0d14",
"serial": null,
"partitions": [],
"size": 3221225472,
"model": null
}
How to unmount a block device
To remove the mount point from the block device, use the ‘unmount’ call:
maas admin block-device unmount <node-id> 11 mount_point=/srv
The previous command will include a nullified ‘mount_point’ in its output:
Success.
Machine-readable output follows:
{
"available_size": 0,
"path": "/dev/disk/by-dname/vgroot-lvroot",
"name": "vgroot-lvroot",
"used_for": "Unmounted ext4 formatted filesystem",
"type": "virtual",
"used_size": 3221225472,
"filesystem": {
"uuid": "6f5965ad-49f7-42da-95ff-8000b739c39f",
"mount_point": null,
"mount_options": null,
"fstype": "ext4",
"label": "
},
"id_path": null,
"id": 11,
"partition_table_type": null,
"block_size": 4096,
"tags": [],
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/11/",
"uuid": "fc8ba89e-9149-412c-bcea-e596eb7c0d14",
"serial": null,
"partitions": [],
"size": 3221225472,
"model": null
}
How to set a block device as a boot disk
By default, MAAS picks the first added block device to the machine as the boot disk. In most cases this works as expected as the BIOS usually enumerates the boot disk as the first block device. There are cases where this fails and the boot disk needs to be set to another disk. This API allow setting which block device on a machine MAAS should use as the boot disk.:
maas admin block-device set-boot-disk <node-id> 10
Only an administrator can set which block device should be used as the boot disk and only a physical block device can be set as as the boot disk. This operation should be done before a machine is allocated or the storage layout will be applied to the previous boot disk.
How to list partitions
To view all the partitions on a block device, use the ‘partitions read’ API call:
maas admin partitions read <node-id> 10
Success.
Machine-readable output follows:
[
{
"bootable": false,
"id": 9,
"resource_uri":
"/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/partition/9",
"path": "/dev/disk/by-dname/vda-part1",
"uuid": "aae082cd-8be0-4a64-ab49-e998abd6ea43",
"used_for": "LVM volume for vgroot",
"size": 5360320512,
"type": "partition",
"filesystem": {
"uuid": "a56ebfa6-8ef4-48b5-b6bc-9f9d27065d24",
"mount_options": null,
"label": null,
"fstype": "lvm-pv",
"mount_point": null
}
}
]
To view the metadata for a specific partition on a block device, rather than all partitions, use the singular ‘partition’ API call with an endpoint:
maas admin partition read <node-id> 10 9
How to create a partition
To create a new partition on a block device, use the ‘create’ API call:
maas admin partitions create <node-id> 10 size=5360320512
In addition to bytes, as shown above, the ‘size’ of a partition can also be defined with a ‘G’ for gigabytes or ‘M’ for megabytes. The output from the previous command will look like this:
Success.
Machine-readable output follows:
{
"bootable": false,
"path": "/dev/disk/by-dname/vda-part1",
"filesystem": null,
"used_for": "Unused",
"type": "partition",
"id": 10,
"size": 5360320512,
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/partition/10",
"uuid": "3d32adbf-9943-4785-ab38-963758338c6c"
}
How to delete a partition
Partitions can be deleted from a block device with the ‘delete’ API call. Make sure you double check the partition details as the partition is deleted immediately, with no further confirmation:
maas admin partition delete <node-id> 10 9
Successful output from the ‘delete’ command will look like this:
Success.
Machine-readable output follows:
How to format a partition
Partitions can be formatted in a similar way to block devices:
maas admin partition format <node-id> 10 9 fstype=ext4
The output from the ‘format’ command will be similar to the following:
Success.
Machine-readable output follows:
{
"id": 9,
"used_for": "Unmounted ext4 formatted filesystem",
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/partition/9",
"path": "/dev/disk/by-dname/vda-part1",
"uuid": "aae082cd-8be0-4a64-ab49-e998abd6ea43",
"size": 5360320512,
"bootable": false,
"type": "partition",
"filesystem": {
"uuid": "ea593366-be43-4ea3-b2d5-0adf82085a62",
"mount_point": null,
"mount_options": null,
"fstype": "ext4",
"label": "
}
}
You cannot format partitions that are used to make another virtual block device.
How to unformat a partition
You can also remove the filesystem from a partition with the ‘unformat’ API call:
maas admin partition unformat <node-id> 10 10 fstype=ext4
Success.
Machine-readable output follows:
{
"bootable": false,
"path": "/dev/disk/by-dname/vda-part1",
"filesystem": null,
"used_for": "Unused",
"type": "partition",
"id": 10,
"size": 5360320512,
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/partition/10",
"uuid": "3d32adbf-9943-4785-ab38-963758338c6c"
}
How to mount a partition
A formatted partition can be mounted at a given mount point with the ‘mount’ command.
maas admin partition mount <node-id> 10 10 mount_point=/srv
The mount point and the filesystem is visible in the output from the command:
Success.
Machine-readable output follows:
{
"bootable": false,
"id": 10,
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/partition/10",
"path": "/dev/disk/by-dname/vda-part1",
"uuid": "3d32adbf-9943-4785-ab38-963758338c6c",
"used_for": "ext4 formatted filesystem mounted at /srv",
"size": 5360320512,
"type": "partition",
"filesystem": {
"uuid": "1949a5fb-f7bd-4ada-8ba5-d06d3f5857a8",
"mount_options": ",
"label": ",
"fstype": "ext4",
"mount_point": "/srv"
}
}
How to unmount a partition
A previous mounted partition can be unmounted with the ‘unmount’ command:
maas admin partition unmount 4y3h8a 10 10
After successfully running this command, the mount point will show as ‘null’ in the output:
Success.
Machine-readable output follows:
{
"bootable": false,
"id": 10,
"resource_uri": "/MAAS/api/2.0/nodes/4y3h8a/blockdevices/10/partition/10",
"path": "/dev/disk/by-dname/vda-part1",
"uuid": "3d32adbf-9943-4785-ab38-963758338c6c",
"used_for": "Unmounted ext4 formatted filesystem",
"size": 5360320512,
"type": "partition",
"filesystem": {
"uuid": "1949a5fb-f7bd-4ada-8ba5-d06d3f5857a8",
"mount_options": null,
"label": ",
"fstype": "ext4",
"mount_point": null
}
"type": "partition",
"id": 3,
"size": 2000003072
}
How to list VMFS datastores
To view all VMFS Datastores on a machine, use the ‘vmfs-datastores read’ API call:
maas $PROFILE vmfs-datastores read $SYSTEM_ID
[
{
"human_size": "45.8 GB",
"filesystem": {
"fstype": "vmfs6",
"mount_point": "/vmfs/volumes/datastore1"
},
"uuid": "2779a745-1db3-4fd7-b06e-455b728fffd4",
"name": "datastore1",
"system_id": "4qxaga",
"devices": [
{
"uuid": "c55fe657-689d-4570-8492-683dd5fa1c40",
"size": 35026632704,
"bootable": false,
"tags": [],
"used_for": "VMFS extent for datastore1",
"filesystem": {
"fstype": "vmfs6",
"label": null,
"uuid": "55ac6422-68b5-440e-ba65-153032605b51",
"mount_point": null,
"mount_options": null
},
"type": "partition",
"device_id": 5,
"path": "/dev/disk/by-dname/sda-part3",
"system_id": "4qxaga",
"id": 71,
"resource_uri": "/MAAS/api/2.0/nodes/4qxaga/blockdevices/5/partition/71"
},
{
"uuid": "5182e503-4ad4-446e-9660-fd5052b41cc5",
"size": 10729029632,
"bootable": false,
"tags": [],
"used_for": "VMFS extent for datastore1",
"filesystem": {
"fstype": "vmfs6",
"label": null,
"uuid": "a5949b18-d591-4627-be94-346d0fdaf816",
"mount_point": null,
"mount_options": null
},
"type": "partition",
"device_id": 6,
"path": "/dev/disk/by-dname/sdb-part1",
"system_id": "4qxaga",
"id": 77,
"resource_uri": "/MAAS/api/2.0/nodes/4qxaga/blockdevices/6/partition/77"
}
],
"id": 17,
"size": 45755662336,
"resource_uri": "/MAAS/api/2.0/nodes/4qxaga/vmfs-datastore/17/"
}
]
How to view a VMFS datastore
To view a specific VMFS Datastores on a machine, use the ‘vmfs-datastore read’ API call:
maas $PROFILE vmfs-datastore read $SYSTEM_ID $VMFS_DATASTORE_ID
{
"uuid": "fb6fedc2-f711-40de-ab83-77eddc3e19ac",
"name": "datastore1",
"system_id": "b66fn6",
"id": 18,
"filesystem": {
"fstype": "vmfs6",
"mount_point": "/vmfs/volumes/datastore1"
},
"human_size": "2.8 GB",
"devices": [
{
"uuid": "b91df576-ba02-4acb-914f-03ba9a2865b7",
"size": 2814377984,
"bootable": false,
"tags": [],
"system_id": "b66fn6",
"used_for": "VMFS extent for datastore1",
"type": "partition",
"id": 80,
"filesystem": {
"fstype": "vmfs6",
"label": null,
"uuid": "4a098d71-1e59-4b5f-932d-fc30a1c0dc96",
"mount_point": null,
"mount_options": null
},
"device_id": 1,
"path": "/dev/disk/by-dname/vda-part3",
"resource_uri": "/MAAS/api/2.0/nodes/b66fn6/blockdevices/1/partition/80"
}
],
"size": 2814377984,
"resource_uri": "/MAAS/api/2.0/nodes/b66fn6/vmfs-datastore/18/"
}
How to create a VMFS datastore
A VMware VMFS datastore is created on one or more block devices or partitions.
To create a VMFS Datastores on a machine use the ‘vmfs-datastores create’ API call:
maas $PROFILE vmfs-datastores create $SYSTEM_ID name=$VMFS_NAME block_devices=$BLOCK_ID_1,$BLOCK_ID_2 partitions=$PARTITION_ID_1,$PARTITION_ID_2
{
"system_id": "b66fn6",
"devices": [
{
"uuid": "b91df576-ba02-4acb-914f-03ba9a2865b7",
"size": 2814377984,
"bootable": false,
"tags": [],
"device_id": 1,
"system_id": "b66fn6",
"type": "partition",
"used_for": "VMFS extent for datastore42",
"filesystem": {
"fstype": "vmfs6",
"label": null,
"uuid": "fc374367-a2fb-4e50-9377-768bfe9705b6",
"mount_point": null,
"mount_options": null
},
"path": "/dev/disk/by-dname/vda-part3",
"id": 80,
"resource_uri": "/MAAS/api/2.0/nodes/b66fn6/blockdevices/1/partition/80"
}
],
"name": "datastore42",
"filesystem": {
"fstype": "vmfs6",
"mount_point": "/vmfs/volumes/datastore42"
},
"id": 19,
"size": 2814377984,
"uuid": "2711566c-2df4-4cc4-8c06-7392bb1f9532",
"human_size": "2.8 GB",
"resource_uri": "/MAAS/api/2.0/nodes/b66fn6/vmfs-datastore/19/"
}
How to edit a VMFS datastore
To edit an existing VMFS Datastores on a machine use the ‘vmfs-datastore update’ API call:
maas $PROFILE vmfs-datastore update $SYSTEM_ID $VMFS_ID name=$NEW_VMFS_NAME add_block_devices=$NEW_BLOCK_ID_1,$NEW_BLOCK_ID_2 add_partitions=$NEW_PARTITION_ID_1,$NEW_PARTITION_ID_2 remove_partitions=$EXISTING_PARTITION_ID1,$EXISTING_PARTITION_ID2
{
"uuid": "2711566c-2df4-4cc4-8c06-7392bb1f9532",
"name": "datastore42",
"system_id": "b66fn6",
"id": 19,
"filesystem": {
"fstype": "vmfs6",
"mount_point": "/vmfs/volumes/datastore42"
},
"human_size": "13.5 GB",
"devices": [
{
"uuid": "b91df576-ba02-4acb-914f-03ba9a2865b7",
"size": 2814377984,
"bootable": false,
"tags": [],
"system_id": "b66fn6",
"used_for": "VMFS extent for datastore42",
"type": "partition",
"id": 80,
"filesystem": {
"fstype": "vmfs6",
"label": null,
"uuid": "fc374367-a2fb-4e50-9377-768bfe9705b6",
"mount_point": null,
"mount_options": null
},
"device_id": 1,
"path": "/dev/disk/by-dname/vda-part3",
"resource_uri": "/MAAS/api/2.0/nodes/b66fn6/blockdevices/1/partition/80"
},
{
"uuid": "f21fe54e-b5b1-4562-ab6b-e699e99f002f",
"size": 10729029632,
"bootable": false,
"tags": [],
"system_id": "b66fn6",
"used_for": "VMFS extent for datastore42",
"type": "partition",
"id": 86,
"filesystem": {
"fstype": "vmfs6",
"label": null,
"uuid": "f3d9b6a3-bab3-4677-becb-bf5a421bfcc2",
"mount_point": null,
"mount_options": null
},
"device_id": 2,
"path": "/dev/disk/by-dname/vdb-part1",
"resource_uri": "/MAAS/api/2.0/nodes/b66fn6/blockdevices/2/partition/86"
}
],
"size": 13543407616,
"resource_uri": "/MAAS/api/2.0/nodes/b66fn6/vmfs-datastore/19/"
}
How to delete a VMFS datastore
To delete a VMFS Datastores on a machine use the ‘vmfs-datastore delete’ API call:
maas $PROFILE vmfs-datastore delete $SYSTEM_ID $VMFS_ID
How to pre-seed with curtin
You can customise the Curtin installation by either editing the existing curtin_userdata template or by adding a custom file as described above. For a flowchart, showing where Curtin and pre-seeding fits into the deployment picture, see How images get deployed.
Curtin provides hooks to execute custom code before and after installation takes place. These hooks are named early and late respectively, and they can both be overridden to execute the Curtin configuration in the ephemeral environment. Additionally, the late hook can be used to execute a configuration for a machine being installed, a state known as in-target.
Curtin commands look like this:
foo: ["command", "--command-arg", "command-arg-value"]
Each component of the given command makes up an item in an array. Note, however, that the following won’t work:
foo: ["sh", "-c", "/bin/echo", "foobar"]
This syntax won’t work because the value of sh's -c argument is itself an entire command. The correct way to express this is:
foo: ["sh", "-c", "/bin/echo foobar"]
The following is an example of an early command that will run before the installation takes place in the ephemeral environment. The command pings an external machine to signal that the installation is about to start:
early_commands:
signal: ["wget", "--no-proxy", "http://example.com/", "--post-data", "system_id=&signal=starting_install", "-O", "/dev/null"]
The following is an example of two late commands that run after installation is complete. Both run in-target, on the machine being installed.
The first command adds a PPA to the machine. The second command creates a file containing the machine’s system ID:
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"]
How to pre-seed with cloud-init
For a flowchart, showing where cloud-init fits into the deployment picture, see How images get deployed.
To customise cloud-init via the web UI:
-
Select Machines.
-
Select a machine.
-
Select Actions > Deploy.
-
Checkbox Cloud-init user-data….
-
Paste, upload, or drag-and-drop the script into the box.
-
Select Start deployment for machine.
To customise cloud-init via the web UI:
-
Select a machine.
-
Choose Take action >> Deploy.
-
Select a viable release.
-
Check the box labelled Cloud-init user-data….
-
Paste the desired script directly into the box.
-
Select Start deployment for machine.
For example, to import an SSH key immediately after your machine deployment, you could paste this script:
#!/bin/bash
(
echo === $date ===
ssh-import-id foobar_user
) | tee /ssh-key-import.log
No script validation of any kind is provided with this capability. You will need to test and debug your own cloud-init scripts.
Using cloud-init to customise a machine after deployment is relatively easy. After you’re logged in, use the following command to deploy a machine with a custom script you’ve written:
maas $PROFILE machine deploy $SYSTEM_ID user_data=<base-64-encoded-script>
The three replaceable parameters shown above decode to:
-
$PROFILE: Your MAAS login. E.g.admin -
$SYSTEM_ID: The machine’s system ID (see example below) -
<base-64-encoded-script>: A base-64 encoded copy of your customisation script. See below for an example.
E.g.:
Suppose you would like to import an SSH key immediately after your machine deployment. First, you want to find the machine’s system_id, which you can do with this short, command-line jq script:
maas admin machines read | jq -r '(["HOSTNAME","SYSID"] | (., map(length*"-"))),
(.[] | [.hostname, .system_id]) | @tsv' | column -t
You might then use this script, called import_key.sh, to retrieve the needed key:
#!/bin/bash
(
echo === $date ===
ssh-import-id foobar_user
) | tee /ssh-key-import.log
This script echoes the date in addition to the output of the ssh-import-key command. It also adds that output to a file, /ssh-key-import.log.
Base-64 encoding is required because the MAAS command-line interacts with the MAAS API, and base-64 encoding allows MAAS to send the script inside a POST HTTP command.
Use the base64 command to output a base-64 encoded version of your script:
base64 -w0 ./import_key.sh
Putting it together:
maas $PROFILE machine deploy $SYSTEM_ID user_data=$(base64 -w0 ./import_key.sh)
After MAAS deploys the machine, you’ll find /ssh-key-import.log on the machine you deployed.
How to choose Ubuntu kernels
How to set a default minimum kernel for enlistment and commissioning
To set the default minimum enlistment and commissioning kernel for all machines:
-
Select Settings.
-
Select Configuration.
-
Select Commissioning.
-
Select a kernel from the Default minimum kernel version drop-down.
-
Select Save to register your changes.
To set the default minimum enlistment and commissioning kernel (based on Ubuntu release: GA kernel) for all machines:
-
Select Settings >> General.
-
Select a kernel in the Default Minimum Kernel Version field of the Commissioning section
How to set a minimum deployment kernel for a machine
To set the minimum deploy kernel on a machine basis:
-
Select Machines.
-
Click on a machine.
-
Select Configuration.
-
Select Edit in the Machine configuration section.
-
Select a kernel in the Minimum Kernel field.
How to set a specific kernel during machine deployment
To set a specific kernel during deployment:
-
Select Machines.
-
Click on a machine.
-
Choose Take action >> Deploy.
-
Choose a kernel from the third kernel field.
-
Click Deploy machine to initiate the deployment.
MAAS verifies that the specified kernel is available for the given Ubuntu release (series) before deploying the machine.
To set a default minimum kernel for all new and commissioned machines:
maas $PROFILE maas set-config name=default_min_hwe_kernel value=$KERNEL
For example, to set it to the 16.04 GA kernel:
maas $PROFILE maas set-config name=default_min_hwe_kernel value=ga-16.04
The command option default_min_hwe_kernel appears to apply to only HWE kernels but this is not the case.
How to set a minimum deployment kernel for a machine
To set the minimum deploy kernel on a per-machine basis:
maas $PROFILE machine update $SYSTEM_ID min_hwe_kernel=$HWE_KERNEL
For example, to set it to the HWE 16.04 kernel:
maas $PROFILE machine update $SYSTEM_ID min_hwe_kernel=hwe-16.04
The command option default_min_hwe_kernel appears to apply to only HWE kernels but this is not the case.
How to set a specific kernel during machine deployment
To set a specific kernel during the deployment of a machine:
maas $PROFILE machine deploy $SYSTEM_ID distro_series=$SERIES hwe_kernel=$KERNEL
The operation will fail if the kernel specified by hwe_kernel is older than the kernel (possibly) given by default_min_hwe_kernel. Similarly, it will not work if the kernel is not available for the given distro series (such as ‘hwe-16.10’ for ‘xenial’).
For example, to deploy a Xenial node with the HWE 16.04 edge kernel:
maas $PROFILE machine deploy $SYSTEM_ID distro_series=xenial hwe_kernel=hwe-16.04-edge
The command option hwe_kernel appears to apply to only HWE kernels but this is not the case.
How to set global kernel boot options
To set global kernel boot options:
-
Select Settings.
-
Select Configuration > Kernel parameters.
-
Enter the Global boot parameters always passed to the kernel in the text box.
-
Select Save to register your changes.
To set kernel boot options globally:
-
Make sure that you are logged in as an administrator.
-
Go to Settings >> General.
-
Scroll down to the Global Kernel Parameters section:
-
Type in the desired (space separated) options.
-
Be sure to click Save.
The contents of the field will be used as-is. Do not use extra characters.
You can set kernel boot options and apply them to all machines with the CLI command:
maas $PROFILE maas set-config name=kernel_opts value='$KERNEL_OPTIONS'
How to create tags with built-in kernel options
You can create tags with embedded kernel boot options. When you apply such tags to a machine, those kernel boot options will be applied to that machine on the next deployment.
To create a tag with embedded kernel boot options, use the following command:
maas $PROFILE tags create name='$TAG_NAME' \
comment='$TAG_COMMENT' kernel_opts='$KERNEL_OPTIONS'
For example:
maas admin tags create name='nomodeset_tag' \
comment='nomodeset_kernel_option' kernel_opts='nomodeset vga'
This command yields the following results:
Success.
Machine-readable output follows:
{
"name": "nomodeset_tag",
"definition": ",
"comment": "nomodeset_kernel_option",
"kernel_opts": "nomodeset vga",
"resource_uri": "/MAAS/api/2.0/tags/nomodeset_tag/"
}
You can check your work with a modified form of the listing command:
maas admin tags read | jq -r \
'(["tag_name","tag_comment","kernel_options"]
|(.,map(length*"-"))),(.[]|[.name,.comment,.kernel_opts])
| @tsv' | column -t
This should give you results something like this:
tag_name tag_comment kernel_options
-------- ----------- --------------
virtual
new_tag a-new-tag-for-test-purposes
pod-console-logging console=tty1 console=ttyS0
nomodeset_tag nomodeset_kernel_option nomodeset vga
How to use resource pools
How to add a resource pool
To add a resource pool:
-
Select Organisation > Pools.
-
Select Add pool.
-
Give your new pool a name.
-
Optionally, give your new pool a description.
-
Select Save pool to register the changes.
How to delete a resource pool
To delete a resource pool:
-
Select Organisation > Pools.
-
Select the trash can icon to the far right of the pool row.
-
Select Delete.
The pool will be deleted; there is no confirmation dialogue.
When you delete a resource pool, no machines will be deleted: All machines that belong to that resource pool will return to the default pool.
How to add a machine to a resource pool
To add a machine to a resource pool:
-
Select Machines.
-
Checkbox the machine(s) you want to add to the resource pool.
-
Select Categorise > Set pool….
-
Choose Select pool.
-
Select the desired resource pool from the Resource pool drop-down.
-
Alternatively, you can choose Create pool and create a new pool to add to the machine(s).
-
Register your changes by clicking Set pool….
How to remove a machine from a resource pool
To remove a machine from a resource pool, follow the procedure for adding a machine to a resource pool, but select “default” as the new resource pool. This action will return the machine to the default resource pool.
How to add a VM host to a resource pool
You can add a VM host to a resource pool when you create a new VM host or you can edit a VM host’s configuration:
-
Select KVM > LXD.
-
Select the KVM you want to add to a resource pool.
-
Select KVM host settings.
-
Select the desired pool in the Resource pool drop-down.
-
Register your changes with Save changes.
How to remove a VM host from a resource pool
To remove a VM host from a resource pool, follow the same procedure you would use to add a VM host to a resource pool, selecting “default” as the new resource pool. This action will return the machine to the default resource pool.
How to add a resource pool
To add a resource pool:
-
From the machine list, click the top tab Resource pool.
-
Select Add pool.
-
Give your new pool a name.
-
Optionally, give your new pool a description.
-
Select Save pool to register the changes.
How to delete a resource pool
To delete a resource pool:
-
From the machine list, click the top tab Resource pool.
-
Select the trash can icon to the far right of the pool row.
-
Select Delete.
The pool will be deleted; there is no confirmation dialogue.
When you delete a resource pool, no machines will be deleted: All machines that belong to that resource pool will return to the default pool.
How to add a machine to a resource pool
To add a machine to a resource pool:
-
Select Machines.
-
Select the machine you want to add to the resource pool.
-
Select Configuration.
-
Select Edit in the Machine configuration block.
-
Select the desired resource pool from the Resource pool drop-down.
-
Register your changes by clicking Save changes.
How to remove a machine from a resource pool
To remove a machine from a resource pool, follow the procedure for adding a machine to a resource pool, but select “default” as the new resource pool. This action will return the machine to the default resource pool.
How to add a VM host to a resource pool
You can add a VM host to a resource pool when you create a new VM host or you can edit a VM host’s configuration:
-
Select KVM from the top tab bar.
-
Select the KVM you want to add to a resource pool.
-
Select KVM host settings.
-
Select the desired pool in the Resource pool drop-down.
-
Register your changes with Save changes.
How to remove a VM host from a resource pool
To remove a VM host from a resource pool, follow the same procedure you would use to add a VM host to a resource pool, selecting “default” as the new resource pool. This action will return the machine to the default resource pool.
How to create a resource pool
Here’s an example that demonstrates how to create a new resource pool named myresource.
maas $PROFILE resource-pools create name=myresource description="A new resource pool."
The description field is optional.
How to list available resource pools
maas $PROFILE resource-pools read
How to list a single resource pool
maas $PROFILE resource-pool read $RESOURCE_POOL_ID
How to update a resource pool
maas $PROFILE resource-pool update $RESOURCE_POOL_ID name=newname description="A new description."
The name and description fields are optional.
How to delete a resource pool
maas $PROFILE resource-pool delete $RESOURCE_POOL_ID
How to add a machine to a resource pool
maas $PROFILE machine update $SYSTEM_ID pool=$POOL_NAME
About customising deployed machines
How to enable hardware sync on a machine
MAAS hardware sync may leak the MAAS admin API token. You may need to rotate all admin tokens and re-deploy all machines that have hardware sync enabled. To find out whether this is an issue, and how to fix it, see the troubleshooting instructions for this problem.
To enable Hardware sync on a machine:
-
Select Machines.
-
Select a machine(s).
-
Select Actions > Deploy*.
-
Check Periodically synch hardware.
-
Select Start deployment….
Once you’ve enabled hardware sync, any changes you make to the physical device, or to the VM through the VM host, will show up in the appropriate page for the deployed machine as soon as the sync interval has passed.
How to view updates from hardware sync
To view updates from hardware sync:
-
Select Machines.
-
Select the machine in question.
Any changes to the machine’s hardware configuration will be updated on the next sync. The status bar at the bottom will show times for Last synced and Next sync. Updated BMC configuration and tags can also be viewed on the machine itself.
How to configure hardware sync interval
The hardware sync interval is configured globally in MAAS deployment settings.
How to enable hardware sync on a machine
MAAS hardware sync may leak the MAAS admin API token. You may need to rotate all admin tokens and re-deploy all machines that have hardware sync enabled. To find out whether this is an issue, and how to fix it, see the troubleshooting instructions for this problem.
To enable Hardware sync on a machine:
-
Select Machines.
-
Select a machine.
-
Select Take action >> Deploy*.
-
Check Periodically synch hardware.
-
Select Start deployment for machine.
Once you’ve enabled hardware sync, any changes you make to the physical device, or to the VM through the VM host, will show up in the appropriate page for the deployed machine as soon as the sync interval has passed.
How to view updates from hardware sync
To view updates from hardware sync:
-
Select Machines.
-
Select the machine in question.
Any changes to the machine’s hardware configuration will be updated on the next sync. The status bar at the bottom will show times for Last synced and Next sync. Updated BMC configuration and tags can also be viewed on the machine itself.
How to configure hardware sync interval
The hardware sync interval is configured globally in MAAS deployment settings.
How to enable hardware sync on a machine
MAAS hardware sync may leak the MAAS admin API token. You may need to rotate all admin tokens and re-deploy all machines that have hardware sync enabled. To find out whether this is an issue, and how to fix it, see the troubleshooting instructions for this problem.
To enable Hardware sync on a machine, deploy the machine from the command line, adding enable_hw_sync=true:
maas $PROFILE machine deploy $SYSTEM_ID osystem=$OSYSTEM distro_series=$VERSION enable_hw_sync=true
Once you’ve enabled hardware sync, any changes you make to the physical device, or to the VM through the VM host, will show up in the appropriate page for the deployed machine as soon as the sync interval has passed.
How to view updates from hardware sync
Hardware sync updates the machine’s blockdevice, interface and device sets on a periodic basis. These can be viewed with the CLI command:
maas $PROFILE machine read $SYSTEM_ID
The timestamps of the last time data was synced and the estimated next time the machine will be synced can be seen in the last_sync and next_sync fields respectively.
Note that MAAS version 3.2 introduces the capability to sync and update hardware configuration on deployed, running machines.