API
Die eigene Automatisierung eines Mandanten spricht mit Heinzel Pro über HTTP und JSON: eine Pipeline, die den Agenten ein Deployment prüfen lässt, ein Skript, das Server anlegt, ein Bericht, der jeden Morgen abgeholt wird.
Tokens
Ein Administrator erzeugt ein Token unter API-Tokens. Es wird einmal angezeigt. Ein Token
- handelt im Namen der Person, die es erzeugt hat, und darf nicht mehr als diese Person im Moment des Aufrufs; es endet, wenn die Person den Mandanten verlässt oder deaktiviert wird,
- wird durch seine Bereiche eingeengt:
read,sessions,servers, - kann nach einer Zahl von Tagen enden und jederzeit widerrufen werden,
- gibt nie einen Befehl frei. Es sieht, was wartet, und es kann ablehnen; eine Freigabe ist ein Mensch, der einen Befehl im Browser liest.
Jeder Aufruf trägt das Token in einem Header und den Mandanten in der Adresse:
$ curl -H "Authorization: Bearer hzp_…" https://host/api/v1/<mandant>/serversEin unbekannter Mandant, ein falsches und ein beendetes Token bekommen alle
401 mit demselben Inhalt. Ein Aufruf, den der Bereich des Tokens nicht
abdeckt oder den die Person des Tokens nicht machen darf, bekommt 403; einer,
der sich so, wie die Dinge stehen, nicht ausführen lässt (eine Sitzung, die
beschäftigt ist, ein Befehl, der nicht mehr wartet), bekommt 409. Aufrufe werden je Adresse gezählt, bevor das Token
angesehen wird (120 pro Minute als Vorgabe).
Aufrufe
| Aufruf | Bereich | Was er tut |
|---|---|---|
GET /servers | read | Die Server, jeder mit seinen Zugängen (logins); ssh_user und sudo sind die des ersten. |
POST /servers | servers | Legt einen an: hostname, optional ssh_user und sudo (sein erster Zugang), port, description, tags und ceiling (-, r, rw, rwx; das alte mode mit managed, read_only, blocked und das alte owner_mode setzen ihn weiter). Gibt den öffentlichen Schlüssel zurück, der dort zu hinterlegen ist. |
GET /sessions | read | Die Sitzungen, die die Person des Tokens sehen darf. |
POST /sessions | sessions | Startet eine: server (Hostname) und task. Gibt ID und Adresse zurück. |
GET /sessions/:id | read | Zustand, die letzte Antwort des Agenten, seine Zusammenfassung, die Befehle. |
POST /sessions/:id/messages | sessions | Schreibt text in eine Sitzung. |
GET /sessions/:id/record | read | Das Änderungsprotokoll als Markdown. Fragen Sie mit Accept: application/json oder ohne; die Antwort ist text/markdown. |
GET /approvals | read | Die Befehle, die auf einen Menschen warten, für ein Token, dessen Person freigeben darf. |
POST /approvals/:id/deny | sessions | Lehnt einen ab, mit optionaler note. |
GET /findings | read | Die offenen Befunde. |
GET /schedules | read | Die Zeitpläne. |
POST /schedules/:id/run | sessions | Führt einen jetzt aus. |
Eine über die API gestartete Sitzung ist eine gewöhnliche Sitzung: Ihre Befehle warten auf Freigabe, wie die Richtlinie es sagt, und ihre Seite im Browser ist der Ort, an dem sie freigegeben werden.
Der Befehl heinzel
cli/heinzel im Repository ist ein Shell-Skript über diesen Aufrufen. Es
braucht curl und für lesbare Listen jq.
$ export HEINZEL_URL=https://host/api/v1/<mandant>
$ export HEINZEL_TOKEN=hzp_…
$ heinzel run web1.example.com "Prüfe, warum nginx 502 liefert"
$ heinzel show <sitzung>
$ heinzel approvalsDas Token geht an curl in einer Datei, die nur Sie lesen können, nicht über
die Befehlszeile.