Caltech Library logo

clasm

Go TUI (clasm) with scriptable command-line support for administering Caltech Library DLD’s AWS EC2 instances, AMIs, launch templates, and key pairs, plus S3 buckets and backup archives, IAM roles/instance profiles/policies, and Invenio RDM’s own SQL/OpenSearch backup and restore lifecycle, with cross-resource tag management and cloud-init inspection.

What it does

Run clasm for the menu. It is organised in domains, each a menu of its own:

Most actions also run without the menu. The command line mirrors the menu: clasm <domain> opens that domain’s menu, clasm <domain> <action> opens that one action’s prompts, and clasm <domain> <action> <arguments> runs it non-interactively and exits. Listings take -json and -jsonl:

clasm compute show-instances -json
clasm tag-management show-untagged -jsonl instance ami
clasm compute start-ec2-instance test-instance
clasm compute stop-ec2-instance -no-wait test-instance

The command line is experimental: names and JSON keys may still change. See docs/user_manual.md, “Non-interactive (CLI) Usage”, for every form.

Destructive actions and safeguards

Actions that destroy or replace something share one gate on the command line: a dry run by default that prints the plan and changes nothing, and --confirm <name> to run it. At a terminal, the same plan is followed by a type-the-name prompt.

Restoring an RDM database also checks where its files live. A restored database names the S3 buckets that hold its files (CaltechAUTHORS: the content bucket), and an instance that can write to one would write to production’s content. Restore SQL Backup reads the backup’s file locations first, asks IAM’s policy simulator whether the instance can write to each bucket, and refuses unless each writable one is named in a --confirm of its own. A read-only restore role, built with clasm, is never blocked:

clasm iam create-role-from-template --backup-bucket sql-backups.example.org \
  --key-prefix source-instance rdm-restore-source-read-only restore-source-test
clasm iam create-instance-profile restore-source-test restore-source-test
clasm compute associate-replace-iam-instance-profile test-instance restore-source-test
clasm rdm-backup-and-restore restore-sql-backup-from-s3 test-instance sql-backups.example.org source-instance latest

The last command is a dry run. Running it again with --confirm test-instance applies it.

Tagging

clasm adds the Origin tag to everything it creates in IAM, EC2 and S3 (never to S3 objects), so that what clasm manages can be told from the rest and found in a report. The key and the DLD-owned value come from origin_tag in ~/.clasm; with no dld_value set, nothing is added. To backfill what was there before:

clasm tag-management show-untagged -jsonl > untagged.jsonl
clasm tag-management tag-resource instance new-data --tag origin=dld

tag-resource adds a missing tag, does nothing if the value is already right, and refuses a different value (changing nothing) unless --replace is given.

Release Notes

See codemeta.json (releaseNotes) and the GitHub release page for the notes of each version. In short, v0.0.12 fixes the restore defect behind caltechauthors issue #185: Restore OpenSearch now installs the missing index templates, turns orphaned and plain audit-log and job-logs indices back into data streams, and runs a health check, and the three steps are also forms of their own (rdm-index-health, install-index-templates, convert-log-indices). v0.0.11 added the scriptable read-only restore role and instance-profile swap, start-ec2-instance and stop-ec2-instance (a stop of a production instance needs --confirm), the restore location guard with a repeatable --confirm, the Origin tag on everything clasm creates, and show-untagged and tag-resource for tagging the existing fleet.

Authors

Software Requirements

Software Suggestions