Foreman API

Einige Informationen aus dem Foreman können via API abgefragt werden. Damit können dann wiederum vereinzelte Tätigkeiten automatisiert werden. Hier wird dokumentiert, wie die Foreman REST-API zu benutzen ist und welche Endpoints (aktuell) relevant sind.

Benützung

Der einfachste Weg, die API zu benutzen, ist via Access-Token. Dieser kann in der Weboberfläche des Foremans erstellt werden.

Erstellung eines Access-Token

1. Rechts oben auf Profil, dann auf "Mein Account" klicken.
2. Den Tab "Persönliche Zugriffstokens öffnen"
3. Auf "Persönliches Zugriffstoken hinzufügen" klicken und Formular mit Token-Namen und optionalem Ablaufsdatum befüllen.
4. Auf "Bestätigen" klicken und neu erstellten Token kopieren.

Verwendung eines Acccess-Tokens

Verwendung in curl

Mit curl kann der Token einfach im Zusammenhang mit dem Benutzernamen nach der --user-Option benutzt werden

curl --user <username>:<token> https://foreman.iteas.tools/api

Verwendung in Insomnia

Um den Token in Insomnia zu verwenden, geht man beim gewählten Request auf den Tab "Auth", wählt als Authentifizierungsart "Basic" aus, und füllt die Felder "USERNAME" und "PASSWORD" mit Benutzernamen und Token aus.

Relevante Endpunkte

Hier werden Endpunkte beschrieben, die für uns (aktuell) relevant sind

Facts

Mit dem Facts-Endpunkt können die Fakten eines Hosts ausgelesen werden. Verwdendet man den Endpunkt ohne Parameter, bekommt man eine paginierte Auflistung der einzelnen Fakten für einen Host

URL: /api/hosts/<host_id>/facts
Methode: GET
Response:

{
 "total": 838,
 "subtotal": 1,
 "page": 1,
 "per_page": 20,
 "search": " host = 2",
 "sort": {
  "by": null,
  "order": null
 },
 "results": {
  "foreman-test-client.app.iteas.at": {
   "mountpoints::/dev/shm": null,
   "networking": null,
   "mountpoints::/dev/mqueue": null,
   "mountpoints::/dev/pts": null,
   "mountpoints::/run": null,
   "disks": null,
   "mountpoints::/": null,
   "memory::system": null,
   "mountpoints": null,
   "mountpoints::/dev": null,
   "memory": null,
   "dmi::product": null,
   "dmi": null,
   "dmi::bios": null,
   "disks::sda": null,
   "identity": null,
   "augeas": null,
   "dmi::chassis": null,
   "memory::swap": null,
   "networking::interfaces": null
  }
 }
}

Um genauere Infos zu einzelnen Fakten zu bekommen, muss danach gesucht werden. Z. B. URL: /api/hosts/<host_id>/facts
Methode: GET
Params: search=/runs::
Response:

{
 "total": 846,
 "subtotal": 1,
 "page": 1,
 "per_page": 20,
 "search": "/run:: host = 2",
 "sort": {
  "by": null,
  "order": null
 },
 "results": {
  "foreman-test-client.app.iteas.at": {
   "mountpoints::/run::capacity": "0.00%",
   "mountpoints::/run::available": "50.35 GiB",
   "mountpoints::/run::size": "50.36 GiB",
   "mountpoints::/run::available_bytes": "54067888128",
   "mountpoints::/run::size_bytes": "54068621312",
   "mountpoints::/run::used": "716.00 KiB",
   "mountpoints::/run::used_bytes": "733184",
   "mountpoints::/run::options": "[\"rw\", \"nosuid\", \"nodev\", \"size=52801388k\", \"nr_inodes=819200\", \"mode=755\", \"uid=100000\", \"gid=100000\", \"inode64\"]",
   "mountpoints::/run::filesystem": "tmpfs",
   "mountpoints::/run::device": "tmpfs"
  }
 }
}

Der "search"-Parameter durchsucht den kompletten Namen des Facts auf einen Match, also ist beim Setzen des Such-Strings aufzupassen, dass wirklich das abgefragt wird, was gewollt ist.