About tags and annotations (snap/3.0/UI)

2.9 3.0 3.1
DEB CLI ~ UI CLI ~ UI CLI ~ UI
SNAP CLI ~ UI CLI ~ UI CLI ~ UI

Tags are short, descriptive, searchable words that can be applied to various MAAS objects, including:

  • machines (physical and virtual)
  • VM hosts
  • controllers (rack and region)
  • storage (virtual and physical; block devices or partitions)
  • network interfaces
  • devices
  • nodes (in the CLI only)

Tags serve to help you identify, group, and find objects easily, especially when you routinely deploy hundreds of machines.

Annotations are descriptive, searchable phrases that apply only to machines. There are two types of annotations: static (always present in any machine state), and dynamic (only present in allocated or deployed states). Annotations help you identify, characterise, and inform others about your machines.

This article will show you how to:

All headings have been hyperlinked for easy bookmarking. Note that not all functions for tags and annotations can be accessed via one interface (UI/CLI), so you will occasionally encounter cross-links.

Work with tags

This section is devoted to procedures for working with tags. We begin with some general operations that apply to all tag types, such as naming conventions and basic mechanics. We then walk through the various tag types, providing procedures that will help you create, assign, remove, delete, list, view, and filter tags, covering the nuances of each type.

Specifically, this section will show you how to:

Tags for these different objects have similar purposes, but they aren’t necessarily administered in the same way – so we’ve included detailed sections for each tag type.

Work with tags in general

There are a few general procedures for working with tags, centred around naming conventions and basic mechanics. These procedures apply to nearly all tag types. They will be referenced often in the subsections that follow.

As a general rule, you’ll want to know how to:

Name tags

When working with tags, there are some universal rules you need to follow:

  1. Tag names can include any combination of alphabetic letters (a-zA-Z), numbers (0-9), dashes (-) and underscores (_).
  2. Tag names can be a maximum of 256 characters in length.
  3. Tag names cannot include spaces.

In general, names that do not conform to these rules cannot be created.

Create and assign tags

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:

  1. Place the cursor in the “Tags” box, wherever it is located on the screen, and type the name of the new tag:

  1. Hit 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.

  1. When you’re done, click on the appropriate completion button to complete the operation.

The tag you just entered will now be added to the tag auto complete list, in alphabetical order, for re-use with other machines.

Delete and remove tags

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:

  1. Find the “Tags” box, wherever it is located on the screen:

  1. Click the “X” next to the tag you wish to remove.

  2. When you’re done, click on the appropriate completion button to complete the operation.

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.

Work with machine and VM tags

This subsection will show you how to:

Create and assign machine tags to machines

If you want to create a new tag, and simultaneously assign it to a machine, use the following steps:

  1. Go to the machine list and select the machine you’re interested in modifying, by checking the box next to the machine name:

  1. Select the “Take action” drop-down menu and select “Tag”:

  1. Create and/or assign the desired tag, as described in the general tagging procedure above.

  2. Don’t forget to hit the “Tag machine” button when you’re done, to apply your changes to the machine.

Tagging multiple machines at once

In the first step of the above procedure, you can select more than one machine:

Any tags you add in the “Tags” box will be applied to all selected machines, as noted by the change in the “Tag machine” button:

Other than the scope of the transaction (e.g., tagging three machines, in this case), everything else about this operation conforms to the general tag assignment procedure.

Remove and delete machine tags from machines

To remove machine tags from a machine:

  1. View a machine’s currently assigned tags: stay on the ‘Machines’ page and click on the machine in question. MAAS will display currently-assigned tags in the Tags pane of the ‘Machine summary’.

  2. Select the ‘Configuration’ tab and then the ‘Edit’ button alongside ‘Machine configuration’ to edit tags:

  3. Follow the general tag removal procedure.

List machine tags for multiple machines

In the MAAS UI, you don’t explicitly list all machine tags; instead, you filter by them using the “Filter by” drop-down. This filtered list does not distinguish between virtual machines (VMs) and physical machines, unless you’ve assigned tags to help with that distinction.

Of course, if you need to do so, you can see a list of all the tags assigned to machines by opening the “tags” section of the filter drop-down. With the UI, you can’t see a list of tags assigned to all virtual machine hosts (VM hosts), or filter VM hosts by tag. It is possible to get a more comprehensive list of machine tags and retrieve a list of VM host tags using the CLI; choose the CLI link from the menu on the top of this page to explore these options.

Here’s how you can filter the machine list by machine tags, using the MAAS UI:

  1. To list all tags, visit the ‘Machines’ tab and expand the ‘Tags’ subsection in the left pane. In this view, you can use tags as machine search filters.

  2. Select one or several tags. The machines that satisfy all selected tags will display on the right pane. Notice there is a search field at the top of the right pane. You can type a search expression into this field.

Below, tag ‘virtual’ has been selected (with the mouse), and the search field automatically reflects this. Five machines satisfy this search filter.

Remove a tag from the search filter by either hitting the ‘x’ character alongside a tag or editing the search expression.

View machine tags for one machine

To view the tags assigned to a specific machine, use the following procedure:

  1. On the machine list, select the machine of interest by clicking on its name.

  2. On the machine detail screen that comes up, look for the tags on one of the cards presented there: the tags for that machine should be listed there.

View machine tags for a VM host

To view the machine tags assigned to a VM host, here’s the procedure you’ll follow:

  1. Click on the KVM tab at the top of the screen. This will bring you to a list of active KVMs for your system:

  1. On the detail screen that comes up, choose the “Settings” tab at the top:

  1. In the settings tab, you’ll see a box labelled “Tags.” You can use this box to view, assign, edit, or remove tags for the KVM:

Note that you can only see the tags for a VM host in the same place that you change it. For a more comprehensive list of VM host tags, use the MAAS CLI.

Work with controller tags

This subsection will show you how to:

Create and assign controller tags

To create and assign a controller tag, you can use the following procedure:

  1. Click on the “Controllers” tab to open the controllers page:

  1. Click on the hyperlinked name of the controller to which you want to assign tags. You will see a screen with several cards, like this one:

  1. Find the “Tags” card and click on “Edit.” You will be brought to that controller’s “Configuration” tab.

  2. Click on the “Edit” button for “Controller configuration.”
    You’ll be presented with an editing screen similar to this one:

  1. Follow the general procedure to assign a tag to the controller.

Remove and delete controller tags

To remove (and possibly delete) a controller tag, you can use the following procedure:

  1. Click on the “Controllers” tab to open the controllers page:

  1. Click on the hyperlinked name of the controller to which you want to assign tags. You will see a screen with several cards, like this one:

  1. Find the “Tags” card and click on “Edit.” You will be brought to that controller’s “Configuration” tab.

  2. Click on the “Edit” button for “Controller configuration.”
    You’ll be presented with an editing screen similar to this one:

  1. Follow the general procedure to remove a tag from the controller.

List controller tags

There is no explicit means of listing tags for all controllers in the MAAS UI; see the in the MAAS CLI to do this, by choosing the CLI link from the menu on the top of this page. If you click on a tag assigned to a controller, though, you will see a filtered list of machines with that matching tag.

View controller tags

To view a list of tags assigned to a particular controller, you can use the following procedure:

  1. Click on the “Controllers” tab to open the controllers page:

  1. Click on the hyperlinked name of the controller of interest… You will see a screen with several cards, like this one:

  1. Find the “Tags” card; this card will list all the tags assigned to this controller.

Work with block device tags

In the parlance of MAAS, a block device is generally an unassigned and unpartitioned physical or virtual disk. This subsection will show you how to:

Create and assign block device tags

In order to create and assign tags to a block device, the device has to be in an “available” state, with no active partitions. To create and assign tags to block devices:

  1. Go to the machine list:

  1. Select that machine that has the block-device you want to tag:

  1. Click on the “Storage” tab and focus on the block labelled “Available disks and partitions:”

  1. Click the drop-down arrow at the right end of the row containing the block device you want to tag. Choose the “Edit…” option (the wording may vary, e.g, “Edit physical…”). This will take you to an editing screen for that block device:

  1. Add tags as described in the general procedure.

  2. Be sure to click on the “Save” button when you’re done.

Remove and delete block device tags

In order to remove tags from a block device, the device has to be in an “available” state, with no active partitions. To remove and delete tags from a block devices:

  1. Go to the machine list:

  1. Select that machine that has the block-device with the tag you want to remove:

  1. Click on the “Storage” tab and focus on the block labelled “Available disks and partitions:”

  1. Click the drop-down arrow at the right end of the row containing the block device you want to tag. Choose the “Edit…” option (the wording may vary, e.g, “Edit physical…”). This will take you to an editing screen for that block device:

  1. Delete tags by clicking the “X” next to them, as described in the general procedure.

  2. Be sure to click on the “Save” button when you’re done.

List block device tags

There is no explicit way to list all block device tags in the UI; check the CLI version of this page for a more comprehensive procedure. You can list all storage links, though – block device and partition – by using the filter tool on the machine list. Here’s how:

  1. Go to the machine list:

  1. Select the “Filters” drop-down and open the section titled “Storage tags:”

Here you will see a list of all block device and partition tags currently assigned to machines in this MAAS. If you wish to filter the machine list by a given tag, just make sure that it’s checked (and other storage tags unchecked) in the filter list.

View block device tags

To view all tags associated with block devices on a given machine:

  1. Go to the machine list:

  1. Select that machine that has the block device that interests you:

  1. Click on the “Storage” tab and check the page for tags:

Work with partition tags

This subsection will show you how to:

List partition tags

There is no explicit way to list all partition tags in the UI; check the CLI version of this page (via the menu above) for a more comprehensive procedure. You can list all storage links (block device and partition) by using the filter tool on the machine list. Here’s how:

  1. Go to the machine list:

  1. Select the “Filters” drop-down and open the section titled “Storage tags:”

Here you will see a list of all block device and partition tags currently assigned to machines in this MAAS.

View partition tags

To view all tags associated with partitions on a given machine:

  1. Go to the machine list:

  1. Select that machine that has the block device that interests you:

  1. Click on the “Storage” tab and check the page for tags:

Work with network tags

This subsection will show you how to:

Create and assign network interface tags

To assign a tag to a network interface, use the following procedure:

  1. Go to the machine list and select the machine where that interface resides, by clicking on that machine’s name:

  1. Click on the “Network” tab:

  1. Choose the interface you’d like to tag, by selecting the checkbox next to its name:

The checkbox isn’t strictly needed to apply the tag, but it helps prevent you from choosing the wrong one when multiple interfaces are available.

  1. Select the drop-down under “ACTIONS” at the end of the row, and select “Edit Physical” to edit the parameters of the physical interface:

  1. Edit the “Tags” field as desired, as described in the general tagging procedure above.

  2. Be sure to select the “Tag machine” button to apply your changes to the interface for that machine.

Note that different machines may have the same physical interface name, but different MAC addresses, so it’s not typical that interface tags carry over from one machine to the next – so auto complete menus will be sparse or non-existent most of the time for these tag types.

Remove and delete network interface tags

To remove a tag from a network interface, use the following procedure:

  1. Go to the machine list and select the machine where that interface resides, by clicking on that machine’s name:

  1. Click on the “Network” tab:

  1. Choose the interface you’d like to un-tag, by selecting the checkbox next to its name:

The checkbox isn’t strictly needed to apply the tag, but it helps prevent you from choosing the wrong one when multiple interfaces are available.

  1. Select the drop-down under “ACTIONS” at the end of the row, and select “Edit Physical” to edit the parameters of the physical interface:

  1. Edit the “Tags” field as desired, as described in the general tagging procedure above.

  2. Be sure to select the “Tag machine” button to apply your changes to the interface for that machine.

Note that different machines may have the same physical interface name, but different MAC addresses, so it’s not typical that interface tags carry over from one machine to the next – so auto complete menus will be sparse or non-existent most of the time for these tag types.

View network interface tags

To view the tags associated with a network interface, use the following procedure:

  1. Go to the machine list and select the machine where that interface resides, by clicking on that machine’s name:

  1. Click on the “Network” tab:

  1. Choose the interface you’d like to see, by selecting the checkbox next to its name:

The checkbox isn’t strictly needed to apply the tag, but it helps prevent you from choosing the wrong one when multiple interfaces are available.

  1. Select the drop-down under “ACTIONS” at the end of the row, and select “Edit Physical” to edit the parameters of the physical interface:

  1. Be sure to cancel the operation when you’re done.

Note that different machines may have the same physical interface name, but different MAC addresses, so it’s not typical that interface tags carry over from one machine to the next.

Work with device tags

This subsection will show you how to:

Create and assign device tags

To add a tag to a device, follow this procedure:

  1. Select the “Devices” tab; it may be in a drop-down labelled “Hardware,” if your browser window is not very large:

  1. Select the device you’d like to tag, by clicking on its name:

  1. In the “Tags” card, select the “Edit” link, or choose the “Configuration” tab under the device name:

  1. Select the “Edit” button on the “Configuration” tab which comes up:

  1. Edit the “Tags” field, as explained in the general tagging procedure above.

  2. Be sure to hit the “Save changes” button to apply your changes to the device.

Remove and delete device tags

To remove a tag from a device, follow this procedure:

  1. Select the “Devices” tab; it may be in a drop-down labelled “Hardware,” if your browser window is not very large:

  1. Select the device you’d like to un-tag, by clicking on its name:

  1. In the “Tags” card, select the “Edit” link, or choose the “Configuration” tab under the device name:

  1. Select the “Edit” button on the “Configuration” tab which comes up:

  1. Edit the “Tags” field, as explained in the general tagging procedure above.

  2. Be sure to hit the “Save changes” button to apply your changes to the device.

List device tags

  1. Go to the device list:

  1. Select the “Filters” drop-down and open the section titled “Tags:”

Here you will see a list of all device tags currently assigned to devices in this MAAS.

View device tags

  1. Go to the device list:

  1. Select the device that has your interest by clicking on its name. A device summary will appear:

The “Tags” card on that screen with show you all the tags currently associated with this device.

Work with annotations

This section will explain how to:

Work with static annotations

This subsection will show you how to:

Create and assign static annotations

To create and assign static annotations (a note) to a machine, follow this procedure:

  1. Go to the machine list and click on the machine of interest:

  1. This will bring up a machine summary for that machine:

  1. Select “Configuration” and click the “Edit” button to the right of the “Machine configuration” section:

  1. Add free-form notes in the “Note” field, as desired.

  2. Click “Save changes” to update the machine’s configuration.

Delete static annotations

To delete static annotations (a note) from a machine, follow this procedure:

  1. Go to the machine list and click on the machine of interest:

  1. This will bring up a machine summary for that machine:

  1. Select “Configuration” and click the “Edit” button to the right of the “Machine configuration” section:

  1. Edit the free-form notes in the “Note” field, as desired.

  2. Click “Save changes” to update the machine’s configuration.

View static annotations

To view static annotations, you can follow this procedure:

  1. Go to the machine list and look at the machine of interest; you should see the first few characters of a note in the bottom half of the column marked “POOL/NOTE:”

  1. Click on the machine, which will bring up a machine summary for that machine. Switch to the configuration tab to see the full note:

Work with dynamic (workload) annotations

This subsection will show you how to:

View dynamic (workload) annotations for one machine

To view the dynamic (workload) annotations for one machine, do the following:

  1. Go to the machine list and select the machine of interest by clicking on its hyperlinked name.

  2. In the machine summary that comes up, look for the “Workload Annotations” card, in the lower, right-hand corner:

Filter on dynamic (workload) annotations

To filter machines by dynamic (workload) annotations, use the following procedure:

  1. Go to the machine list and select the “Filter” drop-down; open the “Workload” segment:

  1. Select one or more values from this list to filter the machine list by these workload annotations.