systemslab infra tag

Description	Create and manage virtual tags: the job tags that the infrastructure manager launches EC2 instances for on demand.
Usage	systemslab infra tag <COMMAND> [OPTIONS]

Description

A virtual tag names an AMI, an EC2 instance type and a launch profile. When a job asks for a host with that tag, the infrastructure manager launches one. Tags are stored on the server, not in its config file.

Every change to a tag is kept as a numbered revision, recording who made it, when, and an optional comment. You can list the history, look at an old revision, and roll back to it. Tags are disabled rather than deleted, so a name is never reused.

Before a change is saved, the server checks it against AWS: the AMI must exist in the deployment's region and be available, its owner must be allowed by the launch profile, and the instance type must be offered in the region and run the AMI's architecture. If anything is wrong, nothing is saved and every problem is reported.

systemslab infra virtual-tag is accepted as an alias of systemslab infra tag.

Command	What it does
list [--all]	List tags. Disabled tags are left out unless you pass --all.
show <NAME> [--revision N]	Show a tag's launch fields, what AWS reported about its AMI, and its setup script.
history <NAME>	List every revision, newest first.
create <NAME> [FIELDS]	Create a tag at revision 1.
edit <NAME> [FIELDS] [--clear-*]	Change some fields. Fields without a flag keep their value.
rollback <NAME> --to <N>	Restore revision N's fields as a new revision.
disable <NAME> / enable <NAME>	Retire or restore a tag.
validate [FIELDS]	Check fields against AWS without saving anything. Exits non-zero if any are invalid.
profiles	List the launch profiles a tag can use.

list, history and profiles take the usual table flags (--no-header, --no-align, --field-separator, --record-separator).

Warm pools

Idle instances are kept for a while so the next job can reuse them. By default edit and rollback drain the tag's warm pool: idle instances launched from earlier revisions are terminated instead of reused, so later jobs get hosts with the new settings. Pass --keep-warm-pool to let them be reused, e.g. for a change that doesn't affect the hosts, like a higher instance cap.

Concurrent changes

edit, rollback, enable and disable read the tag's current revision and only save if it is still current. If someone else changed the tag in between, the command fails without saving and points at history; run it again. Pass --expected-revision N to save only if the tag is at revision N, e.g. the revision you inspected with show.

Output

In the default long output format, create, edit, rollback, enable and disable say what they saved and, for edit and rollback, print each changed field as field: old -> new. With --output-format short they print just <name> <revision>.

A note on --actor and identity

When the server knows who is signed in, it records that user as the author of each change and ignores --actor. Otherwise the author is the --actor value — by default operator:<your OS username> — which nothing verifies. Treat it as a record of a claim, not proof of who acted.

Examples

See which launch profiles exist, then create a tag:

systemslab infra tag profiles
systemslab infra tag create ec2-m5-large --launch-profile lab \
    --image ami-0123456789abcdef0 --instance-type m5.large \
    --max-instances 4 --setup-script setup.sh --comment "first cut"

Check an AMI before switching to it, then switch:

systemslab infra tag edit ec2-m5-large --image ami-0fedcba9876543210 --dry-run
systemslab infra tag edit ec2-m5-large --image ami-0fedcba9876543210

Raise the cap without terminating idle instances:

systemslab infra tag edit ec2-m5-large --max-instances 8 --keep-warm-pool

Remove the setup script:

systemslab infra tag edit ec2-m5-large --clear-setup-script

Undo a bad change:

systemslab infra tag history ec2-m5-large
systemslab infra tag rollback ec2-m5-large --to 2 --comment "AMI broke fio"

Retire a tag:

systemslab infra tag disable ec2-m5-large --comment "replaced by ec2-m7i-large"

Launch fields

create, edit and validate take these flags. create and validate require --image and --instance-type, and --launch-profile unless the server has exactly one launch profile. With edit, every flag is optional.

Option	Default	Description
--launch-profile <NAME>		The [infra.launch_profiles.<NAME>] entry in the server config, which sets the subnet, security groups, IAM role and SSH key. See systemslab infra tag profiles.
--image <AMI>		The AMI ID to launch, e.g. ami-0123456789abcdef0.
--instance-type <TYPE>		The EC2 instance type to launch, e.g. m5.large.
--market <MARKET>	unset (the global policy, auto)	auto (spot, escalating to on-demand for long or wide runs), spot or on-demand.
--max-instances <N>	unset (only the global cap applies)	The most instances of this tag that may run at once.
--spot-max-price <USD>	unset (the on-demand price is the cap)	The highest hourly spot price to pay, e.g. 0.25.
--volume-size <GiB>	unset (the AMI's own size)	The root EBS volume size.
--max-spot-duration <DURATION>	unset (the global threshold)	Expected run length above which this tag uses on-demand instead of spot, e.g. 2h or 90m.
--max-spot-hosts <N>	unset (the global threshold)	Host count above which this tag uses on-demand instead of spot.
--setup-script <PATH>	unset (no script)	A file holding a script that runs as root on each instance before the agent starts, or - for stdin. A script without a #! line runs under bash; if it exits non-zero the instance never registers. At most 16 KiB.

edit also takes --clear-market, --clear-max-instances, --clear-spot-max-price, --clear-volume-size, --clear-max-spot-duration, --clear-max-spot-hosts and --clear-setup-script, which reset that field to its default.

Change options

Option	Default	Description
--comment <TEXT>		A note about the change, kept in the tag's history. Taken by create, edit, rollback, disable and enable.
--actor <ACTOR>	operator:<current OS user>	Who is making the change. Ignored when the server knows the signed-in user. Caller-asserted, not authenticated — see the note above.
--keep-warm-pool		edit and rollback only: let idle instances launched from earlier revisions be reused.
--expected-revision <N>	the tag's current revision	edit, rollback, disable and enable: only save if the tag is still at revision N.
--dry-run		create and edit: check the fields against AWS (and, for edit, print what would change) without saving.

Common Options

Option	Default	Description
--systemslab-url		The URL at which to access the systemslab server.
--color	auto	Controls when color is used in the output. Possible values are auto, always, and never.
--output-format	long	Output format to use when outputting messages. long will result output designed to be human-readable while short is short output meant to be used within scripts.

Environment Variables

Variable	Description
SYSTEMSLAB_URL	Specify the URL used to contact the SystemsLab server. Equivalent to --systemslab-url.