vCloud Web Services Overview
This feature is available in Ultimate edition only.
Overview
Automate Tasks have the ability to communicate with the vCloud API endpoint and can be used to manage vCloud services, including starting and stopping servers, configuring networks, creating vApps, etc. This document shows how to get connected to vCloud and run some simple API calls
Set Up the vCloud Service Endpoint
First define the Web Service Endpoint. In the administration console, navigate to Configuration -> Manage Clouds
. See here for more information on managing Cloud endpoints. Click the Create
button. On the dialog that appears, name the vCloud endpoint, select vCloud as the Provider. Select the proper API Protocol (HTTPS is the vCloud default) and enter the API Url.
The API Url will typically be in the form of vcloud.example.com
which is usually the same URL that would be used to login to vCloud Director without the /cloud
path on the end of the URL. Automate will automatically add the path /api
to the end of the URL at runtime.
Click the Save
button.
vCloud Credentials
To enable communication with the vCloud Web Service, create credentials in vCloud Director that can be used to access the Web Service. These can typically be the credential that are used to login to vCloud Director.
Once the vCloud credentials have been created, login to the administration console and navigate to Configuration -> Manage Cloud Accounts
. See this this page for general information on Cloud Accounts.
Click the Create
button and fill in the following fields: Account Name, Login ID, Password. Account Name is an arbitrary name for the set of credentials which will distinguish it from other credentials defined. Login ID and Password are the user id and password created in vCloud. The user id may take the form of username@organization
.
On the Cloud Account page, select "vCloud" in the provider list. Select the vCloud previously created as the default cloud and click Save
.
All passwords are encrypted inside the repository.
Finalize vCloud Endpoint
Return to the edit page of the vCloud Endpoint by navigating to Configuration -> Manage Clouds
and clicking on the vCloud endpoint row.
Select the newly created Cloud Account named in the previous step in the Default Account drop down and click the Save
button.
Next to the Default Account list is a button used to test the connection. Testing vCloud connections is not yet supported in the administrator console.
Network Connectivity
The Task Engine server(s) will need inbound TCP access to the vCloud Web Services endpoint server at port 443 (default).
Connectivity can be tested by using the following command at the command line on the Task Engine server, substituting the address of the vSphere Web Services endpoint. This tests only un-authenticated network connectivity.
curl -Lk https://vcloud.example.com/api
This should result the the following message returned from the vCloud API endpoint which is what we want to see.
No valid API version can be selected
Testing the Credentials
To test Task connectivity to the vSphere Web Service endpoint as well as the credentials, create a Task and name it test vcloud connection
.
On the Commands tab, select the vCloud
category and drag the vCLoud API Call and Parse
command over to the right. Enter org
in the Url or Method field. Make sure the Method or Href drop down has method
selected and the Action is GET
.
In the XPath box, put Org
. Under Values to Extract, enter href
in the Attribute or Element Name field and org_href
in the Variable field.
Add another step to the task from the command list Interact, Log Message
. Drag Log Message below the vCloud command. Enter the following text into the Log box.
The organization href is -> [$org_href$]
Your task should look like the following:
In the top menu, select Configuration
. There's a option there for the "Session Cloud Account". Change this to the newly created named credentials if they are not already selected.
The "Session Cloud Account" is the account used when running Tasks from within the Automate UI. It has no bearing on Tasks executed externally, via Flow, Deploy, or the command line tools. In those cases, the Account is explicitly provided as an argument, or the Account selected as "default" will be used.
Click on the Run
tab and click the Run
button. On the next screen, click Run Now
. The Task instance log page will appear. If the command is successful, you should see a the xml returned from the vCloud endpoint and the log message with the vCloud Organization href link.