Skip to main content

​
About VMware vCenter

VMware vCenter Server manages vSphere estates: the ESXi hosts, clusters, and virtual machines that run them. This integration connects Serval to your vCenter appliance so workflows can identify a virtual machine, read what VMware Tools reports from inside its guest, enumerate inventory for audits, and answer scope questions from vSphere tags. The integration is read-only and is marked Beta in the connect screen, so its capabilities and prebuilt workflows may still change. Authentication: Username and password for a vCenter Single Sign-On account. Serval exchanges those credentials for a session, reuses it for up to five minutes, and can sign in again and retry a read request once if the session expires sooner. Workflows never handle the credentials or the session. Data sync: None - everything is on demand. Serval calls your vCenter only when a workflow or health check runs. There is no background sync, no webhooks, and no data ingestion.

​
What the VMware vCenter integration enables

These use the vSphere Automation REST API introduced in vSphere 7.0 - see VMware’s vSphere Automation API documentation for background on the underlying interfaces.
This integration is read-only, and enforces it: Serval refuses any request to your appliance that is not a read, so it cannot power machines on or off, create or delete them, take snapshots, or change tags.

​
Before you connect

Two things about your vCenter appliance decide whether a connection can work at all. Check both before creating the account.
Most vCenter appliances sit on an internal network that Serval’s cloud cannot reach. Three deployments are possible:
  • Appliance reachable from the internet: connect normally, nothing extra needed.
  • Self-hosted Serval deployment: works when your deployment is configured to allow internal targets.
  • Serval cloud with a self-hosted worker: Enable Run on self-hosted workers for the connection. With an up-to-date worker and proxy, both the session exchange and API requests run from your network. The worker must be able to reach the appliance and trust its TLS certificate.
Serval verifies the appliance’s certificate against its trust store, and there is no option to skip that check or supply a private CA. A vCenter still serving the self-signed certificate it ships with will fail to connect. Replacing it with a certificate signed by a CA your Serval deployment trusts is standard vSphere practice - see VMware’s guidance on replacing vCenter Server certificates.

​
Get your credentials

Serval needs your vCenter host and a vCenter Single Sign-On account. A read-only account is sufficient: this integration never writes.
1

Create a service account in vSphere

Sign in to the vSphere Client as an administrator and go to Administration then Single Sign On then Users and Groups. Create a user in the vsphere.local domain, for example svc-serval, and give it a strong password. Using a dedicated account rather than a person’s login keeps the connection working when staff change.
2

Give it a read-only role at the vCenter root

Go to Administration then Access Control then Global Permissions, add the new user, and assign the built-in Read-only role. Select Propagate to children so the permission covers every datacenter, cluster, host, and virtual machine.
3

Confirm the account can read tags

The tag workflows call vCenter’s tagging service, which is separate from the inventory API. The Read-only role covers it in a default configuration; if your vCenter restricts tagging separately, grant the account read access there too.
4

Note your vCenter host

Use the hostname or IP address you use to reach the vSphere Client, without the “https://” prefix and without the “/ui” path - for example “vcenter.example.com”.

​
Connect in Serval

1

Open the VMware vCenter integration

In Serval, go to the integrations page and select VMware vCenter (marked Beta).
2

Enter the vCenter Host

Enter the hostname or IP address of your appliance, for example “vcenter.example.com”. Add a port only if your appliance does not serve the API on 443. Serval always connects over HTTPS.
3

Enter the Username and Password

Enter the Single Sign-On account, for example “svc-serval@vsphere.local”, and its password. The password is stored encrypted and shown masked after saving.
4

Save, then run the health checks

Saving validates the format of what you entered but does not call your appliance, because the connect screen cannot reach an internal network even when workflows can. Run the health checks afterwards to confirm the credentials work.

​
Verifying the connection

Four health checks run on demand and are the way to confirm a working connection: If Test Connection passes but the others fail, the credentials are correct and the account is missing privileges.

​
Gotchas and troubleshooting

A virtual machine’s hostname and IP addresses are reported by VMware Tools from inside the guest. vCenter itself does not know them. On a machine where Tools is not installed, not running, or the machine is powered off, the Find Virtual Machine workflow returns those fields empty with a reason rather than failing - so a machine that appears to have no IP address usually has no running Tools, not no network.
Everything here comes from the vSphere layer, so the integration answers questions about a Windows or Linux server only insofar as that server is a virtual machine on this vCenter. A physical server, a machine on Hyper-V or Nutanix, and a cloud instance are all invisible. Within a virtual machine, the visible facts are its vSphere configuration plus what VMware Tools reports - hostname, IP addresses, detected OS, mounted filesystems. Patch level, installed software, Active Directory domain membership, logged-on users, and anything else requiring in-guest execution are not available: correlate on instance UUID with an endpoint agent or CMDB for those.
Every virtual machine records the guest operating system it was configured for at creation. That value is what the machine claims, not what is booted - a machine created as Windows Server 2019 and later rebuilt as Linux still reports the original. The detected guest OS comes from VMware Tools, alongside the hostname and IP addresses.
vCenter refuses any list request that would return more than 4,000 virtual machines, and its API has no way to page through results. Serval works around this by splitting the request across datacenters, and then across folders where a single datacenter is still too large. This is automatic, but it costs one call per partition, so inventory workflows are noticeably slower on very large estates. Narrowing to a datacenter or cluster makes them fast again.
vCenter’s name filter has no substring or wildcard form. The Find Virtual Machine workflow tries an exact match first and falls back to listing inventory and matching locally, which is why a partial name is slower. When a partial name matches more than one machine, the workflow reports the candidates and stops rather than guessing.
Two categories can each hold a tag named “Production”. List Virtual Machines By Tag reports the ambiguity and asks for a category rather than picking one, since the two usually mean different things.
The BIOS UUID is what an agent inside the guest reports as the machine UUID, and cloning can produce duplicates. The instance UUID is unique per virtual machine within a vCenter. When correlating with a CMDB or an endpoint agent, prefer instance UUID where both systems have it.
Serval exchanges the stored password for a session on demand. If the account’s password is rotated or the account is disabled in vSphere, requests fail when the existing session stops working or Serval next needs to sign in. Update the password in the integration settings to restore it.
The VMware vCenter connect tile is marked Beta, so the available actions and prebuilt workflows may still change.
Need help? Contact support@serval.com for assistance with your VMware vCenter integration.