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