How to manage tags (snap/3.1/CLI)

[billwear]

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

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 look at tag management steps that are the same (or very similar) across all types of MAAS tags.

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.

How to create a tag

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

How to delete a tag

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.

How to update a tag

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

How to rebuild a tag

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"
}