banshee/cloud-collection/cloud/ovh/https/vps

OVHcloud VPS, by the OVHcloud API

Returns the state of each VPS of an OVHcloud account, read through the OVHcloud API with an application's keys that may only read. Two watches are offered, each one set on the probe.

Versions

Generic: the OVHcloud API is the same in its three places, Europe (eu.api.ovh.com), Canada (ca.api.ovh.com) and the United States (api.us.ovhcloud.com), version 1.0. The address is that of protocol:ovh:endpoint, where the keys were created.

How it works

Every request is a GET to <protocol:ovh:endpoint><path>, signed by ovh.sign.

GET /vps: the names of the VPS, ["vps-0a1b2c3d.vps.ovh.net", …].
For each VPS, GET /vps/<name>:

{"name": "vps-0a1b2c3d.vps.ovh.net", "displayName": "web-1", "state": "running", "vcore": 2, …}

A VPS is named by its service name, unique; its display name is the customer's and may repeat.
state is state: running, backuping, installing, maintenance, rebooting, rescued, stopped, stopping or upgrading.
An address of the API not written https://<host>/<version> stops the collector misconfigured before anything leaves.
A code 401 (keys wrong, expired or revoked, or the poller's clock off) or 403 (the consumer key not allowed the route) stops the collector misconfigured; a code 400 or 404 too; any other code but 200 stops it unreachable.

The keys come from protocol:ovh: the application secret never leaves the poller, only the signature it makes; the consumer key goes in a header, to the API only, in HTTPS. The answers are not secret.

Prerequisites

An application created on the API of the account's place, and a consumer key whose access rules allow these routes and nothing else:

{
  "accessRules": [
    { "method": "GET", "path": "/vps" },
    { "method": "GET", "path": "/vps/*" }
  ]
}

The application key goes in protocol:ovh:application-key, its secret in protocol:ovh:application-secret, the consumer key in protocol:ovh:consumer-key, the address of the API in protocol:ovh:endpoint, https://eu.api.ovh.com/1.0. With an IAM policy of OVHcloud instead, the action is vps:apiovh:get.

The poller reaches the API in HTTPS, and its clock is right: OVHcloud refuses a signature too far from its own time. The certificates of OVHcloud are issued by public authorities: the profile "Standard" trusts them.

Variables

The collector declares none of its own: it reads protocol:ovh and protocol:ovh:endpoint.

Outputs

Name	Label	Unit	Per instance
`state`	State	—	yes, per VPS

Watches

Name	Title	Kind	Defaults	Checked by default
`not-running`	VPS not running	expected value, on `state`	critical when neither `running` nor `backuping` for 2 runs: a reboot does not raise	yes
`missing`	VPS missing	expected instances, on `state`	no name given: it raises nothing until names are set on the probe	no

A VPS stopped on purpose is left out by the selection of the probe.

Limits

One call per VPS each run, beside the list.
Not checked against an OVHcloud account: the routes, their fields and their values are those of the schema the OVHcloud API publishes for itself (/1.0/vps.json: vps.VPS, vps.VpsStateEnum), which its console shows; the signature that of "First Steps with the OVHcloud APIs".