Er zijn verschillende goede redenen om een Software Defined Network (SDN) te implementeren met VMware NSX, waaronder: lagere operationele kosten, kortere implementatietijd, betere beveiligingsmogelijkheden, flexibiliteit en hogere beschikbaarheid. Maar het grootste voordeel van een SDN is toch wel dat deze met software is aan te sturen. Door middel van een Application Programming Interface (API) kan andere software, bijvoorbeeld een Cloud Management Systeem, een netwerk uitrollen en direct VM’s koppelen aan dit netwerk. De uitrol van het netwerk kan dus worden geautomatiseerd, wat het mogelijk maakt om deze in enkele minuten consistent (lees: reproduceerbaar) uit te rollen. Dit automatiseren kan uitstekend met bijvoorbeeld VMware vRealize Automation, maar uiteraard ook met Microsoft Windows PowerShell.

Deze blogserie bestaat uit meerdere delen, die in de komende maanden uitkomen. De volgende delen zijn op dit moment gepland:

1. Wat is de VMware NSX REST API (deze blogpost)
2. Aanroepen van de VMware NSX REST API met PowerShell
3. Met PowerShell aanmaken van een eenvoudig 3-tier netwerk in VMware NSX
4. PowerNSX
5. Van virtueel naar visueel: Genereer een netwerkdiagram met PowerNSX
6. Kloon uw netwerk: van productie naar test met REST
7. …

Deel 1: Wat is de VMware NSX REST API

VMware NSX wordt beheerd door vCenter en de NSX Manager, samen de managementlaag van VMware NSX. NSX Manager zorgt daarbij voor uitrol van de NSX Controllers, installatie van de benodigde software op de vSphere Hosts, aanmaken van routers, configuratie van switches en de firewall rules.

NSX Manager heeft zelf geen grafische gebruikersinterface voor de configuratie van het netwerk, dit gebeurt door middel van plug-ins in de web interface van vCenter of vanuit bijvoorbeeld VMware Automation/Orchestrator. Deze plug-ins en producten roepen vervolgens via een Application Programming Interface de NSX Manager aan.

Een Application Programming Interface, oftewel API, is een manier waarop een computerprogramma kan communiceren met een ander programma. Een soort contract met definities, regels en protocollen die programma’s kunnen gebruiken om onderling te communiceren.

De API van VMware NSX is gebaseerd op Representational State Transfer, oftewel REST, vandaar de naam: REST API. Een REST API is gebaseerd op een software architectuur waarbij de implementatie van de “leverancier” (de server) onafhankelijk is gemaakt van de implementatie van de “gebruiker” (de client). De REST API doet dit door gebruik te maken van HyperText Transfer Protocol (HTTP) voor het transport van de gegevens, Extensible Markup Language (XML) of JavaScript Object Notation (JSON) voor de uitwisseling van de gegevens en een Uniform Resource Identifier (URI) om het object aan te wijzen waarop de opdracht betrekking heeft.

De meeste mensen kennen de URI onder de naam Uniform Resource Locator (URL), maar eigenlijk is de URL alleen het adres van de server, bijvoorbeeld het adres van een webserver. De Uniform Resource Name (URN) is de naam van het object, bijvoorbeeld de naam van de pagina. De URI is de combinatie van de URL en de URN, oftewel:

 

Dit maakt samen:

 

Daarnaast bevat de URI ook nog de “scheme”, vrij vertaald: de manier waarop de resource benaderd wordt. In het geval van REST is dat HTTP of HTTPS. De volledige URI inclusief scheme wordt dan bijvoorbeeld:

https://en.wikipedia.org/wiki/Representational_state_transfer

Als je bovenstaande URI volgt dan kun meer details over REST lezen. De reden waarom ik bij dit voorbeeld de URI van een webpagina heb gebruikt, is omdat een webserver ook een REST API implementeert, waarbij de uitvoer, HTML, een specifieke vorm is van XML. De webbrowser (de client) stuurt dus een verzoek naar de webserver (de server) voor een specifieke pagina (aangeduid door de URI). De webserver stuurt het resultaat terug als HTML, dat door de webbrowser aan de gebruiker wordt getoond. Niets nieuws onder de zon dus.

Een programma dat gebruik maakt van de NSX REST API stuurt een opdracht via het HTTPS-protocol naar NSX Manager. NSX Manager voert de opdracht uit en geeft het resultaat terug. Er zijn maar 4 opdrachten die je kunt gebruiken met de REST API:

• GET: voor het ophalen van een object;
• POST: voor het toevoegen van een nieuw object;
• UPDATE: voor het wijzigen van een object;
• DELETE: voor het verwijderen van een object;

Alle NSX-objecten en bijbehorende URI’s (voor versie 6.2.x van VMware NSX) zijn te vinden in de NSX vSphere API Guide:

https://pubs.vmware.com/NSX-62/topic/com.vmware.ICbase/PDF/nsx_62_api.pdf

Deze blogpost beperkt zich tot de eerste opdracht, GET, voor het ophalen van een object. We gaan de in NSX gedefinieerde transport zone(s) ophalen. We maken nog geen gebruik van PowerShell, zie hiervoor de volgende blog, maar van een REST-client.

Ik maak zelf gebruik van de Advanced Rest Client (ARC), een plug-in voor de Google Chrome webbrowser, maar er zijn ook andere REST-clients. De ARC is als volgt te installeren: Start google en zoek naar ‘Advanced Rest Client’:

Klik op het aangegeven resultaat en installeer de plug-in. Na installatie van de plug-in kun je ARC starten door naar chrome://apps te gaan en op ARC te klikken:

Als je nu in ARC de URI intypt voor het ophalen van de transport zones (zie voorbeeld 2-26 op pagina 39 van de NSX vSphere API Guide):

https://nsxmanager/api/2.0/vdn/scopes

en drukt op ‘Send’, dan krijg je waarschijnlijk het volgende resultaat (zie de rode pijl):

Als je op het vraagteken klikt dan krijg je de melding “No response”. De reden voor dit resultaat is een ongeldig certificaat, bijvoorbeeld een self-signed certificaat dat standaard wordt gemaakt als je NSX Manager installeert.

Je kunt dit probleem op één van de volgende manieren oplossen:

1. Een geldig certificaat configureren;
2. Het gebruikte (self-signed) certificaat als vertrouwd certificaat aan laten merken;
3. Door deze tijdelijk (gedurende de sessie) te accepteren als vertrouwd;

Oplossing 1 en 2 vallen buiten de scope van deze blogpost. Oplossing 3 kan door (in een ander tabblad) de URI direct aan te roepen en te klikken op ‘Advanced’ en daarna op ‘Proceed to nsxmanager (unsafe)’:

Daarna krijg je het volgende resultaat:

Ga nu terug naar het ARC tabblad en druk nogmaals op ‘Send’.

Uiteraard krijg je ook hier als status ‘403: Forbidden’ terug. De reden voor deze status is dat de NSX REST API verwacht dat je een gebruikersnaam en wachtwoord van een geldige gebruiker meestuurt. Dit doe je als volgt:

1. Klik op ‘Form’ (eerste pijl);
2. Vul ‘Authorization’ in bij het eerste veld (zie ovaal);
3. Selecteer het veld achter ‘Authorization’ (het blauwe veld);
4. Klik op ‘CONSTRUCT’ (tweede pijl);

Je krijgt nu een pop-up. Vul de gebruikersnaam en wachtwoord in van een geldige gebruiker:

En klik op ‘OK’. Het resultaat is:

De tekst achter ‘Basic ‘ is je gebruikersnaam en wachtwoord in Base64-formaat (beter bekend als UUENCODE). Dit lijkt een versleuteld wachtwoord, maar is het niet, vandaar dat ik het onzichtbaar heb gemaakt.

Als je nu op ‘Send’ klikt dan krijg je wel een geldig resultaat terug:

De status is nu ‘200: OK’. Let vooral op het content-type in de header (klik eventueel op ‘Response headers’). Hier staat voor VMware NSX altijd ‘application/xml’, wat betekent dat het resultaat een XML-document is. Dit XML-document staat onder in het scherm (ik laat hier alleen een klein gedeelte zien).

Met enige moeite is XML voor een mens leesbaar, maar gebruiksvriendelijk zal ik dit niet willen noemen. Toch is het gebruik van een REST-client een uitstekende manier om de werking van de NSX REST API te doorgronden. Een scripttaal zoals PowerShell kan gelukkig veel beter overweg met XML-documenten. In de volgende blogpost zal ik dit laten zien.