There are several different tag types, all administered in similar fashion
Errors or typos? Topics missing? Hard to read? Let us know!
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:
In general, names that do not conform to these rules cannot be created.
How to download hardware configuration information
To download hardware configuration information in XML format:
Select Machines.
Select a machine which is allocated or deployed.
Select Logs >> Installation output >> Download >> Machine output (XML).
You can learn more about these attributes^ if desired. Note that:
You can also find device classes from the same sources.
MAAS 3.2 and above provide greatly expanded tagging capability (through the UI only). You can auto-apply tags to machines that match a custom XPath expression. Setting up an automatic tag lets you recognise special hardware characteristics and settings, e.g., the gpu passthrough.
Creating automatic tags with MAAS 3.4 UI
To create automatic tags:
Select Organisation > Tags.
Select Create new tag.
Enter the Tag name.
Optionally enter a Comment.
Optionally enter Kernel options.
Enter an XPath-based Definition. 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.
Select Save to register your changes.
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.
Pro tip: 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
Select Organisation > Tags.
Select the pencil icon on the right end of the tag's row.
Edit the Definition.
Select Save to register your changes.
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.
Creating automatic tags with MAAS 3.2 and 3.3, via the UI
To create automatic tags:
Select Machines.
Select Tags.
Select Create new tag.
Enter the Tag name.
Optionally enter a Comment.
Optionally enter Kernel options.
Enter an XPath-based Definition. 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.
Select Save to register your changes.
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.
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
Select Machines.
Select Tags.
Select the pencil icon on the right end of the tag's row.
Edit the Definition.
Select Save to register your changes.
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 options on a tag
To update the kernel options on a tag:
Select Machines.
Select Tags.
Select the pencil icon on the right end of the tag's row.
Edit the Kernel options.
Select Save to register your changes.
Kernel options can exist for both manual and automatic tags. However, they will be applied during boot time (commissioning and deploying).
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
To unassign tags from machines:
Select Machines.
Select the checkbox(es) next to the machine(s) you wish to untag.
Select Take action >> Tag. A table of tags appears at the top of the screen.
For each tag you wish to unassign, select Remove. The text will change to Discard with an X to the right.
If you want to undo a choice before saving, click the X to right of Discard to undo the proposed change.
When you're satisfied with your new tag configuration, select Save to finalize and register your choice(s).
Automatic tags cannot be unassigned manually. You can either update or delete automatic tags.
You can also unassign tags individually by going to Machines >> {machine-name} >> Configuration >> Tags >> Edit. The Tags table functions exactly the same as what's described above.
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"
Creating and assigning tags with MAAS 3.2 through 3.4, via the UI
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 create and assign a tag to specific machines:
Select Machines.
Select the checkbox next to the machines you wish to tag.
Select Take action >> Tag. A Tag dialogue will pop up at the top of the screen.
In the box labelled Search existing or add new tags, enter the name for your proposed tag (e.g., {tag-name}).
Select Create tag {tag-name}, under the Search... box. A modal dialogue box pops up; {tag-name} will automatically populate the Tag name field.
Optionally enter a Comment.
Optionally enter some Kernel options.
Select Create and add to tag changes. You will be returned to the previous screen; note that your changes have not yet been registered with MAAS.
If you wish to abandon this new tag without assigning it, select Discard X to the right of the new tag name. It will disappear from the list.
If you're happy with the new tag(s), select Save to apply your changes to the selected machines. You'll be returned to Machines.
You can confirm your changes by hovering over the Tags list in the Machines screen.
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:
Select Machines.
Select Tags.
Select the trash can icon to the right of the tag you'd like to delete. A warning dialogue will pop up at the top of the screen.
Select Delete.
The tag will be unassigned from all machines and deleted. There is no undo.
Removing a tag from specific machines
To remove a tag only from specific machines:
Select Machines.
Select the checkbox next to each machine from which you want the tag removed.
Select Take action >> Tag.
For each tag you wish to unassign, select Remove. The text will change to Discard with an X to the right.
If you want to undo a choice before saving, click the X to right of Discard to undo the proposed change.
When you're satisfied with your new tag configuration, select Save to finalize and register your choice(s).
Creating and assigning tags with MAAS 3.1 and below, via the UI
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.
The process for creating and assigning tags in the UI is generally the same for all tag types:
Place the cursor in the Tags box.
Type the name of the new tag.
Press the return key to add the new tag. The auto complete list will re-appear after you've entered the tag, in case you'd like to enter another tag.
When you're done, select the appropriate completion button to register your changes.
The tag you just entered will now be added to the tag auto complete list, in alphabetical order, for re-use with other machines.
With the MAAS UI, you remove tags, rather than explicitly deleting them. Tags are "deleted" when you have removed them from all machines.
To remove (unassign) a tag:
Find the Tags box.
Click the X next to the tag you wish to remove.
When you're done, select the appropriate completion button to register your changes.
Note that the tag you just removed will be deleted from the tag auto complete list when it is no longer assigned to any machines.
Creating tags via the CLI, all MAAS versions
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 zorko
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"
}