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.

• 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.

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.

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.

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

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

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.

• 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.

• 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.

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