banshee/cloud-collection/cloud/google/https/cloud-sql

Cloud SQL instances, by the Cloud SQL Admin API

Returns the state of each Cloud SQL instance of a Google Cloud project, an instance stopped by its owner told apart from one that runs, read through the Cloud SQL Admin API with a service account that may only read. Two watches are offered, each one set on the probe.

Versions

Generic: the Cloud SQL Admin API is one service, the same for every engine (MySQL, PostgreSQL, SQL Server). The collector reads its version v1.

How it works

google.token('https://www.googleapis.com/auth/sqlservice.admin'): 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. The Cloud SQL Admin API has no read-only scope: what the token may do is bounded by the role of the service account, which only reads.
GET https://sqladmin.googleapis.com/v1/projects/<google:project>/instances, the token as Authorization: Bearer, page after page by pageToken.

{"items": [{"name": "orders-db", "state": "RUNNABLE", "databaseVersion": "POSTGRES_16", "region": "europe-west1", "settings": {"activationPolicy": "ALWAYS", …}, …}], "nextPageToken": "…"}

A database is named by the name of its instance, unique in the project.
state is the state of the instance in lower case: runnable (running), suspended (not available, a billing problem for instance), pending_create, pending_delete, maintenance, failed, repairing, sql_instance_state_unspecified; and stopped for an instance RUNNABLE whose settings.activationPolicy is NEVER: Google keeps the state of a stopped instance at RUNNABLE, and the policy alone says it is stopped.
A code 403 (the role missing, or the Cloud SQL Admin 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: it names the instances and their settings, never a password.

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 Cloud SQL Viewer (roles/cloudsql.viewer) given to it on the project: it reads the instances and their settings, and nothing else. With the Google Cloud CLI: gcloud projects add-iam-policy-binding <project> --member=serviceAccount:<account e-mail> --role=roles/cloudsql.viewer.
The Cloud SQL Admin API enabled on the project.
The poller reaches oauth2.googleapis.com and sqladmin.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
`state`	State	—	yes, per database

Watches

Name	Title	Kind	Defaults	Checked by default
`not-running`	Database not running	expected value, on `state`	critical when not `runnable` for 2 runs: a maintenance of a few minutes does not raise	yes
`missing`	Database missing	expected instances, on `state`	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 (Databases: All except test-*).

Limits

Not checked against a Google Cloud project: the route, its parameters, its scopes, the fields, the states and the activation policies are those of the Cloud SQL Admin API (instances.list, the schemas InstancesListResponse, DatabaseInstance and Settings), read in its discovery document as Google publishes it with its client libraries; the role is that of "Cloud SQL IAM roles". That a stopped instance stays RUNNABLE with the policy NEVER is read from the descriptions of the schema ("The instance is running, or has been stopped by owner").