Using machine tags

Machine tags help you quickly tell machines apart

Errors or typos? Topics missing? Hard to read? Let us know!

Assign machine tags

If you want to create a new tag, and simultaneously assign it to one or more machines, use the following steps:

  1. Select Machines.

  2. Select the checkbox next to the machine(s) you want to tag.

  3. Select Categorise >> Tag.

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

  5. Select Save to register your changes.

If you want to create a new tag, and simultaneously assign it to one or more machines, use the following steps:

  1. Select Machines.

  2. Select the checkbox next to the machine(s) you want to tag.

  3. Select Take action >> Tag.

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

  5. Select Tag machine to register your changes.

You can assign tags to a physical or virtual machine with the following command:

maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID

For example:

maas admin tag update-nodes new_tag add=g6arwg

This returns something like the following:

Success.
Machine-readable output follows:
{
   "added": 1,
   "removed": 0
}

You can check your work by listing machine tags, like this:

maas admin machines read | jq -r \
'(["hostname","sysid","machine_tags"]
|(.,map(length*"-"))),(.[]|[.hostname,.system_id,.tag_names[]])
| @tsv' | column -t

This should yield output similar to the following:

hostname       sysid   machine_tags
--------       -----   ------------
divine-stork   8b3ypp  pod-console-logging  virtual
casual-prawn   4end6r  pod-console-logging  virtual
driven-teal    tgaat6  pod-console-logging  virtual
immune-beetle  43xand  pod-console-logging  virtual
good-osprey    napfxk  pod-console-logging  virtual
smart-hen      c4rwq7  pod-console-logging  virtual
boss-satyr     xn8taa  pod-console-logging  androko
golden-martin  8fxery  pod-console-logging  virtual
crack-guinea   qk4b3g  pod-console-logging  virtual
finer-leech    cy3dtr  pod-console-logging  virtual
free-mouse     gxtbq4  pod-console-logging  virtual
humble-bunny   srqnnb  pod-console-logging  virtual
wanted-muskox  ekw7fh  pod-console-logging  virtual
one-boa        by477d  pod-console-logging  virtual
great-urchin   srnx4g  pod-console-logging  virtual
ace-frog       g6arwg  pod-console-logging  virtual  barbar  farquar  new_tag
alive-marlin   gbwnfb  pod-console-logging  virtual
picked-parrot  am77wn  pod-console-logging  virtual
tough-kit      ke3wc7  pod-console-logging  virtual
legal-whale    8nq3mt  pod-console-logging  virtual
game-sponge    76pdc6  pod-console-logging  virtual
fun-ghoul      qxfm7k  pod-console-logging  virtual
aware-earwig   8m8hs7  pod-console-logging  virtual
chief-crane    7fapx7  pod-console-logging  virtual
select-tapir   4ascbr  pod-console-logging  virtual
on-slug        snfs8d  pod-console-logging  virtual
polite-llama   dbqd4m  pod-console-logging  virtual
frank-coyote   wcmk48  pod-console-logging  virtual
usable-condor  ed8hmy  pod-console-logging  virtual
still-imp      h6ra6d  pod-console-logging  virtual

Remove machine tags

To remove machine tags from a machine:

  1. Select Machines.

  2. Select the machine in question by clicking on its name.

  3. Check the Tags pane under Machine summary to confirm the tags applied to the machine.

  4. Select Edit.

  5. Follow the general tag removal procedure.

To remove machine tags from a machine:

  1. Select Machines.

  2. Select the machine in question by clicking on its name.

  3. Check the Tags pane under Machine summary to confirm the tags applied to the machine.

  4. Select Configuration >> Edit.

  5. Follow the general tag removal procedure.

You can remove a tag from a physical or virtual machine with this command:

maas $PROFILE tag update-nodes $TAG_NAME remove=$SYSTEM_ID

For example:

maas admin tag update-nodes new_tag remove=g6arwg

This would produce output similar to the following:

Success.
Machine-readable output follows:
{
    "added": 0,
    "removed": 1
}

A quick check to verify results should yield something like this:

hostname       sysid   machine_tags
--------       -----   ------------
ace-frog       g6arwg  pod-console-logging  virtual  barbar  farquar

Change tags for multiple machines

This functionality can only be accessed via the MAAS CLI.

You can simultaneously add and remove tags from multiple machines, as long as you are only modifying one tag, with a command like this one:

maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID1 add=$SYSTEM_ID2 remove=$SYSTEM_ID3

For example, to remove the tag “barbar” from machine “g6arwg,” but add it to machines “8fxery” and “by477d,” you could use a command like this:

maas admin tag update-nodes barbar add=8fxery add=by477d remove=g6arwg

This compound operation would yield a response similar to this:

Success.
Machine-readable output follows:
{
    "added": 2,
    "removed": 1
}

Again, verifying by checking the list of machine tags, we enter a command like this:

maas admin machines read | jq -r \
'(["hostname","sysid","machine_tags"]
|(.,map(length*"-"))),(.[]|[.hostname,.system_id,.tag_names[]])
| @tsv' | column -t

The resulting response looks something like this:

hostname       sysid   machine_tags
--------       -----   ------------
divine-stork   8b3ypp  pod-console-logging  virtual
casual-prawn   4end6r  pod-console-logging  virtual
driven-teal    tgaat6  pod-console-logging  virtual
immune-beetle  43xand  pod-console-logging  virtual
good-osprey    napfxk  pod-console-logging  virtual
smart-hen      c4rwq7  pod-console-logging  virtual
boss-satyr     xn8taa  pod-console-logging  androko
golden-martin  8fxery  pod-console-logging  virtual  barbar
crack-guinea   qk4b3g  pod-console-logging  virtual
finer-leech    cy3dtr  pod-console-logging  virtual
free-mouse     gxtbq4  pod-console-logging  virtual
humble-bunny   srqnnb  pod-console-logging  virtual
wanted-muskox  ekw7fh  pod-console-logging  virtual
one-boa        by477d  pod-console-logging  virtual  barbar
great-urchin   srnx4g  pod-console-logging  virtual
ace-frog       g6arwg  pod-console-logging  virtual  farquar
alive-marlin   gbwnfb  pod-console-logging  virtual
picked-parrot  am77wn  pod-console-logging  virtual
tough-kit      ke3wc7  pod-console-logging  virtual
legal-whale    8nq3mt  pod-console-logging  virtual
game-sponge    76pdc6  pod-console-logging  virtual
fun-ghoul      qxfm7k  pod-console-logging  virtual
aware-earwig   8m8hs7  pod-console-logging  virtual
chief-crane    7fapx7  pod-console-logging  virtual
select-tapir   4ascbr  pod-console-logging  virtual
on-slug        snfs8d  pod-console-logging  virtual
polite-llama   dbqd4m  pod-console-logging  virtual
frank-coyote   wcmk48  pod-console-logging  virtual
usable-condor  ed8hmy  pod-console-logging  virtual
still-imp      h6ra6d  pod-console-logging  virtual

List machine tags

In the MAAS UI, you don’t explicitly list all machine tags; instead, you filter by them using the “Filters” drop-down:

  1. Select Machines.

  2. Select the Filters drop-down.

  3. Select Tags in the drop-down.

  4. Select one or more tags by clicking on the tag name.

The machine list will automatically filter by (be limited to) the machines matching the selected tag(s).

Remove a tag from the search filter by either by deselecting it in the Tags section.

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.

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

  • 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.

  • 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.

To list machine tags for all physical and virtual machines, just enter a command similar to this one:

maas $PROFILE machines read | jq -r '(["hostname","sysid","machine_tags"]|(.,map(length*"-"))),(.[]|[.hostname,.system_id,.tag_names[]]) | @tsv' | column -t

For example:

maas admin machines read | jq -r \
'(["hostname","sysid","machine_tags"]
|(.,map(length*"-"))),(.[]|[.hostname,.system_id,.tag_names[]])
| @tsv' | column -t

This gives us a listing similar to this:

hostname       sysid   machine_tags
--------       -----   ------------
divine-stork   8b3ypp  pod-console-logging  virtual
casual-prawn   4end6r  pod-console-logging  virtual
driven-teal    tgaat6  pod-console-logging  virtual
immune-beetle  43xand  pod-console-logging  virtual
good-osprey    napfxk  pod-console-logging  virtual
smart-hen      c4rwq7  pod-console-logging  virtual
boss-satyr     xn8taa  pod-console-logging  androko
golden-martin  8fxery  pod-console-logging  virtual  barbar
crack-guinea   qk4b3g  pod-console-logging  virtual
finer-leech    cy3dtr  pod-console-logging  virtual
free-mouse     gxtbq4  pod-console-logging  virtual
humble-bunny   srqnnb  pod-console-logging  virtual
wanted-muskox  ekw7fh  pod-console-logging  virtual
one-boa        by477d  pod-console-logging  virtual  barbar
great-urchin   srnx4g  pod-console-logging  virtual
ace-frog       g6arwg  pod-console-logging  virtual  farquar
alive-marlin   gbwnfb  pod-console-logging  virtual
picked-parrot  am77wn  pod-console-logging  virtual
tough-kit      ke3wc7  pod-console-logging  virtual
legal-whale    8nq3mt  pod-console-logging  virtual
game-sponge    76pdc6  pod-console-logging  virtual
fun-ghoul      qxfm7k  pod-console-logging  virtual
aware-earwig   8m8hs7  pod-console-logging  virtual
chief-crane    7fapx7  pod-console-logging  virtual
select-tapir   4ascbr  pod-console-logging  virtual
on-slug        snfs8d  pod-console-logging  virtual
polite-llama   dbqd4m  pod-console-logging  virtual
frank-coyote   wcmk48  pod-console-logging  virtual
usable-condor  ed8hmy  pod-console-logging  virtual
still-imp      h6ra6d  pod-console-logging  virtual

View machine tags

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

  1. Select Machines.

  2. Select the machine of interest by clicking on its name.

  3. Select Configuration.

  4. Scroll down to the Tags section.

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

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

  • 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.

To view tags for one physical or machine, you can enter a command like this:

maas $PROFILE machine read $SYSTEM_ID | jq -r '(["hostname","sysid","machine_tags"]|(.,map(length*"-"))),([.hostname,.system_id,.tag_names[]]) | @tsv' | column -t

For example:

maas admin machine read 8fxery | jq -r \
'(["hostname","sysid","machine_tags"]
|(.,map(length*"-"))),([.hostname,.system_id,.tag_names[]])
| @tsv' | column -t

Typical output from this command might look like this:

hostname       sysid   machine_tags
--------       -----   ------------
golden-martin  8fxery  pod-console-logging  virtual  barbar

Discover your virtual machine host ID

This functionality is available only through the MAAS CLI.

If you don’t know your VM host ID, you can discover it with this command:

maas $PROFILE vmhosts read \
| jq -r '(["vm_host_name","id"]
|(.,map(length*"-"))),(.[]|[.name,.id])
| @tsv' | column -t

For example:

maas admin vmhosts read \
| jq -r '(["vm_host_name","id"]
|(.,map(length*"-"))),(.[]|[.name,.id])
| @tsv' | column -t

This should produce output similar to the following:

vm_host_name      id
------------      --
my-lxd-vm-host-1  1

Assign tags to a VM host

This functionality is available only through the MAAS CLI.

To assign a tag to a virtual machine host, enter the following command:

maas $PROFILE vmhost add-tag $VMHOST_ID	tag=$TAG_NAME

If you don’t know the ID of your VM host, you can look it up beforehand.

As an example of assigning a tag to a VM host:

maas admin vmhost add-tag 1 tag=virtual

If it worked, this should return Success, followed by the JSON that describes the VM host. You can check your work by listing all VM host tags.

Remove VM host tags

This functionality is available only through the MAAS CLI.

To remove a tag from a virtual machine host, enter the following command:

maas $PROFILE vmhost remove-tag $VMHOST_ID tag=$TAG_NAME

If you don’t know the ID of your VM host, you can look it up beforehand.

As an example of removing a tag from a VM host:

maas admin vmhost remove-tag 1 tag=virtual

If it worked, this should return Success, followed by the JSON that describes the VM host. You can check your work by listing all VM host tags.

List VM host tags

This functionality is available only through the MAAS CLI.

You can list tags for all VM hosts with the following command:

maas $PROFILE vmhosts read | jq -r '(["vm_host_name","id","tags"]|(.,map(length*"-"))),(.[]|[.name,.id,.tags[]]) | @tsv' | column -t

For example:

maas admin vmhosts read | jq -r '(["vm_host_name","id","tags"]|(.,map(length*"-"))),(.[]|[.name,.id,.tags[]]) | @tsv' | column -t

This should yield output similar to the following:

vm_host_name      id  tags
------------      --  ----
my-lxd-vm-host-1  1   morkopongo  pod-console-logging  virtual

View VM host tags

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

  1. Under KVM, select the type of VM host you’re investigating.

  2. Select a VM host by clicking on its name.

  3. Select KVM host settings.

  4. You can view, edit, add, or delete tags in the Tags box.

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.

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

  1. Select KVM.

  2. Select a VM host by clicking on its name.

  3. Select KVM host settings.

  4. You can view, edit, add, or delete tags in the Tags box.

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.

If you want to list the tags for just one VM host, you can use a command like this one:

maas $PROFILE vmhost read $VMHOST_ID \
| jq -r '(["name","id","tags"]
|(.,map(length*"-"))),([.name,.id,.tags[]])
| @tsv' | column -t

If you don’t know the ID of your VM host, you can look it up beforehand.

As an example of viewing tags for one VM host:

maas admin vmhost read 1 | jq -r '("name","id","tags"]|(.,map(length*"-"))),([.name,.id,.tags[]]) | @tsv' @ column -t

Typical output might look something like this:

name              id  tags
----              --  ----
my-lxd-vm-host-1  1   morkopongo  pod-console-logging

Last updated 16 days ago.