vsphere APIs and SDKs First Published On: Last Updated On:

Transcription

1 First Published On: Last Updated On:

2 Table of Contents 1. vsphere Automation APIs (REST) 1.1.vSphere API Explorer 1.2.vSphere Automation APIs - Introduction 2. vsphere Automation SDKs 2.1.vSphere Automation SDK for REST - Getting Started Part vSphere Automation SDK for REST - Getting Started Part vSphere Automation SDK for Python - Getting Started 2

3 1. vsphere Automation APIs (REST) This section describes the REST APIs that are publicly exposed in vsphere. 3

4 1.1 vsphere API Explorer Getting Started with vsphere s API Explorer Every time I talk to users, there s always one consistent theme: learning to use vsphere s APIs is difficult. With the new release of vsphere 6.5, we ve taken aim at improving that experience with the API Explorer. The API Explorer allows users to connect to the API endpoint and then browse and interact with available REST based APIs and their calls. This includes available parameters, expected responses, what response status codes may mean, and much more. If you ve happened to use the Managed Object Browser, or MOB, think of that but on steroids! Accessing the API Explorer Accessing the API Explorer is incredibly easy. It s available on any API endpoint whether that be a vcenter server (appliance or Windows based) or external PSC appliance. Browse to: vcenter.fqdn/apiexplorer First Look After having loaded the API Explorer s interface, it s time to start looking around and seeing what s available. There are two items that should jump out immediately, the login option and the Select API dropdown. If you want to really interact with the API itself, you should log in. The login prompt accepts SSO based credentials, similar to what would be used to log into the vsphere client itself. 4

5 The Select API dropdown box allows the selection of available API. The APIs available on the endpoint are dependent upon the role the endpoint has. Example: an External PSC appliance won t have the same APIs and calls available to it as does the vcenter Server appliance. Common APIs: Appliance handles calls to the underlying VMware appliance CIS Common Infrastructure Services, handles calls involving tagging Content handles calls involves the Content Library vapi vsphere API, handles calls regarding the API endpoint vcenter handles calls to involving the vcenter Browsing the API Explorer Let s take a look around the API Explorer now that we have our bearings. With the vcenter API selected, expand the GET /vcenter/cluster operation. 5

6 On the above screen, we can see the path to make the call and the method. However, the API Explorer also gives some other information such as the expected response class, parameters and potential response messages. Clicking on those items expands and collapses additional information. Here s some examples: Response Class: 6

7 Cluster Filter Parameters: Response Messages: 7

8 My favorite part is right below those areas, the Try It Out! button. Clicking on that button performs the operation directly within the browser. It then provides a bunch of information such as an example curl statement, the request s URL, as well as the request s body, status code, and headers. 8

9 Conclusion The API Explorer is a great way to orient to and discover vsphere s REST based APIs. Not only does it provide lots of information and additional context around the API calls, it even helps users start making those calls. 1.2 vsphere Automation APIs - Introduction 9

10 Introducing the vsphere Automation APIs VMworld Europe 2016 introduced a lot of new and exciting products and features. One of the more exciting things that have been announced have been around the automation and development space. As seen from the keynote in Barcelona (see about 35 minutes in), VMware is taking the developer and automation specialists seriously. In the new vsphere 6.5 release we are providing simplified and modern API interfaces and giving customers their choice of access with language bindings and automation tools to a fresh new modern set of APIs. What s New VMware vcenter has received some new extensions to its REST based API. In vsphere 6.0, this API set provides the ability to manage the Content Library and Tagging but now also includes the ability to manage and configure the vcenter Server Appliance (VCSA) based functionality and basic VM management. VCSA API The VCSA s new and simplified REST based API will consistently be able to manage things like how to access the appliance, managing user accounts, checking on the health of the appliance or even the services of the appliance itself, networking configurations like firewall rules or proxy settings, being able to provide a file based backup or restore of appliance and even managing system settings like NTP or just checking the uptime or version. Virtual Machine API Additional functionality has been added for handling the management of VMs, using the range of interfaces (including REST) you will be able to read information, create, update and even delete VMs, as well as setting their power state and working with the hardware. Some example hardware tasks would be connecting the CD-ROM, updating the RAM allotment, adding a network adapter, removing a hard disk, and so forth. 10

11 All of this not just available via the developer and automation tooling but also simplified to make sure they are easily discoverable and the use of strong defaults means you only specify the information that is needed, a simple example of this means that to create a VM is now as easy as 12 lines of JSON and a single API call. Discover the APIs with the new API Explorer What s the best way to learn about these awesome new APIs? How about checking out the API Explorer that lives on the vcenter. It s available on the vcenter server at the following URL: *vcenter URL*/apiexplorer Once connected, the API Explorer will display information about the numerous endpoints available in order to easily understand the API models. The API Explorer also allows users to expand each API call and check out the required fields, understand the request body, see the available filter information, as well as a list of response messages. One of my favorite capabilities, the ability to click a button and trying out the calls live! 11

12 Process Improvements Due to how the above APIs are defined, we also have the ability to greatly improve our turnaround time on providing resources! This process allows us to provide a number of developer and automation based tool integrations out of the box. The SDK with new improved, simplified samples will include Java,.NET, Python, Ruby, and Perl. This also allows our automation tools to be provided on day 0 as well. The associated PowerCLI cmdlets, Datacenter CLI commands (new in 6.5), vrealize Orchestrator workflows, and so forth are all 12

13 part of the process. Lastly, and probably the best part, the documentation is created as well. The documentation will be fully featured and much easier to understand! Summary vsphere 6.5 brings all the features and improvements from above and many more. One thing is certain though, the future is bright when it comes to VMware s developer and automation interfaces. This blog post shows a summary of a lot of new features that each deserve their own blog posts, watch this blog over the next couple of months as there will be several more blog posts diving further into each of these areas! Originally Posted: VMware Developer Blog - What's New with Developer and Automation Interfaces for vsphere

14 2. vsphere Automation SDKs This section describes the vsphere Automation Software Development Kits (SDKs) that can work with the vsphere Automation APIs. 14

15 2.1 vsphere Automation SDK for REST - Getting Started Part 1 Getting Started with the vsphere Automation SDK for REST vsphere 6.5 introduced a big update to its newest API service, which is known as the vsphere Automation API. This API is a big step forward in the process of simplifying and modernizing our APIs. This service also allows us to introduce several new SDKs for the following programming languages: Java, Python,.NET, Perl, Ruby, and REST. This blog will take a look at the REST SDK and how to easily get started using it. For more information about what was introduced with the vsphere Automation APIs, check out the associated What s New blog post. Accessing the SDK First things first, we need to gain access to the vsphere Automation SDK for REST from VMware s GitHub repository. Make sure to read through the README, noting that we ll be able to view and use these resources, as well as contribute back to the following items: vsphere Automation SDK for REST API Reference Documentation Postman Samples Javascript Samples (See Part Two) The easiest method is now to either download or clone the repository. Downloading can be done as follows: 1. Click on the green Clone or Download button and then click Download ZIP 2. Once downloaded, extract the zip file to the location of your choosing 3. At this point, you will now have a local copy of the repository Cloning can be done as follows by CLI: 1. Click on the green Clone or Download button and then copy the clone URL 2. Within Terminal, change to the appropriate directory, and enter the following command: git clone [Copied URL] 3. Once the tasks complete, you will now have a local copy of the repository Cloning can also be done through the GitHub Desktop client as follows: 1. Click on the green Clone or Download button and then click Open in Desktop 2. Within the newly opened Clone As window, select the appropriate directory and name, then select Clone 15

16 Documentation The documentation for this SDK has improved so much it deserves its own section. The documentation is just clean and straight forward. Looking at it from a high level, you can browse each API and see the sections of what the underlying operations cover. Each of the operations list the method, URL, and a brief description of what it s used for. To receive some more in-depth information, click on the operation s method. Here you ll see all the information needed in order to perform the request including the request parameters, response codes, JSON and XML response representations, followed by a table of what those response types mean, and it also covers the error codes. 16

17 Install Postman One of the most convenient ways to get started using this SDK is with the Postman application. If you ve never heard of Postman, it is a simple and free REST API client. It can be installed on Windows, OSX, and Linux (although this is currently a beta install). While there is a Chrome app, we have found the best experience is with the full client application. Postman can be downloaded at the following link: Initial Setup At this point we have the SDK downloaded and the recommended client installed, so let s get Postman setup with everything needed to work with the SDK. First, start by importing the collections which were downloaded as part of the SDK. This can be done by clicking the Import button. On the new screen, with Import File selected, click the orange Choose Files button, browse to the location where you unzipped the SDK and then navigate to: client \samples\postman. Select the two JSON files in the directory titled: vsphere-automation-rest-api-resources.postman.json vsphere-automation-rest-api-samples.postman.json 17

18 We ll now notice two new collections which are named quite similarly to the files imported. The vsphere Automation REST Resources collection is a number of requests, grouped in folders by their object level, that can be performed against a vsphere environment. The vsphere Automation REST Samples is a couple groups of requests which can be combined to perform a normal task. Some of the examples include ESXi host connection and disconnection, VM creation, and VM power actions. Last part of setup comes down to configuring some environmental variables. As you begin browsing through the requests, you ll start noticing some double curly brackets that may look like this: {{vc}} This is what s known as an environmental variable within Postman, and vc will be used to refer to the vcenter Server. There s only a couple environmental variables which need to be set in order to begin: vc, user, password. Those are fairly self-explanatory, so let s set them up in Postman. To begin creating environmental variables, head towards the gear icon in the top right hand side and click on it. This is where environments are managed. Add a new environment by clicking on the orange Add button. Give the environment a name, then enter in those three items mentioned above and 18

19 valid values for your environment. Click the orange Add button again to complete the creation, and click on the X to the right of Manage Environments to close the window. Getting Authenticated As with all vsphere environments, the first step is to authenticate. Expand the vsphere Automation REST Resources collection, expand the Authentication folder, and select Login. We can gather a bit of information about the request at this point. We ll be doing a Post method to the vcenter s URL of "/rest/com/cmware/cis/session" with a basic authentication type and sourcing the username and password from our environmental variables. Before making the request, make sure to select the environment that was just created by selecting it via dropdown box next to the gear icon on the top right hand side. 19

20 NOTE: If you have any issues, you may need to turn off SSL certificate verification in the Settings (File > Settings > General tab > SSL certificate verification, turn off, restart Postman) Environment Discovery We re now authenticated to the vcenter s API endpoint, so we can start exploring some other areas within the vsphere Automation REST Resources section. Let s do some environmental discovery while we re still exploring the SDK. To get a list of the hosts available by this vcenter s API endpoint, expand the Hosts folder and select List. Here we can see the request uses a Get method to the vcenter s URL of "/rest/vcenter/host". Clicking Send will give us a list of the hosts available as well as some basic information such as the host ID, name, connection state, and power state. 20

21 To get a list of the datastores available by this vcenter s API endpoint, expand the Datastores folder and select List. This request is very similar to the last request, except it points to the vcenter s URL of "/rest/vcenter/datastore". Clicking Send will give us a list of the datastores available as well as their datastore ID, name, type, free space and capacity. To get a list of the VMs available by this vcenter s API endpoint, expand the VM folder and select List. At this point, hopefully you can figure out what the request is going to look like and a rough guess at what information is going to be pulled back. 21

22 We ve got the basics down now, how about getting into some additional detail on a VM. In the VM folder, select the Details. In the URL, we re just appending the VM s ID to the end of the prior call. The example includes vm-22 which can be modified to a VM ID as identified in the prior request. Clicking on Send retrieves a ton of information back about the configuration settings for that VM including CPU information, NICs, boot configuration, and so forth. VM Creation Last example, creating a VM. We ve just seen all of the configuration settings for a VM, however we don t need to have all of those to create a VM with this SDK. The API endpoint has the capability of setting those options automatically per best practices and VMware s guidance. These decisions are all based on the guest OS type. We ll start by selecting the Create with defaults option. Notice the familiar URL, however we re performing a Post method on it this time. Switching over to the Body section, we can see some items have already been filled in for us like Guest OS type, datastore, folder, and resource pool. These are the basics in order to perform this request. Once those options have been filled in with valid values for your environment, click the blue Send button to create the VM. 22

23 You should see a response that resembles a VM ID. Run the VM Details request again, only this time substituting the new VM s ID in the request URL. Scrolling through the response s body, take note of many of the areas which were populated automatically. Things like memory, disk size, SCSI controller, even the name were all populated automatically. 23

24 If you ve done this through the API before, this is a tremendous improvement! If there are additional things you d like to specify, that s possible as well. If you want to populate the settings for all of those items, that too is possible. It is all about the user s choice. Wrapping Up We just scratched the surface on what s possible with this SDK and Postman. There s many more areas to check out and explore. There s also the samples collection to take a look at too. Be on the lookout for part two, where we take a look through the javascript portion of this SDK! Originally Posted: VMware Code Blog - Getting Started with the vsphere Automation SDK for REST 2.2 vsphere Automation SDK for REST - Getting Started Part 2 Getting Started with the vsphere Automation SDK for REST Part 2 We re continuing the Getting Started series focusing on the vsphere Automation SDK for REST! In this part of the series, we ll be switching gears and looking at the JavaScript (JS) examples which were included in the SDK download. JS samples were included in the REST SDK to provide an easy example of how to call the vsphere REST API using a common and easy web based language. 24

25 Preparing The Environment If you haven t already done any JS work in your current environment, there are a couple preparation steps that are required to get started. While there are many ways to get started with JS, my personal preference is outlined below. Download NodeJS for your preferred OS and install it, ensuring the NPM Package Manager is also installed: The reasons I m using NodeJS and the associated NPM is because NodeJS will allow us to execute JS directly from the command line. NPM (Node Package Manager) will be used to install any of the package dependencies we ll be needing, as documented in the project.json file. Lastly, download and install Visual Studio Code which will be used as the IDE (or Integrated Development Environment): 25

26 However, please note, an IDE is not required to run these samples. First Steps We have our environment setup, the vsphere Automation SDK for REST is already downloaded (from Part 1), and we re ready to move on. Let s begin by examining the contents of the JS folder within the unzipped SDK directory: VMware-vSphere-Automation-SDK-REST-6.5.0\client\samples\javascript \vcenter We ll start by going through the README. There s a couple important parts in there with regards to getting started, plus it s always good to get a better understanding of what s going on with some of these samples. The beginning portion of the README illustrates a need to download and install some Node modules. These modules are dependencies of the samples and are sourced from the packages.json file in the vcenter directory. We can do this with the following commands at a prompt: cd VMware-vSphere-Automation-SDK-REST-6.5.0\client\samples\javascript\vcenter npm install 26

27 The bottom portion of the README provides a list of all the samples that have been included. Which are as follows: vm-details vm-create-defaults vm-create-details vm-power-on vm-power-off host-add host-remove host-connect host-disconnect The last of the first steps is to fill in some of the parameters included as part of the settings.js file. These parameters include some information like which REST endpoint we re connecting to and which what credentials we re using to authenticate with. If you recall the Environmental Variables we configured in Part One of this blog series, these parameters work very similarly to those. One item to keep in mind while filling in these parameters is related to the Host information, the endpoint will 27

28 need to have to prepend to the value. See the example below for a bit more information: VM Samples There are several VM examples that are included with this SDK. The easiest and most straight forward of the examples is retrieving details of the VMs associated with the API endpoint by using the vmdetails sample. It s executed by running: npm run vm-details 28

29 Another sample is about how to create a VM using defaults. This sample requires the host1 and datastore parameters to be completed within the settings.js file. 29

30 If you remember from part 1 of this series, the default settings are made based upon the Guest OS type. This sample creates a VM based on it being a RHEL_7_64 Guest OS type, which can be seen on line 86 of the create_vm_with_defaults.js script. Another parameter which is set as part of the script is which folder the VM is created in. Referencing line 72 of the same script, we can see it searching for the Discovered Virtual Machine folder. The sample can then be run with the following command: npm run vm-create-defaults We can see the VM was created with a hardware ID of vm-96. Let s go back to our first sample and verify that the VM was indeed created. If we want to perform some actions to that newly created VM, there are a couple samples we can use. However, before we do that, we will need to update the settings.js file to indicate the name of the VM we re targeting. 30

31 The two samples we have access to which can modify the VM are power actions, so powering on or off the system. We can perform the power on action with the following command: npm run vm-power-on 31

32 We can see in the above example that the proper VM is found, as referenced by the hardware ID of vm-96. We can then see the status code of 200 meaning the request was successfully received. Powering off the VM is just as easy as powering it on, and can performed with the following command: npm run vm-power-off Host Samples We re going to switch gears a bit and take a look at some of the host based samples. Since this is an existing environment, I ll be showing how to disconnect and reconnect a host. Before running the commands, we ll need to update our settings.js file again to reference the host we re working with. The host will be designated via the host1 parameter. 32

33 If you happen to be adding a host, the hostusername and hostpassword parameters should be completed as well. They are not needed for the examples below. In order to disconnect a host, we ll run the following command: npm run host-disconnect If we want to reconnect that host, we run the following command: npm run host-connect 33

34 Wrap-Up When you start creating additional JS scripts, some of the work has already been done for you. Check out the resources directory, it will have multiple individual top level object based scripts that have some of the functions already created. If the function isn t already created, the vsphere Automation API is really easy to work with so you can easily add your own to the SDK s samples. Originally Posted: VMware Code Blog - Getting Started with the vsphere Automation SDK for REST Part vsphere Automation SDK for Python - Getting Started Getting Started with the vsphere Automation SDK for Python We ve been looking at how to get started using the new vsphere Automation SDKs. This time, we ll be looking at the vsphere Automation SDK for Python! Prerequisites There are a handful of ways to install and setup Python on your workstation, I will be walking through a high level configuration for my Mac. First things first, clone the vsphere Automation SDK for Python from the VMware GitHub repository located here. After that s complete, we ll need to install the Python prerequisites. These include the GNU Complier Collection (GCC), a C compiler, and HomeBrew, a package management system. GCC can be installed in multiple ways, but I ve found it s easiest to obtain it by installing the Xcode Command Line Tools. This can be done with the following command, then following the prompts: xcode-select --install 34

35 Next, we ll need to install the package manager, Homebrew. It can be easily downloaded and installed with the following command: /usr/bin/ruby -e "$(curl -fssl raw.githubusercontent.com/homebrew/install/master/install)" Finally, we ll install Python in the recommended version of 3.6. It s worth noting here that Mac OS X comes with a version of Python already installed. However, it is generally an older version (normally, Python 2.7) and is used for some system related tasks. Due to that, it is best not to modify that version or the defaults. Utilizing our package manager, we ll install Python 3.6 with the following command: brew install python3 35

36 It s also recommended to isolate your development environments from each other so, we ll setup a virtual environment and jump into it. We can do that with the following commands: python3 -m venv SDKDemo source SDKDemo/bin/activate Lastly, we ll install the SDK requirements. They re listed within the root of the SDK folder in the file labeled: requirements.txt. After checking out which requirements are necessary, we ll install those requirements by way of the following command: pip3 install -r requirements.txt 36

37 One other item worth mentioning is an IDE. This will make editing, running and debugging the code a lot easier to deal with. I ll be using PyCharm, which is available here. Running Sample Setup Script To really show off the capabilities of the SDK, there s a sample script which takes an un-configured vsphere environment and performs all of those normal configuration steps. The environment requirements to run the script are as follows: 1 vcenter Server 2 ESXi Hosts 1 NFS Datastore (minimum of 3GB free) We ll first need to open up the testbed.py file and populate lines 17 through 29 as follows: We re now ready to set the environment up with the sample script! However, before running the script we should take a look at what it s doing. The script is available in the SDK directory at: /bin/ run_sample.sh The goal of the script is to do the following actions: Create 2 Datacenters Create a Cluster Create Test Folders for VM Storage Attach the Hosts Create a Distributed Switch Create a Distributed PortGroup Attach the NFS Datastore (if Selected) to the hosts Copy the Photon OS ISO image downloaded from VMware s bintray server to the Datastore Create directories to add sample ports One note before running the script, the ISO image being downloaded is roughly 200MB and could take a while depending on your bandwidth. My tests ranged anywhere between 30 seconds and 5 minutes. 37

38 The sample script can be run with the following command:./run_sample.sh../samples/vsphere/vcenter/setup/main.py sv Create a VM with Defaults Now that our environment is setup, let s take a look at adding a VM to this environment. The easiest way is to create a default VM. This action means the API takes care of all the configuration settings based on the Guest OS version. There are some prerequisites that are required for placement such as desired datacenter, VM folder, and datastore. These are all referenced from the testbed.py configuration file we referenced in the first example. The VM can then be created with the following command:./run_sample.sh../samples/vsphere/vcenter/vm/create/create_default_vm.py v 38

39 Notice in the above example how even though we didn t populate all of the settings, the VM received required items like a CPU, a disk, and so forth. To verify the VM does indeed exist, we can obtain a list of VMs with the following command:./run_sample.sh../samples/vsphere/vcenter/vm/list_vms.py v 39

40 VM Power Actions The next logical step after creating a VM is to power it on. There s a sample within the vm folder named power.py, which shows off all of the power actions. This file references the VM_NAME_DEFAULT input from the testbed.py file. When running the command as is, the VM will be put through the following power states: Obtain current power state Power Off (NOTE: Only if the VM is currently powered on) Power On Suspend the VM Resume the VM Reset the VM The command can be run with the following:./run_sample.sh../samples/vsphere/vcenter/vm/power.py v 40

41 Summary This post shows you how to easily get started with the vsphere Automation SDK for Python. It takes you through the setup of an entire environment, as well as using the individual samples. You can then take whichever is most relevant to you and apply to your environment or, pull parts of this code out and use it to automate or integrate as needed. With our SDK now being open sourced, we are intent on making sure these samples are of a high quality. If you notice areas of improvement, or come up with some new samples, please feel free to raise issues or pull requests on our GitHub repository. Originally Posted: VMware Code Blog - Getting Started with the vsphere Automation SDK for Python 41