banshee/cloud-collection/cloud/google/https/compute-instances

Compute Engine instances, by the Compute Engine API

Returns the status of each Compute Engine instance of a Google Cloud project, every zone at once, read through the Compute Engine API with a service account that may only read. Two watches are offered, each one set on the probe.

Versions

Generic: the Compute Engine API is one service, the same for every project. The collector reads its version v1.

How it works

google.token('https://www.googleapis.com/auth/compute.readonly'): an access token for the service account of protocol:google, kept fifty minutes in the probe's cache, encrypted on the poller. A token Google no longer takes answers 401, and the collector asks for a new one, once.
GET https://compute.googleapis.com/compute/v1/projects/<google:project>/aggregated/instances, the token as Authorization: Bearer, page after page by pageToken: the instances of every zone, a scope per zone.

{"items": {"zones/europe-west1-b": {"instances": [{"name": "web-1", "status": "RUNNING", "zone": "https://www.googleapis.com/compute/v1/projects/…/zones/europe-west1-b", …}]}, "zones/us-central1-a": {"warning": {"code": "NO_RESULTS_ON_PAGE", …}}}, "nextPageToken": "…"}

An instance is named <zone>/<name> (europe-west1-b/web-1): a name is unique in its zone only.
status is the status of the instance in lower case: provisioning, staging, running, stopping, stopped, terminated (stopped, by an action or a failure), suspending, suspended, repairing, pending, pending_stop, deprovisioning.
A zone without an instance comes with a warning and no list, and adds nothing.
A code 403 (the role missing, or the Compute Engine API not enabled on the project) stops the collector misconfigured; a code 400 or 404 (the project unknown) too; any other code but 200 stops it unreachable. A key or a scope that Google refuses stops it misconfigured (access_denied, from google.token).

The key comes from protocol:google, a secret variable: google.token signs an assertion with it and sends only the assertion, to Google only. The token is a secret too, kept in the cache and sent in a header. The list is not secret.

Prerequisites

A service account of the project, with a key in JSON, the file Google gives, set in protocol:google:service-account-key.
The role Compute Viewer (roles/compute.viewer) given to it on the project: it reads the resources of Compute Engine and nothing else, neither their data nor their disks. With the Google Cloud CLI: gcloud projects add-iam-policy-binding <project> --member=serviceAccount:<account e-mail> --role=roles/compute.viewer.
The Compute Engine API enabled on the project.
The poller reaches oauth2.googleapis.com and compute.googleapis.com in HTTPS, and its clock is right within a few minutes: Google refuses an assertion signed away from its own time. The certificates of Google are issued by public authorities: the profile "Standard" trusts them.

Variables

Name	Label	Says	Default
`google:project`	Project	the ID of the project, `my-project-123456`	—

Outputs

Name	Label	Unit	Per instance
`status`	Status	—	yes, per instance

Watches

Name	Title	Kind	Defaults	Checked by default
`not-running`	Instance not running	expected value, on `status`	critical when not `running` for 2 runs: a start or a stop in progress does not raise	yes
`missing`	Instance missing	expected instances, on `status`	no name given: it raises nothing until names are set on the probe	no

An instance stopped on purpose is left out by the selection of the probe (Instances: All except europe-west1-b/test-*).

Limits

Not checked against a Google Cloud project: the route, its parameters, the fields and the status are those of the Compute Engine API (instances.aggregatedList, the schemas InstanceAggregatedList, InstancesScopedList and Instance), read in its discovery document as Google publishes it with its client libraries; the role is that of "Compute Engine IAM roles and permissions".