Google Cloud

$ dormeto gcp check --project my-project --region europe-west1project my-project: billing enabled✓ check  ✓ install  ✓ install-router  ✓ uninstall✓ workloads  ✓ onboard  ✓ offboard

What it needs

The APIs

dormeto gcp install turns on these ten APIs, .googleapis.com each, in the project. uninstall turns none off: other things in the project may use them.

The roles

Two custom roles, created in the project, and four predefined roles. Every permission below is in the manifest the router and the CLI share. The router's tests check that each Google Cloud call it makes is covered by one of them.

dormetoRouter

Dormeto router. Lets a Dormeto router read its workloads' load balancers, VMs and groups, and update their URL maps. It can create and delete their waker backend services, and turn their autoscalers off and back on. It reads their request counts.

Google marks compute.urlMaps.get, compute.urlMaps.list and compute.urlMaps.update as testing in custom roles: usable, not recommended for production by Google. No narrower predefined role holds them, so dormetoRouter keeps them. An autoscaler cannot carry a tag, so compute.autoscalers.update is here, without the tag condition.

dormetoRouterBackends

Dormeto router backends. Lets a Dormeto router start, stop, suspend and resume its workloads' VMs and managed instance groups. Granted on the condition that the resource has the tag dormeto=managed.

Granted on the condition that the resource has the tag dormeto=managed. An autoscaler's change names its group, so compute.instanceGroupManagers.update and .use are checked on the group's tag.

Predefined roles

Granted as described in the grants. Dormeto relies on these permissions of each:

The grants

The router runs as the service account dmtr-<region>@<project>.iam.gserviceaccount.com. The CLI adds exactly these bindings, and only these. It never changes or removes a binding it did not add. In a condition, {project} is the project's ID and {database} is the router's database, dmtr-<region>.

What Google adds

Turning APIs on and creating resources makes Google add bindings of its own to the project's IAM policy. Dormeto uses none of them for its own work. The CLI prints each one as Google's, with the step it appeared after, and records it. Seen on a real project, seven were added during the install, and an eighth when the image's repository was created:

The step names are those of the operator's table. The service agents are Google's to manage: leave them. uninstall leaves them too, and lists them as left in place. Compute Engine's own service agents, already there once Compute Engine is on, are Google's as well.

The default service account's Editor

Take a project outside an organization that enforces the constraint iam.automaticIamGrantsForDefaultServiceAccounts. When Compute Engine is turned on, Google gives its default service account, <project number>-compute@developer.gserviceaccount.com, the role roles/editor on the whole project. Dormeto does not use it: the router's Cloud Run services run as dmtr-<region>. dormeto gcp check reports the grant as a warning and leaves it: it is yours to remove. Before you do, check which VMs, instance templates and services run as that account, since they lose what Editor gave them:

gcloud compute instances list --format="table(name,zone.basename(),serviceAccounts[].email)"
gcloud projects remove-iam-policy-binding my-project \
  --member="serviceAccount:123456789012-compute@developer.gserviceaccount.com" \
  --role="roles/editor"

To keep Google from granting it again in your next projects, enforce iam.automaticIamGrantsForDefaultServiceAccounts on the organization or the folder.

The operator's permissions

You run the CLI with your gcloud account (its active configuration, or --gcloud-configuration). Each command tests the permissions of its steps before it changes anything: one missing stops it with nothing changed. roles/owner holds all of them. The tables list the steps of each command, as the manifest does.

dormeto gcp check

dormeto gcp install

dormeto gcp install --image

Added to install when you give the router's image.

dormeto gcp uninstall

dormeto gcp workloads list

Also show, nap and wake: they call the router's controller with your identity token.

dormeto gcp workloads onboard

dormeto gcp workloads offboard

A custom role for a narrower operator

If roles/owner is too much, create a role with the permissions of the commands this operator runs. This one holds every permission of the tables above:

title: Dormeto operator
description: Runs dormeto gcp in this project
stage: GA
includedPermissions:
- artifactregistry.dockerimages.get
- artifactregistry.repositories.downloadArtifacts
- artifactregistry.repositories.get
- cloudscheduler.jobs.create
- cloudscheduler.jobs.delete
- cloudscheduler.jobs.get
- cloudscheduler.jobs.update
- cloudtasks.queues.create
- cloudtasks.queues.delete
- cloudtasks.queues.get
- cloudtasks.queues.getIamPolicy
- cloudtasks.queues.setIamPolicy
- cloudtasks.queues.update
- compute.instanceGroupManagers.createTagBinding
- compute.instanceGroupManagers.deleteTagBinding
- compute.instanceGroupManagers.listTagBindings
- compute.instances.createTagBinding
- compute.instances.deleteTagBinding
- compute.instances.listTagBindings
- compute.regionNetworkEndpointGroups.create
- compute.regionNetworkEndpointGroups.delete
- compute.regionNetworkEndpointGroups.get
- compute.regionOperations.get
- datastore.databases.create
- datastore.databases.delete
- datastore.databases.get
- datastore.databases.list
- datastore.entities.create
- datastore.entities.get
- datastore.entities.list
- datastore.entities.update
- datastore.operations.get
- iam.roles.create
- iam.roles.delete
- iam.roles.get
- iam.roles.undelete
- iam.roles.update
- iam.serviceAccounts.actAs
- iam.serviceAccounts.create
- iam.serviceAccounts.delete
- iam.serviceAccounts.get
- iam.serviceAccounts.getIamPolicy
- iam.serviceAccounts.setIamPolicy
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.setIamPolicy
- resourcemanager.tagKeys.create
- resourcemanager.tagKeys.delete
- resourcemanager.tagKeys.get
- resourcemanager.tagValueBindings.create
- resourcemanager.tagValueBindings.delete
- resourcemanager.tagValues.create
- resourcemanager.tagValues.delete
- resourcemanager.tagValues.get
- run.operations.get
- run.routes.invoke
- run.services.create
- run.services.delete
- run.services.get
- run.services.getIamPolicy
- run.services.setIamPolicy
- run.services.update
- serviceusage.operations.get
- serviceusage.services.enable
- serviceusage.services.list
- serviceusage.services.use

gcloud iam roles create dormetoOperator --project=my-project --file=operator-role.yaml
gcloud projects add-iam-policy-binding my-project \
  --member="user:you@example.com" --role="projects/my-project/roles/dormetoOperator"

Drop the permissions of the commands you do not give, and check the result with dormeto gcp check, which lists what is missing for each command. Note that resourcemanager.projects.setIamPolicy lets its holder grant themselves any role in the project. Give this role for the time of the install and take it back after. Or keep it for the few people who run it.

Google lists three of these permissions as TESTING in custom roles, like compute.urlMaps.*: cloudtasks.queues.getIamPolicy, cloudtasks.queues.setIamPolicy and serviceusage.operations.get. They are usable and none is refused.

Optional access

From router 0.35.0 and CLI 0.8.0. Turning on the Cloud SQL or GKE API makes Google add its own service agents. A project that uses neither should not get them. So you ask for each by name:

dormeto gcp install --with cloud-sql,gke

The install record keeps your choice. A later run with more adds to it. A run without --with keeps what is there. Only uninstall removes a feature. dormeto gcp check tests a feature only when --with names it or the record has it. The CLI's next run prints any binding Google added.

cloud-sql

Never run against Google yet. A companion database that a nap stops and a wake starts. API: sqladmin.googleapis.com.

gke

Never run against Google yet. Pods behind standalone network endpoint groups, on a load balancer you own. API: container.googleapis.com.

The role grants nothing inside the cluster. When you onboard a workload, the CLI reads the cluster as you. It then prints, asks and applies a Role and a RoleBinding named dormeto-<workload>, in the workload's namespace, for the router's service account. Nothing is cluster-wide, and offboarding removes both. The rules:

• get on deployments, statefulsets.
• list on replicasets.
• patch on deployments/scale, statefulsets/scale.
• list on pods, events.
• list, patch on scaledobjects.

Kubernetes lets you grant only what you hold, so the operator needs container.roles.escalate and container.roles.bind. Google lists container.roles.escalate as TESTING in custom roles.

IP lists

From router 0.35.0. With --ip-list name=<n>,url=<u>[,refresh=<hours>], repeatable, a visit from an address on the list never wakes a workload. An API client's POST /_dormeto/wake still does. --no-ip-lists clears them. They need no extra role. A list's URL, query string included, is printed and stored in the plan, the install record and the services' environment. Keep tokens out of it. A URL with credentials is refused.

If Terraform writes your load balancer and VMs

Terraform doesn't know what the router writes, so every plan offers to undo it. After such an apply, the router's check repairs the URL map within 5 minutes. Until then, a sleeping workload shows the load balancer's own error page and doesn't wake from a browser. Ignore these fields on the resources you wrote, with lifecycle { ignore_changes = [...] }:

With the path matchers ignored, Terraform stops applying your own edits to them. Remove the ignore for that apply. That also removes what the router wrote until its check writes it back. The tag's binding is not a field of these resources, so it needs nothing.

Check

dormeto gcp check is read-only. For each command it prints a tick when you hold every permission it needs, and a cross with the missing ones otherwise. It then prints the project's parent, the APIs already on, and the warnings (the default service account's Editor). It exits 1 when a command lacks a permission. With no role in the project it says so and lists every permission as missing. --json prints the report.

dormeto gcp check --project my-project --region europe-west1

dormeto gcp status shows the router's record and live state: version, services, controller health, queue, job, database and grants.

Remove

dormeto gcp uninstall removes exactly what the install added, in reverse order, from its record. It refuses while workloads are onboarded. --force offboards each one first, tag bindings included. It keeps the custom roles and the tag while another router of the project lists them. It turns no API off. It lists the APIs and Google's bindings as left in place.

dormeto gcp uninstall --project my-project --region europe-west1
dormeto gcp uninstall --project my-project --region europe-west1 --force   # workloads still onboarded

Then, if nothing else in the project needs them, turn the APIs off yourself, and remove the default service account's Editor as above:

gcloud services disable \
  compute.googleapis.com \
  run.googleapis.com \
  firestore.googleapis.com \
  cloudtasks.googleapis.com \
  cloudscheduler.googleapis.com \
  monitoring.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com \
  logging.googleapis.com \
  --project my-project

Google may refuse to turn an API off while another service depends on it, or ask for --force. Decide for each one: these APIs may serve other things in the project.

A deleted queue's name stays blocked for up to 3 days and a deleted database's ID for about 5 minutes. Installing again before then fails, and the CLI says so.