Offline docs (switch to live docs)                          Full          UI-only         CLI-only

CLI tag management

This document lists tag management tasks you can perform with the MAAS CLI.

Quick questions you may have:

Rudimentary tag creation

maas $PROFILE tags create name=$TAG_NAME

Tag creation and auto-assignment

When you supply a definition during a tag’s creation, MAAS automatically applies the tag o all the nodes that satisfy the definition:

maas $PROFILE tags create name=$TAG_NAME \
    comment='$TAG_COMMENT' definition='$TAG_DEFINITION'

For example,

maas $PROFILE tags create name='gpu' \
    comment='GPU with clock speed >1GHz for running CUDA type operations.' \
    definition='//node[@id="display"]/'clock units="Hz"' > 1000000000'

We recommend that each tag have a short name and a comment that adequately describes it. You should make sure to create both of these because they will help you identify and use the tag later.

Delete a tag

maas $PROFILE tag delete $TAG_NAME

List all tags

To list all tags present on the region controller:

maas $PROFILE tags read

List nodes/machines labelled with a tag

To list what nodes (or machines) a tag applies to:

maas $PROFILE tag nodes $TAG_NAME
maas $PROFILE tag machines $TAG_NAME

Juju integration

Although you can use a tag in the web UI (as a node search filter), you realise most of the benefit when you’re deploying applications with Juju.

For example, to use the ‘gpu’ tag to deploy a (hypothetical) service called ‘cuda’:

juju deploy --constraints tags=gpu cuda

You can also use multiple tags in addition to the normal Juju constraints:

juju deploy --constraints "mem=1024 tags=gpu,intel" cuda

Manual tag assignment

It is possible to assign tags to nodes manually by simply omitting the definition and applying the tag to a node by referencing its system id:

maas $PROFILE tags create name=$TAG_NAME comment='$TAG_COMMENT'
maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID

To remove a tag:

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

In the same operation, a tag can be added to some nodes and removed from others:

maas $PROFILE tag update-nodes $TAG_NAME \
    add=$SYSTEM_ID_1 add=$SYSTEM_ID_2 remove=$SYSTEM_ID_3

Hybrid tag assignment

You can also create a tag with a definition (thereby map to certain nodes), remove the definition (but retain the mapping), and then add the tag manually to specific nodes. This action is useful for hardware which is conceptually similar but does not all satisfy a single tag definition. Here are the commands you would use to do this:

maas $PROFILE tags create name=$TAG_NAME \
    comment='$TAG_COMMENT' definition='$TAG_DEFINITION'
maas $PROFILE tag update $TAG_NAME definition=''
maas $PROFILE tag update-nodes $TAG_NAME add=$SYSTEM_ID