Dormeto
ENFR
Menu

Docs

CLI

La ligne de commande dormeto fait depuis un terminal ce que fait le tableau de bord. Elle couvre chaque opération du manager, pour vos scripts, vos jobs de CI et les changements sur de nombreux workloads à la fois. Elle signe ses appels avec votre profil AWS.

15 min de lectureManager 0.21.0

Se connecter au manager

La CLI 0.7.0 a toutes les commandes de cette page (pour l'installer : Démarrer). Chaque commande demande un manager 0.15.0 ou plus récent. La protection du dernier administrateur demande un manager 0.18.0.

Toutes les commandes de cette page sont sous dormeto aws, comme celles de Google Cloud sont sous dormeto gcp. La CLI d'avant aws les avait au premier niveau, comme dormeto install et dormeto routers list. Ces noms fonctionnent encore, cachés de l'aide, avec une ligne sur stderr qui donne le nouveau nom. Ils disparaîtront dans une prochaine version.

  • La CLI trouve l'API du manager par son nom, dmt-<env>-manager-api, avec votre profil AWS.
  • --profile choisit le profil, --region la région du manager et --env son environnement, prod par défaut.
  • --api-url donne plutôt l'URL de l'API : la sortie api_endpoint du module, pas l'adresse du tableau de bord.
  • whoami montre qui le manager voit, avec quel rôle, et la version du manager.
dormeto aws whoami
dormeto aws whoami --profile ops --env dev --region eu-west-3

Cibles

  • Un routeur se désigne par son nom : prod-eu.
  • Un workload s'écrit <router>/<workload id> : prod-eu/w-1. Plus bas, <targets> désigne un ou plusieurs workloads.
  • --tag key=value sélectionne à la place tous les workloads portant ce tag Dormeto. Répétez-le pour exiger plusieurs tags.
  • Un candidat de la découverte se désigne par l'ARN de son target group. Le nom du target group convient aussi quand aucun autre candidat ne le porte.
  • Un utilisateur se désigne par son e-mail, un groupe par son nom, une opération et une exclusion par leur identifiant.
  • --region est toujours la région du manager. La région d'un routeur est --router-region, celle d'un candidat --candidate-region.

Confirmations

  • Un changement sur plusieurs workloads ou routeurs demande une confirmation dans un terminal. La question nomme les cibles : un changement sur des workloads les liste d'abord.
  • Ces commandes la demandent toujours, même pour une seule cible : routers uninstall, workloads offboard, workloads exclude, exclusions add, users disable, users role, groups delete, discovery config set et manager update.
  • Sans terminal, --yes est obligatoire. --dry-run liste les cibles sans rien envoyer.
  • Une confirmation refusée n'envoie rien.

Opérations longues

  • Sont des opérations du manager : l'intégration, le retrait, l'installation, la mise à jour et la désinstallation des routeurs. Les exclusions, leur levée et la mise à jour du manager en sont aussi.
  • La CLI suit chacune étape par étape jusqu'à sa fin. Une étape en échec s'affiche avec son détail.
  • --no-wait affiche plutôt l'identifiant de l'opération. dormeto aws operations watch <id> la suit plus tard.
  • --timeout, 60 minutes par défaut, et Ctrl-C arrêtent le suivi. L'opération continue dans le manager.
  • Un réveil et une exécution de la découverte ne sont pas des opérations : --wait les attend.
  • --for prend 90m, 2h, ou des jours : 3d, 1d12h. --until prend une heure : 18:30 aujourd'hui, ou une date RFC 3339.

Sortie et codes de retour

  • Les listes sont des tableaux. Les commandes show affichent une ligne par champ, les heures dans votre fuseau.
  • Chaque commande a --json : la réponse du manager, seule sur la sortie standard. La progression, les questions et les listes de --dry-run vont sur la sortie d'erreur.
  • Une liste affiche l'objet de l'API, toutes ses pages comprises : {"users": […]}.
  • Une commande qui lance des opérations les affiche en tableau quand elle prend plusieurs cibles, en objet quand elle en prend une.
  • --dry-run affiche alors {"dryRun": true, "targets": […]}, une confirmation refusée {"confirmed": false, "targets": […]}. Quand rien n'a réussi, [] ou {}.
  • Le code de retour vaut 0 en cas de succès, et 1 quand AWS ou le manager refuse ou qu'une opération échoue. Il vaut 2 pour une option ou un argument invalide, et 130 après Ctrl-C.
dormeto aws workloads list --state ASLEEP --json | jq '.workloads | length'

Routeurs

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 affiche la version, la santé et les workloads de chaque routeur. --outdated garde les routeurs à mettre à jour.
  • show affiche le détail d'un routeur : version, santé et problèmes, pauses, et chaque réglage avec l'endroit où il est défini.
  • install installe un routeur dans un compte et une région. Le compte doit avoir le rôle de commande de Dormeto (Accès à l’organisation).
  • upgrade affiche un plan, avec les routeurs laissés de côté et pourquoi, puis demande confirmation. --all prend tous les routeurs.
  • pause suspend les mises en veille automatiques des workloads d'un routeur, pour 366 jours au plus. Elle réveille ceux qui dorment, sauf avec --keep-asleep. resume met fin à la pause.
  • settings définit l'hibernation EC2 d'un routeur pour les workloads qui n'en définissent pas, ou inherit pour suivre la valeur par défaut du manager (administrateurs). Il demande un routeur 0.32.0 et un manager 0.19.0 (Workloads). --join-minutes règle l'écart jusqu'auquel les plages d'un même type d'un routeur se réunissent, avec un routeur 0.36.0 et la CLI 0.10.0 (Horaires).
  • description affiche la description Markdown d'un routeur telle qu'écrite, ou « no description ». --set l'écrit, --file la lit dans un fichier ou sur l'entrée standard (-), --clear la supprime. Les administrateurs l'écrivent. Elle demande un manager 0.19.0 et la CLI 0.7.0 (Workloads).
  • uninstall refuse un routeur qui a encore des workloads : retirez-les d'abord.
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

Consulter

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 affiche l'état, les réglages, les pauses, l'horaire, les 7 derniers jours et les économies.
  • history affiche le temps passé dans chaque état, les réveils et les derniers changements, sur 7 jours par défaut.
  • idle-window affiche le conseil du manager : des délais de 5 à 120 minutes, chacun avec ses économies et ses réveils.

Réveiller, mettre en veille, mettre en pause

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 réveille les workloads tout de suite. --wait rend la main quand ils sont éveillés.
  • nap les met en veille tout de suite. Un routeur refuse un workload en pause ou qui n'est pas éveillé, et dit pourquoi.
  • pause suspend leurs mises en veille automatiques, pour 366 jours au plus. keep-awake est une pause qui les réveille, pour 7 jours au plus. resume met fin aux deux.
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

Noms, tags et horaires

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 change le nom affiché d'un workload, de 1 à 64 caractères. Il demande des routeurs 0.20.0.
  • description affiche la description Markdown d'un workload telle qu'écrite, ou « no description ». --set l'écrit, --file la lit dans un fichier ou sur l'entrée standard (-), --clear la supprime. Les opérateurs et les administrateurs l'écrivent. Elle demande un manager 0.19.0 et la CLI 0.7.0 (Workloads).
  • tags change les tags Dormeto, pas les tags AWS. Il ne les envoie que s'ils changent. Il demande des routeurs 0.30.0.
  • Les commandes des horaires sont sur la page Horaires.
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 définit l'hibernation EC2 propre à un workload, ou inherit pour suivre son routeur (opérateurs et administrateurs). Un workload écrit en Terraform est refusé : définissez hibernate dans son module workload. Il demande un routeur 0.32.0 et un manager 0.19.0 (Workloads).
  • onboard --hibernate la définit à l'intégration. Sans l'option, le workload hérite de son routeur.
dormeto aws workloads settings --tag env=dev --hibernate true --yes

Page d'attente

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
  • Une page est conservée par niveau : le workload, son routeur et l'organisation (settings waiting-page, pour tous les routeurs). show affiche le mode, l'icône, le titre et la description effectifs avec le niveau dont vient chacun. Pour un workload, il affiche le favicon en cache, ou pourquoi il n'y en a pas. Il affiche aussi qui a défini le niveau et quand, et les avertissements. Une icône ou une page s'affiche comme son type et sa taille, jamais son contenu. --json affiche tout.
  • set remplace le document de ce niveau. --title, --description et --icon écrivent un modèle. Un champ omis est hérité. --icon vaut auto (le favicon de l'application), none, ou un fichier PNG, JPEG, WebP, SVG ou ICO de 64 KiB au plus. Un fichier nommé auto ou none se donne comme ./auto. --html écrit plutôt une page personnalisée : un fichier ou - pour l'entrée standard, en UTF-8, non vide, de 256 KiB au plus. Mélanger --html et une option de modèle, ou lancer set sans aucune, est une erreur d'usage. L'icône et la page sont vérifiées avant tout appel (code 2). Les avertissements de la page s'affichent après l'écriture.
  • clear supprime le document du niveau, qui hérite alors.
  • Une page personnalisée demande un administrateur, à chaque niveau, pour la définir, la remplacer ou l'effacer. Un modèle demande un administrateur pour un routeur ou l'organisation et un opérateur pour un workload. Un workload écrit par Terraform est refusé : définissez waiting_page dans son module. Un routeur antérieur à la 0.35.0 répond qu'il faut le mettre à jour (code 1). Elle demande un manager 0.20.0 et la 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 -

Intégrer, retirer, exclure

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 prend un candidat en attente d'intégration et les champs de la fenêtre Onboard. Ce sont --name, --idle-minutes (15 par défaut), --wake-mode, --database, --fallback-type, --hibernate, et --set-tag pour les tags du nouveau workload (Workloads). Il affiche le nouveau workload.
  • offboard rend l'application telle qu'elle était, 4 workloads à la fois par défaut.
  • exclude tient le target group d'un workload à l'écart de la découverte : une exclusion (plus bas).
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

Découverte

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 affiche la dernière exécution, les candidats par statut et ce que trouve le lint.
  • run demande une exécution tout de suite. --wait rend la main quand elle est terminée.
  • candidates liste un statut, pending-onboarding par défaut, toutes ses pages.
  • dismiss écarte des candidats de la liste à intégrer. restore les y remet.
  • access liste les comptes dont un rôle manque, et lequel.
  • config show affiche la configuration en JSON, le lint sur la sortie d'erreur. config set la remplace par un fichier, après confirmation. Un refus liste chaque erreur. Le format est sur la page Découverte.
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>...
  • Une exclusion tient un target group, un équilibreur de charge ou un compte à l'écart de la découverte. add prend --target-group, --load-balancer ou --account.
  • Le manager met en pause les workloads qu'il y gère : une opération, suivie.
  • --for va jusqu'à 366 jours. Sans lui, l'exclusion dure jusqu'à sa levée.
  • lift reprend les workloads, puis supprime l'exclusion. Si elle reste listée, levez-la de nouveau.
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

Opérations

dormeto aws operations list [--running] [--type <type>] [--limit <n>]
dormeto aws operations show <id>
dormeto aws operations watch <id>
  • list affiche les plus récentes d'abord : type, cible, statut, étape en cours, qui l'a lancée.
  • show affiche les étapes, la durée de chacune et ce qu'elle dit.
  • watch suit une opération jusqu'à sa fin. Son code de retour vaut 1 si l'opération a échoué.
  • Elles voient aussi les opérations lancées depuis le tableau de bord.
dormeto aws operations list --running
dormeto aws operations watch 5f0c2b7e-1d4a-4e8b-9c3f-7a2d6e1b8c40

Utilisateurs

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>
  • Les rôles sont member, viewer, operator et admin (Sécurité).
  • invite envoie un mot de passe temporaire par e-mail. resend le renvoie.
  • users groups définit les groupes personnalisés de l'utilisateur. Sans nom, il les retire tous.
  • reset-mfa réinitialise l'authentificateur de l'utilisateur : il le configure de nouveau à sa prochaine connexion.
  • À partir du manager 0.18.0, le manager refuse de rétrograder ou de désactiver son dernier administrateur. Un manager plus ancien ne le refuse pas, et la CLI ne le vérifie pas : gardez un second administrateur.
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

Groupes

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>
  • Un groupe personnalisé donne à ses membres des permissions sur les workloads portant certains tags.
  • Un droit s'écrit team=payments,env=dev:read,wake : les tags avant le dernier deux-points, les permissions après, parmi read, wake et nap.
  • :read, sans tag, couvre tous les workloads.
  • update remplace les droits du groupe par ceux donnés.
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, économies, alertes et listes d'IP

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 affiche la vue d'ensemble du tableau de bord : workloads par état, économies, alertes ouvertes, opérations en cours et routeurs à mettre à jour.
  • audit montre qui a fait quoi, du plus récent au plus ancien. La CLI le filtre.
  • savings show affiche les économies estimées. savings discounts fixe vos remises sur le calcul et les bases de données, de 0 à 90 %.
  • alerts list affiche les alarmes ouvertes et où partent les alertes.
  • ip-lists list affiche chaque liste d'IP, ses entrées et son dernier téléchargement (Configuration).
dormeto aws audit --since 2d --action pause,resume
dormeto aws savings discounts --compute 20 --databases 15

Le 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 affiche la valeur par défaut du manager pour les réglages des workloads, et qui l'a changée. settings set --hibernate la change (administrateurs) : les routeurs la lisent à leur vérification suivante, dans les 5 minutes. Il demande un manager 0.19.0 et la CLI 0.7.0 (Hibernation). --join-minutes règle les plages réunies de l'organisation, et --ended-window-days combien de temps une plage terminée reste (réunies, terminées). Les deux demandent un manager 0.21.0 et la CLI 0.10.0. Chaque option s'utilise seule ou avec les autres.
  • status affiche la version, la façon dont le manager a été installé, les versions plus récentes et la vérification quotidienne.
  • check active ou désactive la vérification quotidienne des nouvelles versions.
  • changes affiche les notes de version des versions plus récentes.
  • update planifie la mise à jour, affiche le plan, demande confirmation, puis l'applique et la suit. --dry-run s'arrête après le plan.
  • Cela vaut pour un manager installé avec la CLI. Un manager installé avec Terraform se met à jour par son module (Démarrer).
dormeto aws manager changes
dormeto aws manager update --dry-run
dormeto aws manager update --yes

Appels bruts

dormeto aws api <method> <path> [--data <json>] [-q key=value]
  • api appelle n'importe quelle route de l'API du manager, signée, et affiche la réponse.
  • Le chemin est celui de la route sous /iam. --data prend du JSON, @file, ou - pour l'entrée standard.
  • Une réponse autre que 2xx donne le code de retour 1. Servez-vous-en pour ce qu'un manager plus récent offre avant la CLI.
dormeto aws api GET /workloads -q state=ASLEEP -q limit=10
dormeto aws api POST /routers/prod-eu/pause --data '{"reason":"maintenance"}'

Droits

  • La CLI appelle les routes /iam/* de l'API. L'appelant a besoin de execute-api:Invoke sur elles, dans le compte du manager.
  • Pour trouver l'API par son nom, il lui faut aussi apigateway:GET. --api-url s'en passe.
  • Le manager traite l'appelant comme un administrateur. L'audit et les opérations nomment son ARN.
  • Sa politique IAM est la seule limite. Accordez les routes que ses commandes appellent, par méthode et par chemin.

Trois politiques

  • Lecture seule, toutes les commandes qui ne font que lire : arn:aws:execute-api:<region>:<account>:<api id>/*/GET/iam/*. Elle lit tout de même les utilisateurs et l'audit.
  • Toutes les commandes : arn:aws:execute-api:<region>:<account>:<api id>/*/*/iam/*, la sortie api_iam_arn du module.
  • Réveil et mise en veille : vérifier l'appelant avec whoami, lire les workloads, les réveiller et les mettre en veille, rien d'autre.
{
  "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"
    ]
  }]
}

Ajoutez /*/POST/iam/workloads/*/pause et /*/POST/iam/workloads/*/resume pour keep-awake, pause et resume. Le README de la CLI donne la route de chaque changement : Permission to call the manager.