Compatibility overview

Kyvernon serves the vSphere SOAP API (vim25), the REST automation API, datastore file access and the OVF transfer endpoint next to its native API. The controller serves them on the same listener and certificate as the native API, so a tool connects to the address of the controller (port 8443 in the examples). The endpoints are off until [facades] enabled = true is set in controller.toml; see Settings of the compatibility endpoints.

Endpoints

Sessions and accounts

A client signs in with the user name and the password of a Kyvernon account. The permissions of the account decide what the client sees and may do: privileges use the vSphere identifiers and apply to the same objects as in the console. An object the account may not read is not reported, and the PropertyCollector does not traverse through it. Writes check the privilege of the operation on its target and answer a NoPermission fault when it is missing.

The facade sign-in follows the sign-in policy of the controller: lockout and the audit records apply. There is no interactive prompt for two-step verification on the vim25 sign-in. An account that must change its password is refused until it has. A session ends after 30 minutes without requests (session_timeout), and when the account or its sessions are revoked through any API.

Object references and tasks

References to managed objects use the ids of the native API in the vSphere forms, such as vm-42, host-7, datastore-3, network-5, domain-c1 and resgroup-1. Operations whose name ends in _Task return a task reference that tools wait on with the PropertyCollector. They are the same tasks as in the console and the native API. Property paths such as config.hardware.device resolve on the managed objects that the endpoints serve.

Methods that are not served

The vim25 API has 972 methods. Kyvernon serves 196 of them: the methods that the verified tools use, grouped by managed object in the reference supported vSphere API methods. A method that is part of the API and not served returns a NotSupported fault, so a tool that calls it fails visibly. A name outside the API returns MethodNotFound. Examples of methods that are not served are ShutdownGuest, RebootGuest, the methods of LicenseManager and CreateDVS_Task. Use the native API, for example kyvernon vm shutdown <id>, for these functions.

Product identification

The service information (about) names Kyvernon as the product. Some tools check the product name before they enable a function; the setting product_name in [facades] changes the name that the endpoints report. See Settings of the compatibility endpoints for which tool needs it.

Cloud images

Linux cloud images that include cloud-init are personalised with the extraConfig keys that the VMware datasource of cloud-init reads: guestinfo.userdata, guestinfo.metadata and guestinfo.vendordata, each with an optional .encoding of base64 or gzip+base64. Kyvernon passes the data to the guest as a read-only NoCloud disk. The keys that the Terraform argument extra_config, govc vm.change -e or the PowerCLI advanced settings set work without changes. Invalid data fails the task that sets it, with the key named.

Related tasks

• PowerCLI, govc, Terraform, Ansible
• Settings of the compatibility endpoints
• Terminology for vSphere users