How to annotate machines

billwear · 2 February 2023 22:57

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.

Work with annotations

This article will help you learn:

How to work with static annotations
How to work with dynamic (workload) annotations

This section explains how to work with notes, also known as “static annotations”. MAAS 2.9 does not support dynamic annotations; these are only supported from MAAS version 3.0.

How to work with static annotations

This subsection will help you learn:

How to create and assign static annotations
How to delete static annotations
How to view static annotations
How to work with with dynamic (workload) annotations

How to create and assign static annotations

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

Go to the machine list and click on the machine of interest. This will bring up a machine summary for that machine.
Select “Configuration” and click the “Edit” button to the right of the “Machine configuration” section.
Add free-form notes in the “Note” field, as desired.
Click “Save changes” to update the machine’s configuration.

How to delete static annotations

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

Go to the machine list and click on the machine of interest. This will bring up a machine summary for that machine.
Select “Configuration” and click the “Edit” button to the right of the “Machine configuration” section.
Edit the free-form notes in the “Note” field, as desired.
Click “Save changes” to update the machine’s configuration.

How to view static annotations

To view static annotations, you can follow this procedure:

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”.
Click on the machine, which will bring up a machine summary for that machine. Switch to the configuration tab to see the full note.

How to work with dynamic (workload) annotations

This subsection will help you learn:

How to view dynamic (workload) annotations for one machine
How to filter on dynamic (workload) annotations

How to view dynamic (workload) annotations for one machine

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

Go to the machine list and select the machine of interest by clicking on its hyperlinked name.
In the machine summary that comes up, look for the “Workload Annotations” card, in the lower, right-hand corner.

How to filter on dynamic (workload) annotations

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

Go to the machine list and select the “Filter” drop-down; open the “Workload” segment.
Select one or more values from this list to filter the machine list by these workload annotations.

How to work with static annotations

This subsection will help you learn:

How to identify your machines
How to set a static annotation for a machine
How to change or clear a static annotation for a machine
How to list static annotations for all machines
How to view a static annotation for one machine

How to identify your machines

To identify your available machines, use a command like this one:

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

For example:

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

Typical output might look something like this:

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

How to set a static annotation for a machine

If you want to set the static annotation for a given machine, you can do so with a command that looks like this:

maas $PROFILE machine update $SYSTEM_ID description="$STATIC_ANNOTATION"

For example:

maas admin machine update ke3wc7 description="kilo-echo-3-whisky-charlie-7"

You can check your work by viewing the static annotations for one machine.

How to change or clear a static annotation for a machine

If you want to set the static annotation for a given machine, use the same command you’d use to set a static annotation:

maas $PROFILE machine update $SYSTEM_ID description="$STATIC_ANNOTATION"

The existing annotation will be overwritten by the new one you enter. For example:

maas admin machine update ke3wc7 description=""

You can check your work by viewing the static annotations for one machine.

How to list static annotations for all machines

To list static annotations for all machines, enter a command similar to this one:

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

For example:

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

Output might look something like this:

hostname       system_id  description
--------       ---------  -----------
driven-teal    tgaat6     tango-golf
humble-bunny   srqnnb     sierra-romeo
tough-kit      ke3wc7     kilo-echo

How to view a static annotation for one machine

To view a static annotation for one machine, try a command like this:

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

For example:

 maas admin machine read tgaat6 \
| jq -r '(["hostname","system_id","description"]
|(.,map(length*"-"))),([.hostname,.system_id,.description])
|@tsv' | column -t

A command like this might produce output as follows:

hostname     system_id  description
--------     ---------  -----------
driven-teal  tgaat6     tango-golf

How to work with dynamic (workload) annotations

This section will help you learn:

How to identify machines that can receive dynamic annotations
How to set dynamic annotations for a machine
How to clear and change dynamic annotations for a machine
How to list dynamic annotations for all machines
How to list dynamic annotations for one machine

How to identify machines that can receive dynamic annotations

You can only set dynamic annotations for machines that are in the “Allocated” or “Deployed” state. To identify which of your machines are in these states, you can execute the following command:

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

For example:

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

Output should look something like this:

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

How to set dynamic annotations for a machine

Dynamic annotations, otherwise known as “workload annotations” or “owner data,” can be used to keep track of the runtime status of machines that are allocated or deployed. These annotations are set using key=value pairs. You can set any key=value pair that you wish for any machine, although it’s probably more useful if you standardise your key names.

To set a dynamic annotation for a machine, you can enter a command like this:

maas $PROFILE machine set-owner-data $SYSTEM_ID $KEY=$VALUE

For example:

maas admin machine set-owner-data tgaat6 owner=gsmith@zorko.com

This command will return a JSON string representative of the machine’s new configuration, including the dynamic annotations you’ve added. You can check your work by listing the dynamic annotations for the one machine you just edited, or by listing dynamic annotations for all machines.

How to clear and change dynamic annotations for a machine

You can change dynamic annotations for a machine simply by executing a new set-owner-data command:

maas $PROFILE machine set-owner-data $SYSTEM_ID $KEY=$NEW_VALUE

You can clear a dynamic annotation by entering the empty string ("") as the $VALUE:

maas $PROFILE machine set-owner-data $SYSTEM_ID $KEY=""

These commands will return a JSON string representative of the machine’s new configuration, including the dynamic annotations you’ve changed or cleared. You can check your work by listing the dynamic annotations for the one machine you just edited, or by listing dynamic annotations for all machines.

How to list dynamic annotations for all machines

You can list the current dynamic annotations for all machines with a command like this:

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

For example:

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

This command output might look something like this:

hostname       system_id  owner_data
--------       ---------  ----------
divine-stork   8b3ypp
casual-prawn   4end6r
driven-teal    tgaat6     farquar     foobar
immune-beetle  43xand
good-osprey    napfxk
smart-hen      c4rwq7

How to list dynamic annotations for one machine

You can list the dynamic annotations for one machine by entering a command of the form:

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

For example:

maas admin machine read tgaat6 \
| jq -r '(["hostname","system_id","owner_data"]
|(.,map(length*"-"))),(.[]|[.hostname,.system_id,.owner_data[]])
|@tsv' | column -t

This will produce output similar to the following:

hostname     system_id  owner_data
--------     ---------  ----------
driven-teal  tgaat6     farquar     foobar

How to create and assign static annotations
How to delete static annotations
How to view static annotations

How to create and assign static annotations

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

Go to the machine list and click on the machine of interest. This will bring up a machine summary for that machine.
Select “Configuration” and click the “Edit” button to the right of the “Machine configuration” section.
Add free-form notes in the “Note” field, as desired.
Click “Save changes” to update the machine’s configuration.

How to delete static annotations

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

Go to the machine list and click on the machine of interest. This will bring up a machine summary for that machine.
Select “Configuration” and click the “Edit” button to the right of the “Machine configuration” section.
Edit the free-form notes in the “Note” field, as desired.
Click “Save changes” to update the machine’s configuration.

How to view static annotations

To view static annotations, you can follow this procedure:

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”.
Click on the machine, which will bring up a machine summary for that machine.
Switch to the configuration tab to see the full note.