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.
This article will help you learn:
How to work with static annotations
This subsection will help you learn:
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
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@how-to-annotate-machines.htmlo.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