VMware Cloud Director

VMware Cloud Director servers

Since 3.1.0 · Contributed by Andrew Turbay (@turbay-a) in PR #167 · How it works underneath: Proxmox and Cloud Director — Developer Guide

FreeITSM reads the VMs from one or more VMware Cloud Director (vCloud Director) servers, with their network cards, addresses and disks, and the edge gateways with their uplink addresses. The VMs are listed under Asset Management → Servers, next to vCenter. It only reads: nothing is ever changed in Director.

You can add several servers. Each syncs on its own schedule, and its data is kept apart.

⚠️ Not yet tested against a real Director. The sync has been tested against a stand-in that answers the way Director's API is documented to. The first real run is worth watching: if something is missing, the sync's message says what, and an issue with that message helps a great deal.

---

What you need

• A Director user with read access to the organization whose VMs you want.
• The address of the Director portal, e.g. https://vcd.example.com.
• The FreeITSM server able to reach it.

1. The organization and the user

Case	Organization	User
One organization	its name, e.g. acme	a user with Organization Administrator, or a read-only role
Every organization (a provider)	System	a provider administrator

The organization is its name, not its display name: the one in the address when you sign in to it (…/tenant/acme means acme), or the Name column under Administration → Organizations.

2. A read-only role (optional, recommended)

An Organization Administrator can read everything, but can also change it. To let FreeITSM only read: Administration → Roles → New role in the organization, with the rights to view virtual machines, networks and edge gateways and none to create, change or delete. Then a user with that role. The exact rights differ between Director versions; if a sync reports a refused request, add the right it names.

3. The API version

Director	API version
10.5	38.0
10.3	36.2

If Test fails with an HTTP error about the request, try the other one.

4. Add the server in FreeITSM

Asset Management → Settings → VMware Cloud Director servers → Add server:

Field	Value
Name	anything, e.g. vcd-prod
Server address	https://<vcd-host>. https only: the password travels with the login
Organization	from step 1
User	from step 1, without @organization (FreeITSM adds it)
Password	stored encrypted, never shown again; leave it empty when editing to keep it
API version	from step 3
Sync every (minutes)	5 to 10080
Verify certificate	ticked unless the portal has a self-signed certificate
Active	ticked

Save, then Test, which names the organization and checks the VM list can be read. Then Sync now and Show VMs: each VM with its vApp, organization VDC, status, resources and addresses, and the edge gateways below.

Keeping it in step

• Sync hypervisors on the Servers page syncs vCenter, every active Proxmox server and every active Director server, with one result line each. Anyone who can use Asset Management can press it; adding, changing and testing servers needs the VMware Cloud Director servers settings permission.
• On a schedule, cron/vcloud_sync.php syncs every active server whose interval has passed:

*/5 * * * *  php /var/www/html/cron/vcloud_sync.php >> /var/log/freeitsm-vcloud.log 2>&1

In Docker: docker exec <app container> php /var/www/html/cron/vcloud_sync.php, from the host's cron. Command line only.

Each sync logs in, reads, and logs out again, so scheduled runs don't leave sessions open on Director.

When a VM disappears from the list

• A VM is removed only after every page of the VM list was read. If one page fails, nothing is removed that time, not even a VM missing from a page that did come back.
• FreeITSM counts the VMs that actually arrived, not the page size it asked for, so a Director whose administrator has lowered the maximum page size is still read to the end.
• The safety guard: fewer than half of the known VMs seen in one sync means nothing is removed.
• Edge gateways follow the same rule: removed only after all their pages were read.

A VM keeps its identity by UUID, so renaming it or moving it between vApps updates it rather than adding a second one.

Troubleshooting

What you see	Likely cause
"Use an https:// address"	The address starts http://.
"refused the login (HTTP 401)"	Wrong user or password, or the organization's display name instead of its name.
"refused the login (HTTP 403)"	The user is locked, or can't sign in to that organization.
"did not return a session"	The wrong address, or a proxy that drops Director's session header.
"Logged in, but the VM inventory could not be read"	The API version is wrong for this Director, or the user can't view VMs. Check the version first.
"Could not reach the vCloud Director server: …"	The address is wrong, or a firewall is in the way.
A VM has no IP address	Its network card is disconnected, or it has no address yet.
"only partly readable; nothing was removed"	A page of the VM list failed. The next sync tries again.
"SAFETY GUARD"	Nothing was deleted. Usually the user lost rights, or the organization changed.

---

Related: Proxmox VE · Proxmox and Cloud Director — Developer Guide · Assets