As more customers and partners on-board the VMware Cloud on AWS service, the topic of Automation has been coming up more frequently. There are a number of resources that are available to help users get started including here, here, here, here and here to just name a few.
Customers and partners can spin up 1-Node SDDC which includes the full stack (vSphere, vSAN and NSX-T), fully configured and ready for use for less than $8/hour (list price) and start exploring the rich APIs provided by the VMware Cloud on AWS service. Nothing beats playing with the real thing but we definitely have heard from customers and new developers that it would be nice to have the ability to test out some of the Automation prior to running against a real SDDC.
The VMware Cloud APIs is based on OpenAPI (formally Swagger) and has a very rich eco-system of tools that are available to developers and end-users. One really cool thing you can do with OpenAPIs is to "mock" or simulate the APIs just based on your API specification. This is really useful for API development but it can also come in handy for end users to be able to try out your APIs. Prism Mock by Stoplight is an OpenAPI mocking tool that was introduced to me by Jake Robinson.
Over the break, I finally found some time to play with this tool and I think this could be really useful for those wanting to get a taste of the various VMware Cloud APIs. As I have mentioned already, nothing beats the real APIs and there are some limitations with the mocking tool, so you should still consider using the real APIs when you are ready.
Step 1 - Login to the VMware Cloud on AWS service and navigate to Developer Center->API Explorer and select the respective VMware Cloud API (Cloud Services, VMware Cloud on AWS or NSX VMC Policy API) and then download the respective OpenAPI/Swagger specification which can be found in the lower right hand corner.
Since an existing VMware Cloud on AWS account is required to retrieve the latest OpenAPI/Swagger specification, I have gone ahead and pre-downloaded the current version which can be found in the links below. It is still recommended to download the latest version by logging into the service, especially as new versions and features are constantly being released.
- Cloud Services Platform Spec: https://raw.githubusercontent.com/lamw/vmc-api-simulation/master/vmware-cloud-services.json
- VMware Cloud on AWS Spec: https://raw.githubusercontent.com/lamw/vmc-api-simulation/master/vmware-cloud-on-aws.json
- NSX-T Policy Spec: https://raw.githubusercontent.com/lamw/vmc-api-simulation/master/nsx-vmc-policy-api.json
Step 2 - You can install the Prism tool locally on your system but in this example, we will be using their Docker container which makes setting this up a breeze. You will need to have Docker installed on your system before proceeding. There are two options for loading a OpenAPI/Swagger spec, the first is from a locally downloaded file and the second is pointing to a hosted file.
Option A:
JSON_SWAGGER=vmware-cloud-on-aws.json
docker run --init --rm -p 4010:4010 -v $(pwd)/${JSON_SWAGGER}:/tmp/${JSON_SWAGGER} stoplight/prism:3 mock -h 0.0.0.0 /tmp/${JSON_SWAGGER}
Option B:
docker run --init --rm -p 4010:4010 stoplight/prism:3 mock -h 0.0.0.0 https://raw.githubusercontent.com/lamw/vmc-api-simulation/master/vmware-cloud-on-aws.json
If everything was loaded successfully, you should see a status message stating that Prism is now listening on localhost:4010
Step 3 - Lets now interact with Prism and in our example, we have loaded the VMware Cloud on AWS specification, so lets try a basic example by listing an SDDC Organization. For this API specifically, we need to provide one mandatory header which is the csp-auth-token that would normally provide authentication and authorization purposes for the VMware Cloud on AWS API.
Since we are mocking the API, we just have to set the header with some random value. Below is example using the Postman client to perform a GET /orgs and we get back some data from our API specification as expected.
We can also confirm the API request was successful as Prism was able to find a match based on the provided specification and this can be useful for debugging purposes if you are having trouble calling a specific API.
Here is another example calling into our mock API via cURL:
curl -H "csp-auth-token:foobar" localhost:4010/orgs
Here are some additional examples VMware Cloud on AWS examples that you can also try out:
Create a new SDDC:
- Method: POST
- URL: http://localhost:4010/orgs/1d1c83ee-e0b7-4de9-b660-9a9ca1d22f32/sddcs
{
"name": "WILLIAM-SDDC-01",
"num_hosts": 4,
"provider": "AWS",
"region": "US_WEST_2",
"deployment_type": "SingleAZ",
"sddc_type": "1NODE",
"vpc_cidr": "10.2.0.0/16"
}
Provision an additional host to SDDC:
- Method: POST
- URL: http://localhost:4010/orgs/1d1c83ee-e0b7-4de9-b660-9a9ca1d22f32/sddcs/1d1c83ee-e0b7-4de9-b660-9a9ca1d22f32/esxs
{
"num_hosts": 1,
"availability_zone": "us-west-2b",
"cluster_id": "e1135b98-d7d9-4c2d-b197-d4d71e074865"
}
Cloud Services Platform API:
Here is an example for listing service definitions:
curl -H "Accept:application/json" -H "Content-Type:application/json" -H "csp-auth-token:foobar" http://localhost:4010/slc/api/definitions
NSX-T Policy API
Here is an example for listing all Tier-1 Gateways:
curl -H "Accept:application/json" -H "Content-Type:application/json" -u foo:bar http://localhost:4010/infra/tier-1s
Note: Unlike the real VMware Cloud on AWS API which supports NSX-T Policy API via the NSX-T Reverse Proxy, which is a backend implementation not directly visible to end users. The mock method is limited to just the exposed NSX-T Policy API, this means you will have limited access to the types of APIs you can call. For more complete experience, you may want to download the NSX-T on-prem OpenAPI/Swagger so that you can exercise certain functionality like creating an NSX-T Segment which requires the creation of a Tier-1 which is not exposed as part of the NSX-T Policy API in VMware Cloud on AWS.
Mocking Multiple VMware Cloud API endpoints
Prism only supports loading a single OpenAPI/Swagger spec at a given time. If you have multiple files that you wish to mock, you would have to start multiple Docker Containers and ensuring they are all running on different ports to ensure there are no collision. Not exactly the best user experience but certainly doable. While browsing the existing issues, it looks like this particular request has come up before and nifty solution was shared by leveraging nginx as a reverse proxy to the various specs you wish to mock.
The one downside is that you do have to assign a prefix for each additional API endpoint for mocking. For example instead of /orgs you would need to do something like /vmc/orgs where "vmc" is the prefix to describe the VMware Cloud on AWS API spec. Using the three VMware Cloud APIs, I have updated the nginx configuration file along with Docker Compose YAML to have the following three endpoints, which are now reachable on port 8080.
- http://localhost:8080/csp/...
- http://localhost:8080/vmc/...
- http://localhost:8080/vmc-nsx/...
Below are the instructions for setting up the repository for mocking multiple VMware Cloud APIs.
Step 1 - Clone the following Github repo https://github.com/lamw/vmc-api-simulation
Step 2 - Run the following command to startup the Docker Containers:
docker-compose up
Step 3 - To verify that everything is working, we can now perform a request via cURL/Postman to following URL and you should get a response as before.
localhost:8080/vmc/orgs
Thanks for the comment!