When you install a Cloud Director Instance the Site ID name visible to Tenants shows as a unique alphanumeric ID in the GUI and API as default. Many people want to change this to something a bit more descriptive. This can be done easily but the process is not available in the GUI.

Below I show the steps to change the site ID via the Cloud Director API.

REST API Client

There are many ways to access the Cloud Director API. For this example I am using a Rest Client called Insomnia, however you can use Postman, a browser plugin or CURL. As you get more comfortable with the API you can start using variables and scripts to bring the following individual REST calls together. I am going through the full process here to understand each of the steps.

Checking the API Version

Each version of VCD has an API version. For VCD 10.2 the API is v35. It is a good idea to check the versions supported before beginning. You can check this by sending a simple command from your rest client to one of your VCD nodes in a server group.

GET https://sto-vcd01.terataki.local/api/versions

All being well you will get a 200 OK response and in the body you will find a line that says whether or not the API version(s) are deprecated.

<VersionInfo deprecated=”false”>
<Version>35.0</Version>

“False” means that the version listed is still active. Previous versions are provided for backwards compatiability but as my environment is new I am going to continue with the latest API version v35.

Set the Initial Authentication

In order to carry out commands with the VCD API we need to be Authenticated. For the majority of this we will use a bearer token so that we can send multiple calls using that same token. First we must generate and retrieve a token before we can use it. That means we need to use some credentials to authenticate first time.

Under the Authorization section in Insomnia select the Basic Auth type and provide a valid username (including @system) and password. I am using my VCD Provider Administrator account.

Having entered the auth information I now click in Header and using the confirmed API information I add some additional settings. These details are used when sending issuing further API calls:

Accept: application/*;version=35.0

Requesting Bearer Token

With the above in place we can now send the following call to retrieve a bearer token that will then be used in subsequent API calls. To get this we send:

POST. https://sto-vcd01.terataki.local/api/sessions

Again all being well the return should be 200 OK and in the response message we will see under the header a section titled X-VMWARE-VCLOUD-ACCESS-TOKEN. Copy that text to the clipboard. This token will be used for subsequent calls and is valid for 30 minutes.

Changing the Auth Type to Bearer Token

We can change the Basic Authentication set earlier to Bearer Token. To do so go back to the Auth section and select the Bearer Token type and paste in the token from the clipboard.

Retrieve the existing Site ID Information

With the above in place we are now ready to start looking up the current setting for the site ID. To do so we run the following GET call:

GET. https://sto-vcd01.terataki.local/api/site/associations/localAssociationData

In the response preview you will find a href URL for the Cloud Director Site that in my environment looked like the following:

href="https://10.0.100.25/api/site/associations/c3ccd380-db22-442c-864b-03e6b70ccd3a" type="application/vnd.vmware.admin.siteAssociation+xml"

We are interested in the alphanumberic part of the url; 3ccd380-db22-442c-864b-03e6b70ccd3a
We will use this to perform another GET Request to retrieve the configuration including the current Site name:

GET https://sto-vcd-01.tertaki.local/api/site/associations/3ccd380-db22-442c-864b-03e6b70ccd3a     

In the XML response you will see a entry with the current setting. In my environment this looked like:

<SiteName> Site name undefined (Site ID: 3ccd380-db22-442c-864b-03e6b70ccd3a)</SiteName>

but it could show in some circumstances as an IP address between the Sitename brackets.

Changing the Site ID Name

Now I can change the Site name to whatever I please by editing the XML response retrieved above. To do so I copy the response and paste into the body XML which will be sent in the next API call I will make.
I change 3ccd380-db22-442c-864b-03e6b70ccd3a (old value) to Stockholm (my desired value).

With the correct xml pasted in the body I can now change the setting by sending the following command:

PUT https://cloud.example.com/api/site/associations/e228c64d-b92e-4c9f-9bf8-f5e8b2680309

I get a 200 OK response again which shows there was no issue and I confirm this in the Provider UI events and tasks where I can see there is an Updated Site task with a Succeeded status.

Checking the result in the GUI

With our API work complete I can now go back to the UI and reload the Organisation or OrgVDC. The previously observed default Site name has been replaced with my new name when viewing Organizations or Organization VDCs.

Resources

The above process is published in VMware KB 79439

The official VCD API documention for Cloud Director 10.2 can be found at code.vmware.com

Simon Greaves has a post on the vCloud Director REST API (vCloud API) with more information and examples.

Tomas Fojta has a number of articles on his sight but the post Postman and vCloud Director 9.5 Access Token Authentication is useful.