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

How to annotate machines

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

This subsection will help you learn:

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

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