Chapter 14. Using REST API to manage NSX and vRealize Automation

Not all of the VMware products have native support in PowerCLI. Luckily, most VMware products have a representational state transfer (REST) API. PowerShell has the Invoke-RestMethod cmdlet that makes it the easy-to-use REST APIs. In this chapter, we will focus on using REST APIs from PowerCLI. We will use examples from VMware NSX and VMware vRealize Automation to show you the power of the REST APIs.

Just like VMware vSphere is VMware's product for compute virtualization, VMware NSX is VMware's product for network virtualization. It offers distributed switching and routing, distributed firewalling, load balancing, Network Address Translation (NAT), Virtual Private Network (VPN), and many more features. VMware NSX is one of the products you can use to build a Software Defined Data center (SDDC).

vRealize Automation (vRA) is VMware's product to create a self-service portal for an Infrastructure as a Service (IaaS) solution. In...

Connecting to REST API servers

REST APIs provide a way to connect to servers by making requests in the Hypertext Transfer Protocol (HTTP) or the Hypertext Transfer Protocol Secure (HTTPS). The requests you send to the servers are in the form of a Uniform Resource Identifier (URI). The responses to the requests may be in Extensible Markup Language (XML), HyperText Markup Language (HTML), or JavaScript Object Notation (JSON). REST APIs use a stateless protocol. This means that the servers don't know what your previous request was. You have to send all the necessary information, such as credentials, in every request you make.

Tip

To connect your PowerCLI session to an NSX Manager, access to port 443/TCP is required for REST API requests.

The Invoke-RestMethod cmdlet sends an HTTP or HTTPS request to a RESTful web service. The syntax of the Invoke-RestMethod cmdlet is as follows:

Invoke-RestMethod [-Uri] <Uri> [-Body <Object>] [-Certificate
    <X509Certificate>] [-CertificateThumbprint...

Managing NSX logical switches

NSX logical switches are distributed switches just like vSphere distributed switches. Each logical switch is mapped to a unique Virtual eXtensible LAN (VXLAN). The VXLAN carries the virtual machine traffic over the physical network. The physical network can be a routed OSI layer three network. All the ESXi hosts in a vSphere cluster can share one or more NSX logical switches.

In the following sections, Creating NSX logical Switches , Retrieving NSX logical switches , and Removing NSX logical switches , you will learn to create, retrieve, and remove NSX logical switches using the NSX REST API.

Creating NSX logical switches

In the following screenshot of the vSphere Web Client, you can see that in order to create a new NSX logical switch you have to specify a name, transport zone, and the replication mode. Optionally, you can specify a description, enable IP discovery, and enable MAC learning.

In the NSX vSphere API Guide, NSX 6.2 for vSphere, example 7-23. Create...

Managing NSX logical (distributed) routers

Before NSX, if you created a router in your network, it would be a physical or virtual machine connecting two or more networks. All of the traffic from one of the networks to another network connected to the router had to go through the router. Even if two virtual machines connected to different networks were on the same host, if the router were physical or virtual on another host, the traffic would go from the virtual machine off the host to the router and then back to the host and the other virtual machine. In NSX, routing is distributed over the hosts. Every host does a part of the routing. Traffic from one virtual machine to another virtual machine on the same host on a different network connected to the same router does not leave the host in NSX. This is a huge advantage of routing in NSX over traditional routing. NSX Edge logical routers are used for East-West network traffic. This means network traffic within a data center. In the following...

Managing NSX Edge services gateways

NSX Edge services gateways are for the connection between your data center and external networks. This is what we also call North-South network traffic. NSX Edge services gateways are deployed as a virtual appliance and provide services, such as VPN, NAT, load balancing, DHCP, and firewall.

Retrieving NSX Edge services gateways

To retrieve NSX edge services gateways, we use the same URI as in the preceding section, Creating NSX Edge services gateways , and save it in the variable $Uri, as follows:

PowerCLI C:\> $Uri = "https://$NSXManager/api/4.0/edges"

We use the Invoke-RestMethod cmdlet with the GET method to retrieve the edges and save the result in the variable $xml, using the following command:

PowerCLI C:\> $xml = Invoke-RestMethod -Uri $Uri -Method Get
    -Headers $Headers

Because the Invoke-RestMethod call returns the NSX edge services gateways and the NSX logical (distributed) routers, we pipe the output of $xml.pagedEdgeList.edgePage...

Connecting to vRA servers

Using VMware vRealize Automation, you can create a web portal to automate the deployment and management of applications on multicloud environments, such as vSphere, vCloud Director, and Amazon Web Services. The service catalog provides items that users can request.

There are some differences between using the REST API of NSX and the REST API of vRA. The REST API of vRA uses JavaScript Object Notation (JSON) instead of XML. Instead of basic authentication, the REST API of vRA uses a bearer token. You get a bearer token by authenticating to the vRA identity service.

Tip

To test the examples about vRealize Automation in this chapter, you can use the VMware Hands-On Lab HOL-1721-USE-1 - vRealize Automation 7 Basics or any other vRealize Automation Hands-On lab available on http://labs.hol.vmware.com/ . You can use the SEND TEXT button in the Hands-On Lab to send a text to the console. The button is on the upper left-hand side of your window.

In the following example...

Managing vRA tenants

A tenant is an organizational unit in vRA that can be a company or a business unit in an enterprise. After deploying vRA, you will only have a default tenant named vsphere.local. To create a new tenant, you have to connect to vRA using the [e-mail] account that has the system administrator role in the vsphere.local tenant. In the preceding section, Connecting to vRA servers , we have already retrieved a bearer token for the [e-mail] account. In the following section, Creating vRA tenants , we will create a new tenant named Research.

Creating vRA tenants

To create a new tenant, we save the tenant name in the variable $Tenant, as follows:

PowerCLI C:\> $Tenant = 'research'

We will save the URI specifying the identity service and the name of the new tenant in the variable $Uri, using the following command:

PowerCLI C:\> $Uri = "https://$vRAServer/identity/api/tenants/$Tenant"

Next, we create a JSON here-string containing id, urlName...

Retrieving vRA business groups

A business group in vRA is a subdivision of the users in a tenant. A business group is also named a subtenant in the vRealize Automation API. Each business group must have a reservation of servers, storage, and networks.

To retrieve the vRA business groups of the vsphere.local tenant, we connect to the vRA server using the [e-mail] account that has the tenant administrator role and the IaaS administrator role in the vsphere.local tenant. The following code is similar to the code in the preceding section, Connecting to vRA servers . First, we will save the server name, username, password, and tenant name in variables, using the following commands:

PowerCLI C:\> $vRAServer = 'vra-01a.corp.local'
PowerCLI C:\> $Username = '[e-mail]'
PowerCLI C:\> $Password = 'VMware1!'
PowerCLI C:\> $Tenant = 'vsphere.local'

We will create a JSON here-string to store the username, password, and tenant name in the variable $Body, as follows...

Managing vRA reservations

Reservations in vRealize Automation are resources, such as CPU, memory, storage, and network port groups reserved for the business group. You have to create a business group before you can create a reservation. In the following sections, Creating vRA reservations and Retrieving vRA reservations , we will create and retrieve reservations.

Creating vRA reservations

To create a reservation, you have to create a JSON string that specifies the properties of the reservation. In the following code, we will make a here-string containing the specification of the reservation we are going to create. We will save the here-string in the variable $Body. The specification includes properties such as name, reservationTypeId, tenantId, subTenantId, and ExtensionData that contains the reserved values for the reserved networks, memory, compute resources, and storages. The here-string is too big to include in this chapter. Please download the code from the Packt website https://www...

Managing vRA machines and applications

In vRA, new machines and applications are created by selecting them from the catalog, specifying the required settings, such as the number of machines or applications to create, and submitting a request to create the machines or applications. In the following sections, Retrieving entitled catalog items , Retrieving a template request for an entitled catalog item , Creating vRA machines , Viewing details of a machine request , and Retrieving provisioned resources , we will walk you through the workflow to provision new machines or applications.

Retrieving entitled catalog items

We will use [e-mail] user account to deploy a CentOS 6.6 machine. First, we have to connect to the vRA server with the [e-mail] account using the following code we have used before in the section Connecting to vRA servers :

$vRAServer = 'vra-01a.corp.local' 
$Username = '[e-mail]' 
$Password = 'VMware1!' 
$Tenant = 'vsphere.local...

Summary

In this chapter, you learned to use REST APIs from PowerCLI with examples from VMware NSX and vRealize Automation. You saw how to connect to NSX servers using basic authentication and to connect to vRealize Automation servers with a bearer token. The NSX examples used XML and the vRealize Automation examples used JSON.

We discussed managing NSX logical switches, logical (distributed) routers, and edge services gateways. The vRealize Automation examples were about managing vRA tenants, reservations, and resources.

In the following chapter, you will learn how to report with PowerCLI.