vCloud Web Services Overview

Last updated
Save as PDF

This feature is available in Ultimate edition only.

Overview

In Automate, Clouds are definitions of the details of a virtual environment. Different providers may use different terminology to describe this concept: in Amazon AWS, clouds are "Regions", and cannot be changed by users. In private clouds such as Eucalyptus, Clouds are the different Eucalyptus environments you may have set up.

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.