Specify vSphere folders in cluster configuration

This document shows how to specify vSphere objects in cluster configuration files when the vCenter configuration contains parent folders. It also documents the naming rules applied by preflight validations starting with 1.13.0.

Assuming the following example vCenter configuration indicating the path from vCenter root to the specific object

Hosts and Clusters

VMs and Templates

Storage

Network

 
my-vcenter
  my-datacenter-folder
    my-datacenter
      my-cluster-folder
        my-cluster
          my-resourcepool
        
my-vcenter
  my-datacenter-folder
    my-datacenter
      my-vm-folder
        
my-vcenter
  my-datacenter-folder
    my-datacenter
      my-storage-folder
        my-datastore
        
my-vcenter
  my-datacenter-folder
    my-datacenter
      my-network-folder
        my-portgroup

To create an Anthos cluster in my-resource-pool and my-vm-folder using my-datastore and my-portgroup, specify the following admin cluster configuration:

    vCenter:
      address: "my-vcenter"
      datacenter: "my-datacenter-folder/my-datacenter"
      cluster: "my-cluster-folder/my-cluster"
      resourcePool: "my-resourcepool"
      datastore: "my-datastore"
      folder: "my-vm-folder"
    network:
      vCenter:
        networkName: "my-network-folder/my-portgroup"

To create an Anthos admin cluster in the default ResourcePool using my-datastore and my-portgroup, specify the following cluster configuration:

    vCenter:
      address: "my-vcenter"
      datacenter: "my-datacenter-folder/my-datacenter"
      cluster: "my-cluster-folder/my-cluster"
      resourcePool: "my-cluster-folder/my-cluster/Resources"
      datastore: "my-datastore"
      folder: "my-vm-folder"
    network:
      vCenter:
        networkName: "my-network-folder/my-portgroup"

This also applies to user cluster and admin workstation configuration since vCenter section is common across these configuration files.

Naming Rules

Do not specify the parent folder while specifying a datastore as the datastore name must be unique within a datacenter. If a folder is specified, the following error is returned:

  Datastore name 'storage-folder/my-datastore' should not contain parent folders

For all other vSphere object types the parent folder should be specified when vCenter configuration contains parent folders. If the required parent folders are not specified in the cluster configuration but present in the vCenter configuration, the following error is returned: 

 Parent folder is not specified for cluster, you must specify the full path 'clusters/my-cluster' in the cluster field
Starting with Anthos Clusters on VMware 1.13.0, vSphere object names are validated according to the above rules for the following operations:

  • gkectl create
  • gkectl check-config

There is still a chance that a vSphere object resolution is ambiguous under following example situations

  • A cluster is upgraded from a previous version which violates the naming rules and vCenter configuration contains a conflicting folder/object, and
  • Objects with conflicting names were not present during cluster creation but added later

For example, consider the given vCenter configuration

 
my-vcenter
  my-datacenter-folder
    my-datacenter
      my-cluster-folder
        my-cluster
          my-resourcepool

Next, if the following hierarchy is added later

my-vcenter
  my-datacenter-folder
    my-datacenter
      my-cluster
        my-resourcepool

the resolution of 'my-resourcepool' is ambiguous if the configuration files did not specify the my-cluster-folder during cluster creation

You may encounter the following error: path 'my-resourcepool' resolves to multiple resource pools

More generally, the vSphere library returns the following error message when the object resolution is ambiguous: 

 path xxx resolves to multiple objects

To fix the error, ensure that the path does not contain conflicting object names (such as one within a folder and one without). Remove or rename the object which does not belong to the cluster and causes the conflict. Since the vSphere fields are immutable once the cluster is created, a new cluster creation is required if the conflict cannot be resolved by modifying vCenter configuration.