Today, when you deploy a new SDDC on VMware Cloud on AWS (VMC), NSX-T is now the default networking stack and NSX-V is no longer used for net new deployments. In fact, we are about to start migrating existing VMC customers who have an NSX-V SDDC and converting them to an NSX-T SDDC. Humair Ahmed who works over in our Networking & Security Business Unit has an excellent blog post here that goes into more details on what NSX-T brings to VMC.
Upon first glance, you might think that this is the exact same version of NSX-T that we have been shipping to our on-premises customers but in fact, it is actually a brand new and improved version. Similar to vSphere (vCenter and ESXi) and VSAN, VMC is always running a newer version of our software than our on-prem customers. One immediate difference that you should be aware of when using NSX-T in VMC is that the current NSX-T API is not available and instead a new NSX-T Policy API has been introduced to help simplify the consumption of NSX-T. All functionality in the current on-prem NSX-T API can be consumed using the new Policy API.
At VMworld, I spoke to a number of current and upcoming customers with NSX-T based SDDCs and they were really interested in using the new NSX-T Policy API and as the title of this blog post suggests, this will be a quick primer on how to do that. Before we get started, confirm that you have an NSX-T based SDDC deployed. If you are not sure, there are a few ways to determine this using either the VMC Console UI or API, instructions can be found here and here.
There are two ways to interact with the NSX-T Policy API on VMC:
- Connecting to the NSX-T Manager
- Connecting to the VMC Console
The first option is pretty straight forward, so I will not go into detail, you simply connect to the NSX-T Manager like you normally would in an on-prem environment. Having said that, the first option is only available after you setup a VPN or Direct Connect and create an initial firewall rule that allows incoming connection from your source network to the NSX-T Manager in VMC. This poses an interesting chicken/egg problem if you want to fully automate the network configuration, since the NSX firewall blocks all access by default, including access to the NSX-T Manager.
This is where the second option comes in and provides a "Reverse Proxy" to the NSX-T Manager using the VMC Console API, this is the exact same way the UI is able to perform networking changes without direct access to NSX manager. This method enables customers to perform the minimum "Day 0" setup of NSX-T such as configuring a Direct Connect or IPSec VPN and then enabling the firewall to allow your source network to connect to the SDDC, including NSX-T Manager. After that, you have the option of either directly connecting to the NSX-T Manager to perform other configurations or you can continue using the reverse proxy method. You are not limited to a subset of functionality as the reverse proxy simply acts as pass-through to the NSX-T Manager and as mentioned earlier, both options are available.
Note: When working with the NSX-T Policy API in VMC, there are certain values that will be hardcoded and this is purely due to the fact that in VMC, the underlying infrastructure is already setup for customers such as the MGW/CGW gateways. When referencing the NSX-T Policy API documentation, for properties such as <vmc-domain>, this should be replaced with either mgw or cgw as the value.
So, what does the workflow look like from a programmatic standpoint?
Step 1 - Using the VMC Console API, you would first perform a GET /api/orgs/<orgId>/sddcs/<sddcId> on the NSX-T SDDC and retrieve a new property called nsx_api_public_endpoint_url (under resource_config) that provides the base NSX-T Reverse Proxy URL. An example of this URL would look like the following: https://nsx-A-B-C-D.rp.vmwarevmc.com/vmc/reverse-proxy/api/orgs/<orgId>/sddcs/<sddcId>/sks-nsxt-manager
Step 2 - To perform an operation using the NSX-T Policy API, you would specify the VMC Console Access Token as your authentication and then append the specific URL to this base NSX-T Reverse Proxy URL. For example, to list all NSX-T Network Segments (Logical Networks) when going directly to NSX-T Manager, you would perform a GET /policy/api/v1/infra/tier-1s/<networkId>/segments Since, we are using the reverse proxy, then full URL would look like the following: https://nsx-A-B-C-D.rp.vmwarevmc.com/vmc/reverse-proxy/api/orgs/<orgId>/sddcs/<sddcId>/sks-nsxt-manager/policy/api/v1/infra/tier-1s/cgw/segments
To help demonstrate the new NSX-T Policy API, I have created two samples, one using PowerShell and the other using cURL.
Using PowerShell with the NSX-T Policy API:
Step 1 - Install the VMware.VMC.NSXT Community PowerShell module that I have created (I plan to add additional functionality in the future, so stay tuned).
Import-Module VMware.VMC.NSXT
Step 2 - You will need to defined a few variables that will be used by the functions and make it easy to test against different NSX-T based SDDCs:
$RefreshToken - This the Refresh Token from the VM Console (for additional instructions on obtaining this, please take a look at this blog post here)
$OrgName - This is the Organization name which can be found within the VM Console UI
$SDDCName - This is the SDDC name which contains an NSX-T deployment which can be found within the VM Console UI
Step 4 - Connect to the VMC service using the Connect-VmcServer cmdlet and providing your $RefreshToken variable:
Connect-VmcServer -RefreshToken $RefreshToken
Step 5 - Connect to the NSX-T Proxy, which simply retrieves your Access Token from the Cloud Services Platform and setups the NSX-T Reverse Proxy URL which will be used by subsequent functions. You will need to provide the $RefreshToken, $OrgName and $SDDCName as input.
Connect-NSXTProxy -RefreshToken $RefreshToken -OrgName $OrgName -SDDCName $SDDCName
If the command was successful, what the function does is setups a global variable called $global:nsxtConnection which contains the NSX-T Proxy URL which can then be easily referenced when working with the NSX-T Policy API along with the required headers including the csp-auth-token for authenticating to the NSX-T Reverse Proxy endpoint as shown in the screenshot below.
Step 6 - Lastly, lets now make use of this information by running our Get-NSXTSegment function which will return all NSX-T network segments also known as Logical Networks. You can also specify -Name property if you wish to filter a specific segment.
Using cURL with the NSX-T Policy API:
Step 1 - Download the list_vmc_nsxt_network_segments.sh shell script (ensure you have jq utility installed as it uses that to parse the JSON output)
Step 2 - You will need to defined a few variables that will be used by the functions and make it easy to test against different NSX-T based SDDCs:
RefreshToken - This the Refresh Token from the VM Console (for additional instructions on obtaining this, please take a look at this blog post here)
OrgId - This is the ID of your Organization which can be found within the VM Console UI under "Settings" or using the VMC Console API
SDDCId - This is the ID of your SDDC which contains an NSX-T deployment which can be found within theVM Console UI under "Settings" or using the VMC Console API
Step 3 - Simply run the following to list all NSX-T network segments:
./list_vmc_nsxt_network_segments.sh $REFRESH_TOKEN $ORGID $SDDCID
Hopefully this gives a good idea of how to start working with the new NSX-T Policy API in VMC. You can find more details about the NSX-T Policy API by referring to the documentation here. As mentioned above, I plan to add some more functions to the NSX-T Policy PowerShell module, so stay tuned for that and hope to see some contributions from the community as well.
Thanks for the article!
I can't find anything in the API related to DFW, am I missing something?
I'm trying to pull out security groups/policies information
Hi William, thanks for the great info.
When I make a connection to VMC, this works.
Then I can connect to the NSX-T proxy
I can run get-nsxtsegmets with success.
when I want to create a new segment I get the error
The NSX-T Proxy session is no longer valid, please re-run the Connect-NSXTProxy cmdlet to retrieve a new token
this when I run the command using the parameters or by running the command and supply the parameters in the guided execution
Any suggestion?
gert
Did you download the latest version, I had made some changes a few days back due to API changes in VMC
downloaded it today, VMC is setup 1 month ago.
PS C:\Windows\system32> New-NSXTSegment -Name "PCST-CGW-POD-0001" -Gateway $Gateway -Prefix "24" -DHCP -DHCPRange $DHCPRange -Troubleshoot
[DEBUG] - PUT
https://BLABLA.vmwarevmc.com/vmc/reverse-proxy/api/orgs/BLABLA/sddcs/BLABLA/sks-nsxt-manager/policy/api/v1/infra/tier-1s/cgw/segments/PCST-CGW-POD-0001
[DEBUG]
{
"subnets": [
{
"gateway_addresses": [
"10.200.0.1"
],
"dhcp_ranges": [
"10.200.0.2-10.200.0.254"
],
"prefix_len": "24"
}
],
"display_name": "PCST-CGW-POD-0001"
}
Ah, if it was setup a month ago, you might still be on the "Preview" version of NSX-T SDDC which uses the old API. Can you check which version by going to the "Support" tab in your SDDC, it should ideally say 1.5 Patch 1 or greater
I am even better, I am on 1.5 patch 2
I see the problem, it looks like the Segments API also has changed parameters. Give me a few to update and will need to update the examples and my PowerCLI Module
Just fixed my module (submitted a pull request), but for now you can use my latest version https://github.com/lamw/PowerCLI-Example-Scripts/blob/master/Modules/VMware.VMC.NSXT/VMware.VMC.NSXT.psm1
and the new syntax will be:
New-NSXTSegment -Name "sddc-cgw-network-4" -Gateway "192.168.4.1/24" -Network "192.168.0/24" -DHCP -DHCPRange "192.168.4.2-192.168.4.254"Notice that Gateway now requires CIDR based notation and there's no longer a Prefix property but just Network which also requires CIDR notation
GREAT JOB. Works fine now.
a minor thing maybe, if one of the parameters is not filled in correctly, I get the same error about the proxy session not avaialbe.\
but still GREAT JOB
Yea, looking at it again, the try/catch code always defaults to the session rather than looking at response. I need to take another look so the error reporting is better. Maybe during the holidays if I can some time
Is there a special method needed to assign these segments on a Virtual machine vNIC? cannot get it working in powercli, works using the gui
Hi William, I get the following error when trying to connect the NSXT Proxy. I am sure we are running NSX-T as we have SDDC version 1.6.
A server error occurred: 'com.vmware.vapi.std.errors.unauthorized': . Check $Error[0].Exception.ServerError for more details.
At C:\program files\powershell\6-preview\Modules\VMware.VMC.NSXT\VMware.VMC.NSXT.psm1:31 char:9
+ $sddc = $sddcService.get($orgId,$sddcId)
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : OperationStopped: (:) [], CisServerException
+ FullyQualifiedErrorId : VMware.VimAutomation.Cis.Core.Types.V1.CisServerException
This is not an NSX-T based SDDC
What is your Organization Roles? If the role is Support User maybe you will meet that error messages. If right, please re-try to other roles. (Organization member or Owner)
Hi CJ, thank you for the reply. I did figure it out, I was using the numerical ID's for the $OrgName, and $SDDCName. These need to be the actual names, not the ID's assigned to the names. Once I changed my script to use the real names for these variables it worked perfectly.
Great article! Saved my day 🙂
I wish someone told me to go to the user profile in the VMC portal to generate the API token, which is referred in most articles as the "refresh token".
I have a contribution and a question.
First, my goal was to create a bunch of networks of "diconnected" type. The VMware.VMC.NSXT does not allow that, but after playing with the API documentation and reading the responses of networks I created by NSX-T GUI, I added this functionality to that specific module by adding a "disconnected" param and at line 179:
if ($Disconnected) {
$payload = @{
display_name = $Name;
subnets = @($subnets);
advanced_config = @{
connectivity = "OFF"
}
}
}
else {
$payload....
....
}
Rest is straightforward.
Question: William wrote in this article that after the environment had been configured, it is possible to connect to the NSX-T manager directly. While I can access it's endpoint via HTTPS, I have no idea - which credentials to use to login / run commands using Connect-NsxtServer cmdlet?
Please see https://www.williamlam.com/2019/05/connecting-to-nsx-t-policy-api-using-nsx-t-private-ip-in-vmc.html for how to connect to NSX-T Manager using the Private IP
Great. Got it. I understand that my original intent of using standard nsx-t powercli modules is not possible. There is no option to use "username and password" authentication method.
Hey William! Awesome meeting you in Palo Alto. I should probably post this on the VMware.VMC module page, but it bit me here so here I'll post. The VMC module uses -match in the Get-VMCSDDC function. In our case, the DR SDDC names "match" the Prod site name even though they have addition detail in the name. I flipped it to -eq, so no biggy, but it had me scratching my head for longer than I want to admit.
Hi Daniel,
Great meeting you as well. Yea, I just took a look and looks like most of them use -match for some reason. The module itself is actually a collection from a number of contributors, I did not personally work on these base functions. If you can submit a PR on Github, we can have it track and updated that way. Thanks for the feedback
Hi William,
As I code any of the VMWare network products I keep one window open to official docs and the other to your blog entries...and I think I may use your blog entries more often than the official docs. Thanks.
I wanted to extend your example to display the realized logical components for each segment, but I cannot find a way to obtain the logical ports (downlink toward the VMs) of the logical switch:
GET https://xxxx.vmwarevmc.com/vmc/reverse-proxy/api/orgs/xxxx/sddcs/xxxxxx/sks-nsxt-manager/policy/api/v1/infra/realized-state/realized-entities
Providing the intent path for the segment.
This returns three (3) objects: logical switch, logical port (for uplink) and ip pool (for DHCP)
Is there a url (or a realization path) that allows one to list the (downlink) logical ports for the logical switch?
I have tried using:
GET https://xxxx.vmwarevmc.com/vmc/reverse-proxy/api/orgs/xxxx/sddcs/xxxxxx/sks-nsxt-manager/policy/api/v1/infra/realized-state/realized-entity?realized_path=
But this does not provide the logical ports (downlink) of the logical switch.
Perhaps I am misunderstanding something fundamental.
Is there no api to obtain the logical ports (downlink, towards the VMs) of a logical switch in VMC?
Thanks again.
Great work William,
While trying the module i can connect correctly to the NSX Proxy, but any other operation gives me this error:
{
"module_name": "common-services",
"error_message": "Internal server error has occurred.",
"details": "403 Forbidden",
"error_code": "99"
}
From the API Explorer everything is working correctly.
Nevermind, the problem was a missing role in the token.
Great module!
What was the missing role?
Quick question: Are there any plans to either adapt or fork this module for on premise NSX-T?
No plans, most of functionality should work but you’ll have to refactor auth from token->user/pass and remove RP path. You could also look at https://williamlam.com/2017/10/nsx-t-powercli-community-module.html