Script Identification for Embedded vCLS has Changed Identifiers Including ManagedByInfo

Products

VMware vCenter Server 8.0 VMware vSphere ESXi 8.0

Issue/Introduction

The recommended way to treat vCLS VMs in most cases is to ignore them. This usually involves having logic to detect these VMs for exclusion from certain operations. Due to differences in implementation and behavior between External and Embedded vCLS VMs (introduced in 8.0 U3), some identifying traits need to be set to different values, which may cause false-negatives for detection logic.

Identification code will need to be updated to align to the new conventions. This article seeks to outline the general detection of vCLS VMs and the differentiation between External and Embedded types as of vSphere 8.0 Update 3.

Environment

vCenter Server 8.0 U3

ESXi 8.0 U3

Cause

The following list explains VM traits that may be in use as identifiers for vCLS VMs and why they differ between versions.

Extra Config: Both External and Embedded vCLS VMs have a value in vm.config.extraConfig which is not present for workload VMs: "HDCS.agent", which is set to the string "true". Embedded vCLS keeps this same value, and adds an additional field, "vCLSCRX.agent", also set to "true". Scripts can use the presence of "HDCS.agent" to determine if a VM is vCLS in general, and the presence of "vCLSCRX.agent" to determine whether it is Embedded or External. This is the recommended way to identify vCLS VMs, as it is the most reliably available method.
ManagedByInfo: Both External and Embedded vCLS VMs have their vm.config.managedBy populated with a valid ManagedByInfo, but its values have been changed to reflect changes in the underlying deployment mechanism. Instead of extensionKey being set to "com.vmware.vim.eam" and type being set to "cluster-agent", the value for extensionKey is "VirtualCenter" and the value for type is "vcls-entity". Scripts that detect vCLS VMs based on the "com.vmware.vim.eam" value according to https://kb.vmware.com/s/article/80472 will need to either include the "VirtualCenter" value in the search or switch to using vm.config.extraConfig to detect vCLS VMs.
Config Path: External vCLS VMs followed the usual expectation of being datastore-relative since they were deployed as typical VMs. In contract, an Embedded vCLS VM is a container with no datastore, so its VMX path and similar configured paths are pointed at a local ramdisk directory on its host. These paths are not accessible via a datastore browser. This value is not recommended to use for detecting Embedded vCLS VMs, as there may be other system VMs using this style of path in the future.
Guest OS: External vCLS VMs used a generic Linux guest. Embedded vCLS VMs use the container runtime "crxSys1Guest" which will show up as "VMware Photon CRX" in the vSphere UI.
VM Name: The VM name prefix has not been changed between External and Embedded vCLS. Both will start with "vCLS-". This is not recommended to use for detecting Embedded vCLS VMs, as anyone can rename a VM to match this pattern. But if this is already used to detect vCLS VMs, it will continue detecting both External and Embedded vCLS.
Virtual Property: Both External and Embedded vCLS VMs have queries on their Virtual Property "isClusterVM" return true. Note that unlike vm.config.extraConfig which uses the string "true", this property returns an actual boolean.

Resolution

Reference the following chart when determining how to identify Embedded vCLS VM's:

Identifying Trait	Value for a Typical VM	Value for External vCLS	Value for Embedded vCLS
Entries in `vm.config.extraConfig`	No entry for `"HDCS.agent"`No entry for `"vCLSCRX.agent"`	`"HDCS.agent"` = `"true"`No entry for `"vCLSCRX.agent"`	`"HDCS.agent"` = `"true""vCLSCRX.agent"` = `"true"`
Value of `vm.config.managedBy`	Various Values or Null	`extensionKey` = `"com.vmware.vim.eam"` `type` = `"cluster-agent"`	`extensionKey` = `"VirtualCenter"` `type` = `"vcls-entity"`
Value of `vm.config.files.vmPathName`	`[DATASTORE] DIR/FILE.vmx`	`[DATASTORE] DIR/FILE.vmx`	`[] /var/run/crx/infra/DIR/FILE.vmx`
VM Guest OS	Various Values	`guestId` = `"other3xLinux64Guest"` `guestFullName` = `"Other 3.x or later Linux (64-bit)"`	`guestId` = `"crxSys1Guest"` `guestFullName` = `"VMware Photon CRX"`
VM Name Prefix	Various Values	`"vCLS-"`	`"vCLS-"`
Virtual Property `isClusterVM`	`false`	`true`	`true`

The following PyVmomi examples contain functions that take a VirtualMachine object and return whether it is a certain type of vCLS VM. These checks can be used for exclusion, special-casing, and other cases where detection is needed.

Using Extra Config (More Reliable and Future-Proof)

# Key Constants.

kHdcsExtraConfigKey = "HDCS.agent"

kVclsCrxExtraConfigKey = "vCLSCRX.agent"

# ExtraConfig key check helper.

def hasConfigKey(vm, cfgKey):

if not vm.config:

return False

return any(cfg.key == cfgKey and cfg.value.lower() == "true"

for cfg in vm.config.extraConfig)

# Embedded vCLS. VM has both keys set. Checking vCLSCRX is sufficient.

def isEmbeddedVclsVm(vm):

return hasConfigKey(vm, kVclsCrxExtraConfigKey)

# External vCLS. VM has the HDCS key set but not the vCLSCRX key.

def isExternalVclsVm(vm):

return hasConfigKey(vm, kHdcsExtraConfigKey) and not isEmbeddedVclsVm(vm)

# Either type. Both types have the HDCS key set.

def isAnyVclsVm(vm):

return hasConfigKey(vm, kHdcsExtraConfigKey)

Using ManagedByInfo (Simpler)

# Embedded vCLS.

def isEmbeddedVclsVm(vm):

if not vm.config or not vm.config.managedBy:

return False

return vm.config.managedBy.extensionKey == "VirtualCenter" and\

vm.config.managedBy.type == "vcls-entity"

# External vCLS.

def isExternalVclsVm(vm):

if not vm.config or not vm.config.managedBy:

return False

return vm.config.managedBy.extensionKey == "com.vmware.vim.eam" and\

vm.config.managedBy.type == "cluster-agent"

# Either type.

def isAnyVclsVm(vm):

return isEmbeddedVclsVm(vm) or isExternalVclsVm(vm)