banshee/cloud-collection/cloud/ovh/https/dedicated-servers

OVHcloud dedicated servers, by the OVHcloud API

Returns, for each dedicated server of an OVHcloud account, its state as OVHcloud sees it, its power, and how many planned interventions of the datacentre are still to do or in progress, read through the OVHcloud API with an application's keys that may only read. Four 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 /dedicated/server: the names of the servers, ["ns3000000.ip-203-0-113.eu", …].
For each server, GET /dedicated/server/<name>:

{"name": "ns3000000.ip-203-0-113.eu", "state": "ok", "powerState": "poweron", "datacenter": "rbx8", "monitoring": true, …}

For each server, GET /dedicated/server/<name>/plannedIntervention, the IDs of its planned interventions, then GET /dedicated/server/<name>/plannedIntervention/<id> for each:

{"id": 12, "status": "todo", "type": "HARDWARE_UPGRADE_ON_ACTIVE_SERVER", "wantedStartDate": "…", "expectedEndDate": "…"}

A server is named by its service name, the name OVHcloud gives it, unique.
state is state: ok, error, hacked (OVHcloud detected an attack from the server) or hackedBlocked (and cut it off the network).
power is powerState: poweron or poweroff.
interventions counts the planned interventions whose status is todo or doing; done ones are left out.
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 (https://eu.api.ovh.com/createApp/ for Europe), and a consumer key whose access rules allow these routes and nothing else:

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

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 actions are dedicatedServer:apiovh:get and dedicatedServer:apiovh:plannedIntervention/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 server
`power`	Power	—	yes, per server
`interventions`	Planned interventions to do or in progress	—	yes, per server

Watches

Name	Title	Kind	Defaults	Checked by default
`failing`	Server in error	state to avoid, on `state`	critical on `error`, `hacked`, `hackedBlocked`	yes
`powered-off`	Server powered off	state to avoid, on `power`	critical on `poweroff` for 2 runs: a reboot does not raise	yes
`intervention`	Datacentre intervention	above a threshold, on `interventions`	warning above 0	yes
`missing`	Server missing	expected instances, on `state`	no name given: it raises nothing until names are set on the probe	no

Limits

The past interventions (/dedicated/server/<name>/intervention) are not read: OVHcloud gives them a start date and a type, never a status, and nothing in them says whether one is still in progress. Only the planned interventions carry a status.
The route of the planned interventions is marked BETA by OVHcloud: it may change.
Two calls a server, and one more per planned intervention: an account of many hundred servers makes as many requests each run.
Not checked against an OVHcloud account: the routes, their fields and their values are those of the schemas the OVHcloud API publishes for itself (/1.0/dedicated/server.json: dedicated.server.Dedicated, dedicated.server.StateEnum, dedicated.server.PowerStateEnum, dedicated.server.PlannedIntervention, dedicated.PlannedInterventionStatusEnum), which its console shows; the signature that of "First Steps with the OVHcloud APIs".