Was kann man mit der Foreman REST API eigentlich alles machen?

Zuviel um es in nur einen Artikel zu packen. Beschränken wir uns erstmal auf das Anlegen, Bearbeiten und Auslesen von Daten.Foreman ist ein OpenSource Tool mit dem man physikalische oder virtuelle Server verwalten kann. Administratoren können so alle am Foreman registrierten Maschinen steuern, einrichten und aktualisieren. Ist der Foreman frisch installiert, gibt es unzählige Einstellungsoptionen um ihn auf die individuellen Bedürfnisse anzupassen. Beispielsweise können Environments, Architekturen, Organisationen und die Locations angelegt werden, die man für die eigene Infrastruktur benötigt. Ist die Konfiguration angelegt, kann man mit der Arbeit oder dem Testen los legen. 

Um sich hier etwas Arbeit zu sparen, kann man sich mit der Foreman REST API verbinden und dort dann über ein selbst erstelltes Script die Daten einspielen. Alle definierten Einstellungen können so z.B. in einer YAML Datei zusammengestellt werden, um dann den Import bzw. das neu Anlegen der Daten zu automatisieren. REST steht für: Representational state transfer und wird mittels HTTP bzw. HTTPS ausgeführt. Die REST Methoden beschreiben die Art und Weise der Datenverbindung für das Auslesen, Aktualisieren, Anlegen oder Löschen von Daten. API steht für: application programming interface. Die API einer Anwendung enthält definierte Url’s für ausführbare Funktionen, wie z.B. das Auslesen von Konfigurationseinstellungen oder auch das Anlegen von neuen Daten.Bei der Verwendung der REST API werden Aufrufe von Web Adressen durchgeführt mit einem oder mehreren entsprechenden Parametern. Sind der Aufruf und die Parameter gültig, werden die angeforderten Informationen oder ein Status vom Zielserver zurückgegeben. Beispielsweise lassen sich alle angelegten Environments im Foreman über folgenden Aufruf (GET Request) auslesen:

https://mein-foreman-server.de/api/environments

Die Informationen vom Foreman Server über die Environments werden dann im JSON Format ausgegeben:

{
  "total": 34,
  "subtotal": 34,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results": [{"created_at":"2015-10-07T07:21:42Z","updated_at":"2015-10-07T07:21:42Z","name":"api_new","id":3},{"created_at":"2015-10-07T07:21:17Z","updated_at":"2015-10-07T07:21:17Z","name":"apitest","id":2}, ...]
}

Wie man sieht, ist das Auslesen von Informationen mit Hilfe der REST API recht einfach.

Schwieriger wird es bei komplexeren Aufgaben in Verbindung mit bestehenden Daten, die in Abhängigkeit stehen. Beispielsweise wenn man mehrere Daten für bereits angelegte Organisationen oder Locations im Foreman einspielen möchte. In diesem Fall muss man etwas aufwändiger einen Import generieren. Hier kommen dann Nachfolgende REST API Optionen ins Spiel, um den Import oder die Anpassungen automatisiert durchführen zu können.

  • Mit der Bash-Shell über den CURL Befehl
  • Mit dem Foreman-API Gem
  • direkt mit einer Programmiersprache

Die REST API Zugriffe auf den Foreman 1.9. haben wir folgendermaßen getestet.

  1. Mit CURL über die Bash-Konsole
  2. Mit Ruby in den Versionen 1.8.7, 1.9.2 und 2.2.0 und den Bibliotheken net/http(s) und uri
  3. Mit Ruby On Rails 4 und dem Gem ActiveResource

Unser Fazit aus den Tests mit der Forman REST API.

Hat man vor die REST API kurz zu testen oder ein paar kleinere Anpassungen per Skript durchzuführen, ist die Verwendung von CURL die wohl einfachste und schnellste Option.

Das Beispiel von oben mit CURL umgesetzt, sieht wie folgt aus.

$ curl -u admin:password -H "Accept:application/json" https://mein-foreman-server.de/api/environments

Möchte man komplexere Importe, Updates oder andere Bereinigungen vornehmen, ist die Verwendung einer Programmiersprache sehr empfehlenswert. In unseren Beispielen konnten wir mit Ruby und dem Gem ActiveResource gut arbeiten und schnell eine leicht verständliche und wiederverwertbare Schnittstelle erstellen.

Ist aber der Einsatz vom Gem ActiveResource oder die Installation auf einem Server nicht möglich, kann man auch mit der auf dem Server vorhandenen Ruby Version schnell ein Programm/Skript erstellen, dass die gewünschten Aufgaben erledigt. Alternativ gäbe es auch noch ein Gem von den Foreman Entwicklern mit dem Namen Foreman API.

Was kann man mit der Foreman REST API eigentlich alles machen? – Eine ganze Menge!

+ posts