Benutzung der ProfitBricks API mit Power Shell – Teil 1 – Basics und Inventarisierung

Mittwoch, 26. Juni 2013, in ProfitBricks Cookbooks, von Thomas Vogel

Benutzung der ProfitBricks API mit Power Shell – Teil 1 – Basics und Inventarisierung

Einleitung

Mit Hilfe der ProfitBricks API können alle Funktionalitäten des ProfitBricks IaaS automatisiert werden. Die API basiert auf SOAP. Die komplette Dokumentation zur Nutzung der API steht unter https://www.profitbricks.com/de/de/iaas-entwickler-center/profitbricks-api/ als Onlinedokumentation und PDF-Dokument zur Verfügung.

Im Folgenden wird beschrieben, wie die ProfitBricks API mit Power Shell angesprochen werden kann und wie Power Shell genutzt werden kann, um Inventar und Status der Ressourcen in den virtuellen Datacentern auszulesen. Zum Beispiel, um diese Daten in die Unternehmensinterne CMDB importieren zu können.

In den angeführten Beispielen werden die Daten jeweils in Dateien vom Type CSV und/oder XML gespeichert. Dieses Beispiel ist sehr vereinfacht. In einer praktischen Umsetzung würde es sinnvoller sein, die ermittelten Daten direkt über eine von der CMDB bereitgestellte API zu senden oder ggf. mit den Power Shell SQL CmdLet in eine Datenbank zu importieren.

Alle Elemente im Datacenter verfügen über eine UUID. Über die UUID können Elemente eindeutig identifiziert werden. die Eigenschaft Name eines Objektes ist hingegen nicht eindeutig. Mehrere Objekte können identische Namen besitzen.

Erzeugen eines Webservice Objektes

Zur Arbeit mit Webservices auf SOAP-Basis stellt Power Shell das CmdLet New-WebServiceProxy zur Verfügung (http://technet.microsoft.com/en-us/library/hh849841.aspx). Das CmdLet erzeugt ein Webserviceproxy Objekt und benötigt lediglich den URI zur WSDL. Es ist jedoch sinnvoll auch einen Namespace und Klassennamen zu definieren. Der Zugriff auf die WSDL kann anonym erfolgen.

$pb_api ist das neu erzeugte Objekt. Mit Hilfe von Get-Member (oder kurz gm) können die Methoden und Eigenschaften des Objektes angezeigt werden. Die Methoden *Async, *Completed, Begin* und End* werden im Folgenden ausgefiltert. Diese werden in den Power Shell Beispielen auch nicht verwendet. Speziell die *Async Methoden können sehr komfortabel verwendet werden, zum Beispiel wenn die ProfitBricks API direkt in .NET verwendet wird.

Gemäß der –namespace Option sind alle Methoden und Eigenschaften, welche anhand der WSDL erzeugt wurden, an der Definition ProfitBricks.* erkennbar.

Authentifizierung an der API

Um die Methoden der API zu verwenden, ist eine Authentifizierung notwendig. Hierfür muss die Eigenschaft Credentials des Webservice Objektes gesetzt werden. Credentials können entweder interaktiv zur Laufzeit abgefragt oder als secure-string im Script hinterlegt werden.

Interaktive Abfrage der Authentifizierung

Mit Hilfe des CmdLet Get-Credentials werden Benutzername und Passwort abgefragt. Die so erzeugten Credentials können direkt an das Webservice Objekt übergeben werden. Anschließend ist die Nutzung der API-Methoden möglich.

Gespeicherte Authentifizierungsdaten

Um Power Shell Skripte ohne Benutzerinteraktion laufen zu lassen, ist es notwendig, die Authentifizierungsdaten zu hinterlegen. Das Passwort eines Credentials Objektes wird als secure String im geschützten Speicher des Benutzers hinterlegt und kann in einen verschlüsselten String umgewandelt werden, z.B. um in einer Konfigurationsdatei oder ähnlichem hinterlegt zu werden. Bitte beachten Sie, dass die Verwendung der CmdLet ConverFrom-Securestring und ConvertTo-SecureString voraussetzen, dass sie vom gleichen Benutzer verwendet werden. Werden ConvertFrom-SecureString und ConvertTo-SecureString von unterschiedlichen Benutzern ausgeführt, muss zusätzlich ein SecureKey angegeben werden.

Zuerst muss ein Credentials-Objekt erzeugt werden. Das Passwort wird dann als verschlüsselter String im folgenden Beispiel in das Dateisystem gespeichert. Dieser Schritt kann interaktiv an der Power Shell Befehlszeile erfolgen.

Das in der Datei, als verschlüsselter String, gespeicherte Passwort kann dann im Power Shell Script genutzt werden, um ein korrektes Credentials-Objekt zu Authentifizierung am Webservice zu erzeugen und an das Webservice-Objekt zu übergeben.

Besonderheiten des Webservice Objektes

Bei der Verwendung der Methoden des Webserviceproxy ergeben sich bezüglich der Eigenschaften einige Unterschiede zur ProfitBricks API Dokumentation. Funktionsbedingt werden beim Erzeugen des Objektes zusätzliche Eigenschaften erzeugt, welche im Eigenschaftennamen auf *Specified enden.

Diese zusätzliche Eigenschaft wird für alle Eigenschaften erzeugt, welche:

  • Nicht vom Typ string sind oder array
  • Die in der WSDL als optional definiert sind

Beispiel:

Die Eigenschaft datacenterVersion ist vom Typ integer und als optional definiert. Der hier hinterlegte Wert ist also nur gültig, wenn die Eigenschaft datacenterVersionSpecified den Wert True besitzt.

Auslesen des Inventars, globale Daten

Als Globale Informationen stehen die Liste der konfigurierten Datacenter, die Liste der Images und die Liste der reservierten IP-Blöcke bereit. Hierfür gibt es folgende Methoden:

  • getAlleDataCenters
    – Gibt Liste der Datacenter zurück
  • getAllImages
    – Gibt Liste der Images zurück. Das Feld serverIds ist seinerseits eine Liste, welche die Zuordnung von Images zu Servern enthält
  • getAllPublicIpBlocks
    – Gibt Liste der IP Blöcke zurück. Das Feld publicIps ist seinerseits eine Liste, welche die Zuordnung von IP Adressen zu Netzwerkkarten enthält. Für eine verwendete Public IP ist hier im Feld nicid die UUID der zugeordneten Netzwerkkarte hinterlegt.

Auslesen der Datacenterliste

Auslesen der Images

Auslesen der IP-Blöcke

Auslesen des Inventars, detaillierte Daten

Auf Basis der erzeugten Objekte $IpBlockList kann durch eine einfache Schleife über alle Elements auf die verknüpften Objekte iteriert werden. Pro Listenelement ist in publicips die Zuordnung zu Netzwerkkarten vermerkt (UUID der Netzwerkkarte).

Die Struktur eines Datacenter-Objektes ist deutlich komplexer als die IP-Blockliste oder Datacenterliste. Diese komplexe Objekt kann pro Datacenter mit der Methode getDatacenter(datacenterid) instanziiert werden. Das Objekt enthält alle Informationen über

  • das Datacenter selbst,
  • Server und deren Verbindung zu Storages und Netzwerkkarten,
  • Storages und deren Verbindung zu Servern und Images,
  • Netzwerkkarten und zugeordneten IPs
  • und so weiter.

Für jedes dieser Elemente stellt die API, und somit unsere erzeugte Instanz $pb_api wiederum Methoden und Eigenschaften zur Verfügung. Objekte können zum Beispiel mittela:

  • $pb_api.GetServer(ServerId)
  • $pb_api.GetStorage(StorageId)
  • $pb_api.GetNic(NicId)
  • u.s.w.

instanziiert werden. So kann zum Beispiel für jedes in $DatacenterList ermittelte Datacenter die Liste der Server und Storages als CSV exportiert werden:

Hierbei werden vom Server- und Storageobjekt einige Eigenschaften nicht in die CSV-Datei ausgegeben. Bei diesen Eigenschaften handelt es sich um komplexe Objekte oder Listen, welche nicht automatisch von Export-csv konvertier- und in die CSV-Datei exportierbar sind. Das Feld connectedStorages ist z.B. eine Liste vom type ProfitBricks.connectedStorage[], welche die detaillierten Eigenschaften zu jedem angeschlossenen Storage widerspiegelt.

Alternativ kann die komplette Struktur eines Datacenters zur Weiterverarbeitung auch als XML exportiert werden.

Auslesen des Inventars, Anwendungsfall Basisinventar

Im folgenden Beispiel interessieren uns nur folgende Eigenschaften:

  • Pro Server:
    • ServerID
    • ServerName
    • ServerStatus
    • Cores
    • RAM
    • MAC-Addresse der ersten Netzwerkkarte
    • Die IP Addrese des ersten Netzwerkkarte
    • Zeitpunkt der Erstellung
    • Zeitpunkt der letzten Änderung
  • Pro Storage:
    • StorageID
    • StorageName
    • StorageStatus
    • Größe
    • ConnectedServerID
    • Zeitpunkt der Erstellung
    • Zeitpunkt der letzten Änderung

Diese Eigenschaften sollen für alle Datacenter in einer CSV Datei mit folgenden Feldnamen hinterlegt werden:

DCname, ID, Type, Name, Status, Cores, Ram, Nic0-MAC, Nic0-IP, Size, Connected, Created, LastModified

Hierzu wird die schon oben verwendete Schleife etwas komplexer. Es werden nur die Eigenschaften eine Servers bzw. eines Storages ausgelesen, welche für den angenommenen Anwendungsfall interessant sind. Diese warden einem Array zugewiesen, welches später in eine CSV-Datai ausgegeben wird.

Wird die so erzeugte CSV Datei in Excel geöffnet, stehen uns alle gewünschten Daten zur Verfügung.

Ich hoffe diese einfachen Beispiele helfen Ihnen beim Einstieg in die Verwendung der ProfitBricks API mit Power Shell.

Demnächst in Teil 2: Provisionieren mit der API und Power Shell

Codebeispiel

Das komplette Codebeispiel ist unter https://github.com/th-m-vogel/ProfitBricks-Webservice-PS-Samples/blob/master/ProfitBricks_API_Inventory_Demo.ps1 zu finden.

Zusätzlich liegt der Code zum Speichern des Passwortes als secured-string unter https://github.com/th-m-vogel/ProfitBricks-Webservice-PS-Samples/blob/master/Save-Password-as-encrypted-string.ps1 .

Hinterlasse eine Antwort

* Pflichtfeld

© 2012-2017 by ProfitBricks