Dormeto
ENFR
Menu

Docs

CLI

The dormeto command line does what the dashboard does, from a terminal. It covers every operation of the manager, for scripts, CI jobs and changes to many workloads at once. It signs its calls with your AWS profile.

14 min readManager 0.21.0

Connecting to the manager

CLI 0.7.0 has every command on this page (install it: Get started). Every command needs manager 0.15.0 or later. The guard of the last administrator needs manager 0.18.0.

Every command on this page is under dormeto aws, as the Google Cloud ones are under dormeto gcp. The CLI before aws had them at the top level, such as dormeto install and dormeto routers list. Those names still work, hidden from the help, with one line on stderr naming the new one. They go in a later release.

  • The CLI finds the manager's API by its name, dmt-<env>-manager-api, with your AWS profile.
  • --profile picks the profile, --region the manager's region and --env its environment, prod by default.
  • --api-url gives the API's URL instead: the module's api_endpoint output, not the dashboard's address.
  • whoami shows who the manager sees, with which role, and the manager's version.
dormeto aws whoami
dormeto aws whoami --profile ops --env dev --region eu-west-3

Targets

  • A router is its name: prod-eu.
  • A workload is <router>/<workload id>: prod-eu/w-1. Below, <targets> is one or more workloads.
  • --tag key=value selects every workload with that Dormeto tag instead. Repeat it to require several tags.
  • A discovery candidate is its target group's ARN, or the target group's name when no other candidate has it.
  • A user is an email, a group a name, an operation and an exclusion their id.
  • --region is always the manager's region. A router's region is --router-region, a candidate's --candidate-region.

Confirmations

  • A change to several workloads or routers asks for a confirmation on a terminal. The question names the targets: a change to workloads lists them first.
  • These always ask, even for one target: routers uninstall, workloads offboard, workloads exclude, exclusions add, users disable, users role, groups delete, discovery config set and manager update.
  • Without a terminal, --yes is needed. --dry-run lists the targets and sends nothing.
  • A declined confirmation sends nothing.

Long operations

  • Onboarding, offboarding, installing, upgrading and uninstalling routers, exclusions, lifting them and updating the manager are operations of the manager.
  • The CLI follows each one step by step until it ends. A step that fails is printed with its detail.
  • --no-wait prints the operation's id instead. dormeto aws operations watch <id> follows it later.
  • --timeout, 60 minutes by default, and Ctrl-C stop following. The operation goes on in the manager.
  • A wake and a discovery run are not operations: --wait waits for them.
  • --for takes 90m, 2h, or days: 3d, 1d12h. --until takes a time: 18:30 today, or an RFC 3339 time.

Output and exit codes

  • Lists are tables. show commands print a line per field, times in your time zone.
  • Every command has --json: the manager's answer, on stdout alone. Progress, questions and dry-run lists go to stderr.
  • A list prints the API's object, every page in it: {"users": […]}.
  • A command that starts operations prints them as an array when it takes several targets, as an object when it takes one.
  • A dry run prints {"dryRun": true, "targets": […]}, a declined confirmation {"confirmed": false, "targets": […]}. When nothing succeeded, [] or {}.
  • The exit code is 0 on success, and 1 when AWS or the manager refused or an operation failed. It is 2 for a bad flag or argument, and 130 after Ctrl-C.
dormeto aws workloads list --state ASLEEP --json | jq '.workloads | length'

Routers

dormeto aws routers list [--outdated] [--account <id>] [--router-region <region>]
dormeto aws routers show <router>
dormeto aws routers install --account <id> --router-region <region>
dormeto aws routers upgrade [<router>...] [--all] [--dry-run]
dormeto aws routers pause <router>... --reason <text> [--for <duration>]
dormeto aws routers resume <router>...
dormeto aws routers settings <router>... [--hibernate true|false|inherit] [--join-minutes <minutes>|inherit] [--dry-run] [--yes]
dormeto aws routers description <router> [--set <text> | --file <path or -> | --clear]
dormeto aws routers uninstall <router>...
  • list shows each router's version, health and workloads. --outdated keeps the routers to upgrade.
  • show prints one router's details: version, health and problems, pauses, and each setting with where it is set.
  • install installs a router in an account and region. The account needs Dormeto's command role (Organization access).
  • upgrade prints a plan, with the routers it skips and why, then asks to confirm. --all takes every router.
  • pause stops the automatic naps of a router's workloads, for up to 366 days. It wakes the asleep ones, unless --keep-asleep. resume ends the pause.
  • settings sets a router's EC2 hibernation for the workloads that set none, or inherit to follow the manager's default (administrators). It needs router 0.32.0 and manager 0.19.0 (Workloads). --join-minutes sets how far apart a router's windows of one kind may be and still join, with router 0.36.0 and CLI 0.10.0 (Schedules).
  • description prints a router's Markdown description as written, or "no description". --set writes it, --file reads it from a file or from standard input (-), --clear removes it. Administrators write it. It needs manager 0.19.0 and CLI 0.7.0 (Workloads).
  • uninstall refuses a router that still has workloads: offboard them first.
dormeto aws routers install --account 111122223333 --router-region eu-west-3
dormeto aws routers pause prod-eu --reason "database migration" --for 3h
dormeto aws routers upgrade --all --dry-run

Workloads

Reading

dormeto aws workloads list [--state <state>] [--router <name>] [--tag k=v] [--search <text>]
dormeto aws workloads show <router>/<workload>
dormeto aws workloads history <router>/<workload> [--days 1..31]
dormeto aws workloads idle-window <router>/<workload>
  • show prints the state, the settings, the pauses, the schedule, the last 7 days and the savings.
  • history prints the time in each state, the wakes and the latest changes, 7 days by default.
  • idle-window prints the manager's advice: windows from 5 to 120 minutes, each with its savings and wakes.

Waking, napping and pausing

dormeto aws workloads wake <targets> [--wait]
dormeto aws workloads nap <targets>
dormeto aws workloads pause <targets> --reason <text> [--for <duration>] [--keep-asleep]
dormeto aws workloads keep-awake <targets> --for <duration> [--wait]
dormeto aws workloads resume <targets>
  • wake wakes the workloads now. --wait returns once they are awake.
  • nap puts them to sleep now. A router refuses a workload that is paused or not awake, and says why.
  • pause stops their automatic naps, for up to 366 days. keep-awake is a pause that wakes them, for up to 7 days. resume ends both.
dormeto aws workloads wake prod-eu/w-1 --wait
dormeto aws workloads nap --tag env=dev --yes
dormeto aws workloads pause --tag team=payments --reason "load test" --until 18:00 --yes

Names, tags and schedules

dormeto aws workloads rename <router>/<workload> <name>
dormeto aws workloads description <router>/<workload> [--set <text> | --file <path or -> | --clear]
dormeto aws workloads tags <targets> [--set k=v] [--unset k] [--clear]
dormeto aws workloads schedule show <router>/<workload>
dormeto aws workloads schedule set <targets> --file <path>
dormeto aws workloads schedule clear <targets>
  • rename sets a workload's display name, 1 to 64 characters. It needs routers 0.20.0.
  • description prints a workload's Markdown description as written, or "no description". --set writes it, --file reads it from a file or from standard input (-), --clear removes it. Operators and administrators write it. It needs manager 0.19.0 and CLI 0.7.0 (Workloads).
  • tags changes Dormeto's tags, not AWS tags. It sends them only when they change. It needs routers 0.30.0.
  • The schedule commands are on the Schedules page.
dormeto aws workloads rename prod-eu/w-1 "checkout api"
dormeto aws workloads tags prod-eu/w-1 --set team=payments --unset owner

Hibernation

dormeto aws workloads settings <targets> --hibernate true|false|inherit [--dry-run] [--yes]
dormeto aws workloads onboard <candidate> [--hibernate true|false]
  • settings sets a workload's own EC2 hibernation, or inherit to follow its router (operators and administrators). A workload written by Terraform is refused: set hibernate in its workload module. It needs router 0.32.0 and manager 0.19.0 (Workloads).
  • onboard --hibernate sets it at onboarding. Without it the workload inherits its router's.
dormeto aws workloads settings --tag env=dev --hibernate true --yes

Waiting page

dormeto aws workloads waiting-page show <router>/<workload> [--json]
dormeto aws workloads waiting-page set <router>/<workload> [--icon auto|none|<file>] [--title <text>] [--description <text>]
dormeto aws workloads waiting-page set <router>/<workload> --html <file or ->
dormeto aws workloads waiting-page clear <router>/<workload>
dormeto aws routers waiting-page show <router> [--json]
dormeto aws routers waiting-page set <router> [--icon auto|none|<file>] [--title <text>] [--description <text>] | --html <file or ->
dormeto aws routers waiting-page clear <router>
dormeto aws settings waiting-page show [--json]
dormeto aws settings waiting-page set [--icon auto|none|<file>] [--title <text>] [--description <text>] | --html <file or ->
dormeto aws settings waiting-page clear
  • One page is kept per level: the workload, its router and the organization (settings waiting-page, for every router). show prints the effective mode, icon, title and description with the level each comes from. For a workload, it prints the cached favicon, or why there is none. It also prints who set the level and when, and the warnings. An icon or a page prints as its type and size, never its content. --json prints everything.
  • set replaces that level's document. --title, --description and --icon write a template. A field left out is inherited. --icon is auto (the application's favicon), none, or a PNG, JPEG, WebP, SVG or ICO file of at most 64 KiB. A file named auto or none is given as ./auto. --html writes a custom page instead: a file or - for standard input, UTF-8, not blank, at most 256 KiB. Mixing --html with a template flag, or set with none, is a usage error. The icon and the page are checked before any call (exit 2). The page's warnings print after the write.
  • clear removes the level's document, which then inherits.
  • A custom page needs an administrator at every level, to set, replace or clear it. A template needs an administrator for a router or the organization and an operator for a workload. A workload written by Terraform is refused: set waiting_page in its module. A router before 0.35.0 answers that it must be upgraded (exit 1). It needs manager 0.20.0 and CLI 0.8.0 (Workloads).
dormeto aws settings waiting-page set --title "Acme portal" --icon ./logo.svg --description "Our test environments sleep at night."
dormeto aws workloads waiting-page set prod-eu/w-1 --title "Shop (staging)"
cat waiting.html | dormeto aws workloads waiting-page set prod-eu/w-1 --html -

Onboarding, offboarding and excluding

dormeto aws workloads onboard <candidate> [--name <name>] [--idle-minutes <minutes>]
dormeto aws workloads offboard <targets>
dormeto aws workloads exclude <targets> --reason <text> [--for <duration>]
  • onboard takes a candidate pending onboarding and the Onboard dialog's fields. They are --name, --idle-minutes (15 by default), --wake-mode, --database, --fallback-type, --hibernate, and --set-tag for the new workload's tags (Workloads). It prints the new workload.
  • offboard gives the application back as it was, 4 workloads at a time by default.
  • exclude keeps a workload's target group out of discovery: an exclusion (below).
dormeto aws discovery candidates
dormeto aws workloads onboard shop-staging --idle-minutes 30 --database cluster:shop-aurora
dormeto aws workloads offboard prod-eu/w-1 --yes

Discovery

dormeto aws discovery status
dormeto aws discovery run [--wait]
dormeto aws discovery candidates [--status <status>] [--account <id>] [--candidate-region <region>]
dormeto aws discovery dismiss <candidate>... [--note <text>]
dormeto aws discovery restore <candidate>...
dormeto aws discovery access
dormeto aws discovery config show
dormeto aws discovery config set --file <path>
  • status shows the last run, the candidates per status and what the lint finds.
  • run asks for a run now. --wait returns once it has ended.
  • candidates lists one status, pending-onboarding by default, every page of it.
  • dismiss takes candidates out of the onboarding list. restore brings them back.
  • access lists the accounts whose roles are missing, and which one.
  • config show prints the configuration as JSON, the lint on stderr. config set replaces it with a file, after a confirmation. A refusal lists each error. The format is on the Discovery page.
dormeto aws discovery run --wait
dormeto aws discovery candidates --account 111122223333 --candidate-region eu-west-1
dormeto aws discovery config show > discovery.json
dormeto aws discovery config set --file discovery.json

Exclusions

dormeto aws exclusions list
dormeto aws exclusions add --account <id> --reason <text> [--for <duration>]
dormeto aws exclusions lift <id>...
  • An exclusion keeps a target group, a load balancer or an account out of discovery. add takes --target-group, --load-balancer or --account.
  • The manager pauses the workloads it manages there: an operation, followed.
  • --for goes up to 366 days. Without it, the exclusion lasts until it is lifted.
  • lift resumes the workloads, then deletes the exclusion. If it stays listed, lift it again.
dormeto aws exclusions add --account 444455556666 --reason "production account" --yes
dormeto aws workloads exclude prod-eu/w-2 --reason "under migration" --for 14d --yes
dormeto aws exclusions list

Operations

dormeto aws operations list [--running] [--type <type>] [--limit <n>]
dormeto aws operations show <id>
dormeto aws operations watch <id>
  • list shows the newest first: type, target, status, current step, who started it.
  • show prints the steps, how long each took and what it says.
  • watch follows an operation to its end. It exits 1 if the operation failed.
  • They see the operations started from the dashboard too.
dormeto aws operations list --running
dormeto aws operations watch 5f0c2b7e-1d4a-4e8b-9c3f-7a2d6e1b8c40

Users

dormeto aws users list
dormeto aws users invite <email> --role <role> [--group <name>]
dormeto aws users role <email> <role>
dormeto aws users groups <email> [<name>...]
dormeto aws users disable <email>
dormeto aws users enable <email>
dormeto aws users resend <email>
dormeto aws users reset-mfa <email>
  • The roles are member, viewer, operator and admin (Security).
  • invite emails a temporary password. resend sends it again.
  • users groups sets the user's custom groups. Without a name, it removes them all.
  • reset-mfa resets the user's authenticator: they set it up again at their next sign-in.
  • From manager 0.18.0, the manager refuses to demote or disable its last administrator. An older one does not, and the CLI does not check: keep a second administrator.
dormeto aws users invite ana@example.com --role member --group payments-dev
dormeto aws users role ana@example.com operator
dormeto aws users groups ana@example.com

Groups

dormeto aws groups list
dormeto aws groups show <name>
dormeto aws groups create <name> [--description <text>] [--grant <tags>:<permissions>]
dormeto aws groups update <name> [--grant <tags>:<permissions>] [--no-grants]
dormeto aws groups delete <name>
  • A custom group gives its members permissions on the workloads with some tags.
  • A grant is team=payments,env=dev:read,wake: the tags before the last colon, the permissions after it, among read, wake and nap.
  • :read, with no tag, covers every workload.
  • update replaces the group's grants with those given.
dormeto aws groups create payments-dev --grant team=payments,env=dev:read,wake
dormeto aws groups update payments-dev --grant team=payments:read --grant team=payments,env=dev:read,wake,nap
dormeto aws groups delete payments-dev --yes

Audit, savings, alerts and IP lists

dormeto aws overview
dormeto aws audit [--since <duration>] [--action <action>] [--who <text>] [--limit <n>]
dormeto aws savings show
dormeto aws savings discounts --compute <percent> --databases <percent>
dormeto aws alerts list
dormeto aws ip-lists list
  • overview shows the dashboard's Overview: workloads by state, savings, open alerts, running operations and outdated routers.
  • audit shows who did what, newest first. The CLI filters it.
  • savings show shows the estimated savings. savings discounts sets your discounts on compute and databases, from 0 to 90%.
  • alerts list shows the open alarms and where alerts are sent.
  • ip-lists list shows each IP list, its entries and its last download (Configuration).
dormeto aws audit --since 2d --action pause,resume
dormeto aws savings discounts --compute 20 --databases 15

The manager

dormeto aws settings show
dormeto aws settings set --hibernate true|false
dormeto aws settings set --join-minutes <minutes>|inherit
dormeto aws settings set --ended-window-days <days>|default
dormeto aws manager status
dormeto aws manager check --enable
dormeto aws manager changes [--to <version>]
dormeto aws manager update [--version <version>] [--dry-run]
  • settings show prints the manager's default for the workloads' settings, and who changed it. settings set --hibernate changes it (administrators): routers read it at their next check, within 5 minutes. It needs manager 0.19.0 and CLI 0.7.0 (Hibernation). --join-minutes sets the organization's joined windows, and --ended-window-days how long an ended window stays (joined, ended). Both need manager 0.21.0 and CLI 0.10.0. Each flag goes alone or with the others.
  • status shows the version, how the manager was installed, the newer versions and the daily check.
  • check turns the daily check for new versions on or off.
  • changes prints the release notes of the newer versions.
  • update plans the update, prints the plan, asks to confirm, then applies it and follows it. --dry-run stops after the plan.
  • This works for a manager installed with the CLI. A manager installed with Terraform is updated with its module (Get started).
dormeto aws manager changes
dormeto aws manager update --dry-run
dormeto aws manager update --yes

Raw calls

dormeto aws api <method> <path> [--data <json>] [-q key=value]
  • api calls any route of the manager's API, signed, and prints the answer.
  • The path is the route's under /iam. --data takes JSON, @file, or - for standard input.
  • An answer other than 2xx exits 1. Use it for what a newer manager has before the CLI does.
dormeto aws api GET /workloads -q state=ASLEEP -q limit=10
dormeto aws api POST /routers/prod-eu/pause --data '{"reason":"maintenance"}'

Permissions

  • The CLI calls the API's /iam/* routes. The caller needs execute-api:Invoke on them, in the manager's account.
  • To find the API by name, it also needs apigateway:GET. --api-url does without.
  • The manager treats the caller as an administrator. The audit and the operations name its ARN.
  • Its IAM policy is the only limit. Grant the routes its commands call, by method and path.

Three policies

  • Read-only, every command that only reads: arn:aws:execute-api:<region>:<account>:<api id>/*/GET/iam/*. It still reads the users and the audit.
  • Every command: arn:aws:execute-api:<region>:<account>:<api id>/*/*/iam/*, the module's api_iam_arn output.
  • Wake and nap: check the caller with whoami, read the workloads, wake them and nap them, nothing else.
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "execute-api:Invoke",
    "Resource": [
      "arn:aws:execute-api:<region>:<account>:<api id>/*/GET/iam/me",
      "arn:aws:execute-api:<region>:<account>:<api id>/*/GET/iam/health",
      "arn:aws:execute-api:<region>:<account>:<api id>/*/GET/iam/workloads",
      "arn:aws:execute-api:<region>:<account>:<api id>/*/GET/iam/workloads/*",
      "arn:aws:execute-api:<region>:<account>:<api id>/*/POST/iam/workloads/*/wake",
      "arn:aws:execute-api:<region>:<account>:<api id>/*/POST/iam/workloads/*/nap"
    ]
  }]
}

Add /*/POST/iam/workloads/*/pause and /*/POST/iam/workloads/*/resume for keep-awake, pause and resume. The CLI's README lists the route of every change: Permission to call the manager.