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")]'
With the CLI, you can create a tag with the following command:
maas $PROFILE tags create name=$TAG_NAME comment='$TAG_COMMENT'
For example, depending upon your system configuration, you might type a command similar to this one:
maas admin tags create name="new_tag" comment="a new tag for test purposes"
When the command is successful, you should see output similar to this:
Success.
Machine-readable output follows:
{
"name": "new_tag",
"definition": "",
"comment": "a new tag for test purposes",
"kernel_opts": "",
"resource_uri": "/MAAS/api/2.0/tags/new_tag/"
}
You can verify your work by listing all the tags on this MAAS.
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
With the CLI, you can delete a tag with the following command:
maas $PROFILE tag delete $TAG_NAME
For example, depending upon your system configuration, you might type a command similar to this one:
maas admin tag delete how-to-tag-machines.htmlo
When the command is successful, you should see output similar to this:
Success.
Machine-readable output follows:
Note that there is no actual “Machine-readable output” produced by this command, in most cases. Also note that remove a tag removes it from any nodes where you may have assigned it, but does not affect those nodes in any other way.
You can check your work by listing all the tags on this MAAS.
You can update a tag (e.g., a tag comment) like this:
maas $PROFILE tag update $TAG_NAME comment='$TAG_COMMENT'
For example:
maas admin tag update new_tag comment="a-new-tag-for-test-purposes"
This should return an output similar to this one:
Success.
Machine-readable output follows:
{
"name": "new_tag",
"definition": "",
"comment": "a-new-tag-for-test-purposes",
"kernel_opts": "",
"resource_uri": "/MAAS/api/2.0/tags/new_tag/"
}
You can always verify by listing all the tags on this MAAS.
How to list all tags available on this MAAS
You can list all tags that currently exist in this MAAS with a command of the form:
maas $PROFILE tags read | jq -r '(["tag_name","tag_comment"]|(.,map(length*"-"))),(.[]|[.name,.comment]) | @tsv' | column -t
For example:
maas admin tags read | jq -r '(["tag_name","tag_comment"]|(.,map(length*"-"))),(.[]|[.name,.comment]) | @tsv' | column -t
Your output might look like this:
tag_name tag_comment
-------- -----------
virtual
new_tag a-new-tag-for-test-purposes
If you need to update tags for all machines – without having to recommission them – you can accomplish this with the rebuild command:
maas $PROFILE tag rebuild $TAG
This command automatically applies the tag to all machines regardless of state, even machines that are actively deployed. For example:
maas admin tag rebuild virtual
This command would produce output similar to the following:
Success.
Machine-readable output follows:
{
"rebuilding": "virtual"
}