How to tag machines
Tags for different objects have similar purposes, but they aren’t necessarily administered in the same way – so we’ve included detailed articles for each tag type. That said, many of the common operations regarding tags are performed in the same way. This article will present some general, explanatory information, and then look at tag management steps that are the same (or very similar) across all types of MAAS tags.
When working with tags, there are some universal rules you need to follow:
- Tag names can include any combination of alphabetic letters (a-zA-Z), numbers (0-9), dashes (-) and underscores (_).
- Tag names can be a maximum of 256 characters in length.
- Tag names cannot include spaces.
In general, names that do not conform to these rules cannot be created.
Automatic tags are tags with a definition. The definition allows you to auto-apply tags to machines that match with an XPath expression you created. Setting up an automatic tag will help you recognise special hardware characteristics and settings. For instance, we can configure the gpu passthrough by creating an XPath expression that recognises a prospective GPU, as shown in the example below.
In our REST API, a tag has 4 attributes namely, name, definition, kernel options, and comment. The example below shows you how to fill in the definition attribute to create an automatic tag. In this case, we are tagging all machines that have Intel VT-d enabled and have a Tesla v100 PCIe 16GB GPU:
When this tag is created, our REST API will try to match all machines with this definition and automatically apply the gpgpu-tesla-v-100 tag to those machines. Every time a new machine is discovered in your MAAS, if new machines match this definition, they will be automatically tagged as well.
MAAS automatic tags accept XPath expressions in the definition attribute of the tag. XPath expressions are evaluated against lshw‘s XML output; they are used to locate elements or attributes of the XML document for use in configuring automatic tags. You can use the lshw output in the hardware configuration details of a machine in MAAS and use that to create an XPath expression.
Hardware configuration information
You can download your HW configuration information in the XML format by going to the machine details page of any allocated or deployed machines. Choose Logs >> Installation output >> Download >> Machine output (XML) to capture these details:
You can learn more about these attributes↗ if desired. Note that:
- Size and capacity can have various meanings depending on the device
- The size of a node is always equal to its capacity
- Serial refers to the device’s serial number, but is used to report the MAC address for network devices, GUID for disk partition.
You can also find device classes from the same sources:
Capabilities are used to report features of a given node. The exact meaning of each feature depends on the type of node. It can be the presence of an arithmetical co-processor for a CPU, the ability to run at 1GB/s for a network interface, etc. In most cases, capabilities reported by lshw are auto-documented.
To see the capabilities of a specific machine, you can download your HW configuration information, as described above.
You can add kernel options when creating both manual and automatic tags. Kernel options will be automatically applied at boot time or when the machine with that tag is commissioned or deployed.
When updating kernel options on a tag that matches Deployed machines, be aware that the new kernel option will be applied during boot time, so you will need to release and re-deploy them to pick up the change. Otherwise, these deployed machines will have the old kernel options.
If there are multiple tags associated with a machine, the kernel options will be concatenated from all the tags combined, sorted alphabetically .
You can create an automatic tag by going to the Tag tab and click Create new tag. A tag is considered automatic when the definition field is filled with an XPath expression. The current version of our UI will only validate if your XPath expression is valid or not, but it will not show you which machines it will apply to before you create the tag.
Here is a thumbnail sketch of how automatic tags work:
When you choose to create a new tag, you are presented with a screen similar to this one:
While creating the tag, you also have an option to add kernel options to an automatic tag. Bear in mind that if a machine has multiple tags, it will be tagged alphabetically and the kernel option from the last tag will be applied to that machine.
Once an automatic tag is created the screen will initially show that 0 machines are tagged. That is because MAAS is running a background task to auto-apply the tag to matching machines. It can take some time to see that the number of machines tagged is populating.
NOTE: Kernel options will be applied at boot time. So by default kernel options will not be applied to any machines until they are deployed. If machines are deployed before they are tagged, the kernel option will be applied when these machines are redeployed.
How to update the definition of a tag
To update the definition for the automatic tag, go to the ‘Tag’ tab and click the edit icon:
This will open up the form and allow you to make changes in edit mode:
If the new definition is not a valid XPath expression, MAAS will generate an error:
Keep in mind that when a new definition is updated, MAAS will re-tag all the machines that match with the new definition. This can take some time, since it is a background process.
How to update the kernel option on a Tag
Kernel options can exist for both manual and automatic tags. However, they will be applied during boot time (commissioning and deploying). To update the kernel options, go to the ‘Tag’ tab and click the edit icon. Update the text area in the kernel option in this form:
NOTE: If the tagged machines are deployed, the updated kernel option won’t apply until the machines are redeployed. We suggest that you release those machines prior to the update, then redeploy those machines when the kernel options of the tag are updated.
How to unassign tags from machines
There are two ways to unassign tags. In the machine listing page, select all machines that you would like to unassign the tag then click ‘Tag’. A tag form is open. In the first field, ‘Tags’, click the x icon on the chip component to unassign the tags:
Click “Remove” to unassign a tag:
The numbers prescribed in the chip indicate the number of selected machines associated with that tag. You may click on the chip to view its information. After unassigning, click save to confirm the changes.
NOTE: Automatic tags cannot be unassigned manually. You can either update or delete automatic tags.
You can also unassign tags individually by going to the configuration tab on the machine details page; click the “X” icon to unassign the tag:
You may reassign the tag by typing or clicking on the text field to see existing tags. Note that the tag will be assigned to all selected machines.
To see how many nodes (Machines, controllers, devices) are tagged, search for GRUB_CMDLINE_LINUX_DEFAULT in the “Installation output” tab of the machine details page. That log should stay around for the lifetime of the deployment of the machine. The log gets overwritten when you redeploy the machine. For example:
GRUB_CMDLINE_LINUX_DEFAULT="sysrq_always_enabled dyndbg='file drivers/usb/* +p' console=tty1 console=ttyS0"
Tag definition reference examples
Here are some examples of tag definitions – more examples are available↗.
Commonly used Xpath functions usually include:
- contains
- starts-with
- ends-with
Example 1
This definition will identify machines with proper CPU tags, cores, and RAM, and tag them as a hypervisor:
This example looks for at least 40 cores and 256 GB of RAM and has all the required CPU features for being a hypervisor for both Intel and AMD.
NOTE: Don’t forget to adjust cores and RAM (in bytes) to suit your particular needs and available resources.
You can also define this tag with the CLI:
maas ${MAAS_PROFILE} tags create name=hypervisor \
definition='//node[@id="memory"]/size >= "274877906944" and \
//node[@id="cpu"]/configuration/setting/id="cores" >= 40 and \
//node[@id="cpu"]//capabilities/capability/@id = "vmx" or @id="svm" and \
//node[@id="cpu"]//capabilities/capability/@id = "aes" and
//node[@id="cpu"]//capabilities/capability/@id = "flexpriority" and
//node[@id="cpu"]//capabilities/capability/@id = "tpr_shadow" and
//node[@id="cpu"]//capabilities/capability/@id = "ept" and
//node[@id="cpu"]//capabilities/capability/@id = "vpid" and
//node[@id="cpu"]//capabilities/capability/@id = "vnmi"'
Example 2
This will tag UEFI enabled KVM VMs running on AMD-based servers:
You can also do this with the CLI:
maas ${MAAS_PROFILE} tags create \
name=kvm-amd-uefi \
definition='//node[@class="system"]/vendor = "QEMU" and //node[@id="firmware"]/capabilities/capability/@id = "virtualmachine" and //node[@id="firmware"]/capabilities/capability/@id = "uefi" and //node[@class="processor"]/vendor[starts-with(.,"Advanced Micro Devices")]' \
kernel_opts='nomodeset console=tty0 console=ttyS0,115200n8 amd_iommu=on kvm-amd.nested=1 kvm-amd.enable_apicv=n kvm.ignore_msrs=1' \
comment='Tag for automatically identifying AMD-based KVM vms (UEFI BIOS)'
Example 3
This will automatically tag servers that have NVME controllers:
To accomplish the same thing in the CLI:
maas ${MAAS_PROFILE} tags create name=NVME comment="xpath tag for automatically tagging servers that have NVME controllers" definition='//node[@id="storage" and @class="storage"]/description = "Non-Volatile memory controller"'
Example 4
This will tag servers with Mellanox ConnectX-5 NICs:
And you can also do this in the CLI:
maas ${MAAS_PROFILE} tags create \
name=connectx-5 \
definition='//node[@class="network"]/vendor[starts-with(.,"Mellanox")] and //node[@class="network"]/product[contains(.,"ConnectX-5")]' \
comment='Tag for automatically identifying servers with Mellanox Technologies ConnectX-5 cards'
Example 5
This will enable GPU passthrough for Nvidia Quadro K series GPUs on AMD:
You can also duplicate this example in the CLI:
maas ${MAAS_PROFILE} tags create \
name=gpgpu-quadro-k-a \
comment="Enable passthrough for Nvidia Quadro K series GPUs on AMD" \
definition='//node[@id="cpu:0"]/capabilities/capability/@id = "svm" and //node[@id="display"]/vendor[contains(.,"NVIDIA")] and //node[@id="display"]/description[contains(.,"3D")] and //node[@id="display"]/product[contains(.,"Quadro K")]'
In the MAAS UI, creating and assigning tags is a combined operation; that is, you create tags as you assign them, rather than creating them first. Creating tags in the UI is a little different user experience: there is a self-loading completion menu that collects all tags of a similar type. This completion menu helps you avoid misspelling tags when entering them more than once; otherwise, you might not be able to group and filter tags properly. It also makes tag entry more efficient.
To remove a tag only from specific machines, go to the machine list and select the machines from which you want to remove that tag. Choose the “Take action” button and select the “Tag” option:
On the screen that follows, enter the name of the new tag in the tag name box, without spaces:
A modal dialog pops up, giving you the opportunity to enter a name, comments, and kernel options for the new tag:
Select “Create and add to tag changes”; you will be returned to the previous screen, with a special row labeled “To be added”:
If the tag to be added looks correct, select “Save” to save and implement your changes.
You have two choices when it comes to eliminating tags from machines in your MAAS instance: you can delete them from all machines, or simply remove them from specific machines.
Deleting tags from all machines at once
To delete tags from all machines at the same time, go to the “Tags” tab in the machine list and click the trash can icon next to the tag you’d like to delete:
A confirmation screen will pop up, warning you that you are about to remove the tag from all machines. To confirm your choice, select the “Delete” button, or cancel if you change your mind:
The tag will be deleted from the system altogether, and removed from every machine to which it was assigned.
Removing a tag from specific machines
To remove a tag only from specific machines, go to the machine list and select the machines from which you want to remove that tag. Choose the “Take action” button and select the “Tag” option:
NOTE: You may not remove automatic tags using this screen.
Click the trash can icon (“Remove”) next to the tags you with to remove from these particular machines:
The tag will be removed from the selected machines.