Get started

Estimate first

Before you install anything, dormeto aws estimate reads your accounts and tells you what Dormeto would save. It shows which workloads sit idle, for how long, and what their naps are worth. Install the command line with one of:

brew install dormeto/tap/dormeto
curl -fsSL https://dormeto.com/install.sh | sh

Homebrew and the script install the same program. The script checks the download's SHA-256, installs into ~/.local/bin and never uses sudo. On Windows, download dormeto_<version>_windows_amd64.zip from the latest release, unzip it and put dormeto.exe in a folder of your PATH. Then one command:

dormeto aws estimate --profile <profile> --uptime

It is read-only. It only lists and reads (load balancers, instances, services, metrics, prices), and writes a report on your machine. Nothing is sent but to AWS (and to your clusters' own APIs). There is no telemetry and no update check. The options (organizations, regions, reports) are in the Dormeto/cli repository.

Prerequisites

• Administrator credentials of the account where the manager runs, in its region.
• An AWS organization. The manager lists its accounts through a delegation policy of the management account. It reads each account through a role there (Organization access). A single account outside any organization works too. The CLI suggests it. With Terraform, you set discovery_mode = "account" and leave out organization_id.
• Optional: a domain for the dashboard, and its Route 53 zone. Its certificate is in us-east-1 and covers the dashboard host and auth. under it. Without, the dashboard is on a cloudfront.net host.
• Optional: a verified SES identity to send the invitations. Without, Cognito sends them itself (about 50 a day).

Install

Two ways to install the same manager from the same release. The dormeto CLI is the simpler one: it asks what it needs, checks it, and runs Terraform for you in your account. There is nothing else to install and no Terraform state to keep. With your own Terraform, the manager is a module in a configuration you keep.

aws sso login --profile <profile>
dormeto aws install --profile <profile>

# without a terminal: every answer as a flag; it stops after the plan, then apply that plan
dormeto aws install --profile <profile> --admin-emails you@example.com
dormeto aws install apply --profile <profile>

provider "aws" {
  region = "eu-west-1"
}

module "dormeto" {
  source          = "https://releases.dormeto.com/manager/0.21.0/terraform-aws-dormeto-0.21.0.zip//modules/manager"
  env             = "prod"
  organization_id = "o-exampleorgid"
  admin_emails    = ["you@example.com"]
}

output "dashboard_url" {
  value = module.dormeto.dashboard_url
}

terraform init
terraform plan -out=dormeto.tfplan
terraform apply dormeto.tfplan

  domain = {
    dashboard       = "dormeto.example.com"
    auth            = "auth.dormeto.example.com"
    certificate_arn = "arn:aws:acm:us-east-1:111122223333:certificate/…"
    zone_id         = "Z0123456789ABCDEFGHIJ"
  }
  ses_identity = "example.com"
  email_from   = "Dormeto <no-reply@example.com>"

Organization access

The manager's own account gets its roles from the module. Every other account to discover gets DmtDiscoveryRole. Every account where workloads nap gets DmtCommandRole. They come from the access module or the AWS CLI script of the same release, or from dormeto aws install with --management-profile. The management account gets the delegation policy: Organization access. Workloads on EKS also need Dormeto's rights in their cluster: Kubernetes.

First sign-in

Each address of admin_emails receives an invitation with a temporary password, valid 7 days. Open dashboard_url, sign in, choose a password, and add a second factor if you wish. In Discovery, Run now reads your organization. The Organization access panel lists the accounts whose roles are missing.

Event-driven refresh

Discovery runs on its refresh period (daily by default). In Discovery, the Perimeter settings can turn on event-driven refresh. The manager then installs a forwarder in each account with the command role and a CloudTrail trail. Load balancer changes appear within about 5 minutes. Turned off, the forwarders are removed at the next run.

Updating the manager

Three ways to move the manager to a newer release, each showing the plan before it applies it. The CLI and the dashboard update a manager installed with the CLI. Your own Terraform updates the one it installed.

dormeto aws install --profile <profile>                       # the latest release
dormeto aws install --profile <profile> --version <version>

terraform init
terraform plan -out=dormeto.tfplan
terraform apply dormeto.tfplan

The manager then offers, in its Routers view, the router upgrades the release carries.

Routers and workloads from the CLI

This needs the CLI 0.4.0 or later and a manager 0.15.0 or later. keep-awake and resume below need CLI 0.5.0. List the routers and workloads and upgrade routers from your laptop, with the AWS profile you installed with:

dormeto aws routers list --outdated
dormeto aws workloads list --tag team=payments --state ASLEEP
dormeto aws routers upgrade --tag team=payments    # or --all; --dry-run prints the plan only

routers upgrade prints the plan, with the routers it skips and why (written in Terraform, up to date, busy with an operation). It asks you to confirm. --yes is needed without a terminal, and --json prints the result for a script. --tag key=value selects the routers that serve a workload with these Dormeto tags.

To keep workloads awake, for example around a CI job, and to set schedules (Schedules):

dormeto aws workloads keep-awake prod-eu/w-1 --for 1h --wait
dormeto aws workloads resume prod-eu/w-1
dormeto aws workloads schedule set --tag team=payments --file schedule.json

keep-awake wakes the workload if it is asleep and keeps it from napping for up to 7 days (--for or --until). --wait returns once it is awake, so a CI step can go on, and resume ends it. keep-awake and resume need CLI 0.5.0 and any manager 0.15.0 or later. Schedules need CLI 0.5.0, manager 0.16.0 and routers 0.31.0. --tag selects every workload with these tags.

The caller needs execute-api:Invoke on the manager API’s /iam/* routes, in the manager’s account. They are the api_iam_arn output of the module, and GET alone is enough for the two lists. The caller also needs apigateway:GET to find the API by name, unless --api-url is given. Such a caller acts as an administrator: the audit and the operations name its ARN.

CLI 0.6.0 has a command for every other operation of the manager too: onboarding, discovery, operations, users and groups, the audit, the manager’s update. They are on the CLI page, with IAM policies from read-only to every route.

Uninstall

1. In the manager, offboard the workloads and uninstall the routers. They were installed by API calls, outside your Terraform state. If event-driven refresh is on, turn it off and run discovery (Run now). The forwarders it installed in your accounts are then removed.
2. Set deletion_protection = false in the module (it protects the users from a mistaken destroy), apply, then terraform destroy.
3. Remove the roles of the member accounts and Dormeto's statement of the delegation policy, keeping its others: Organization access.