api: Update folder.PlaceVMsXCluster to return available candidate networks

Signed-off-by: Pradeep Ramachandra <[email protected]>

Author: Pradeep Ramachandra

cli/folder/place.go

@@ -10,6 +10,7 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"reflect"
 	"strings"
 	"text/tabwriter"
 
@@ -144,6 +145,10 @@ func (cmd *place) Process(ctx context.Context) error {
 }
 
 func (cmd *place) Run(ctx context.Context, f *flag.FlagSet) error {
+
+	// Register runtime override before any unmarshalling/type casting.
+	types.Add("ClusterClusterInitialPlacementAction", reflect.TypeOf((*types.ClusterClusterInitialPlacementActionEx)(nil)).Elem())
+
 	client, err := cmd.Client()
 	if err != nil {
 		return err
@@ -296,6 +301,20 @@ func (res *placementResult) initialPlacementAction(w io.Writer, pinfo types.Plac
 		fmt.Fprintf(w, "%s:\t%s\n", f.name, path)
 	}
 
+	// Display the available network references from the placement recommendation.
+	if act, ok := any(action).(*types.ClusterClusterInitialPlacementActionEx); ok {
+		if len(act.AvailableNetworks) > 0 {
+			fmt.Fprintf(w, "  AvailableNetworks:\n")
+			for _, net := range act.AvailableNetworks {
+				path, err := find.InventoryPath(res.ctx, res.vimClient, net)
+				if err != nil {
+					return err
+				}
+				fmt.Fprintf(w, "\t- %s\n", path)
+			}
+		}
+	}
+
 	return nil
 }
 
@@ -329,6 +348,17 @@ func (res *placementResult) relocatePlacementAction(w io.Writer, pinfo types.Pla
 		fmt.Fprintf(w, "%s:\t%s\n", f.name, path)
 	}
 
+	// Display the available network references from the placement recommendation.
+	if len(action.AvailableNetworks) > 0 {
+		fmt.Fprintf(w, "  AvailableNetworks:\n")
+		for _, net := range action.AvailableNetworks {
+			path, err := find.InventoryPath(res.ctx, res.vimClient, net)
+			if err != nil {
+				return err
+			}
+			fmt.Fprintf(w, "\t- %s\n", path)
+		}
+	}
 	return nil
 }
 

object/folder.go

@@ -6,6 +6,7 @@ package object
 
 import (
 	"context"
+	"reflect"
 
 	"github.com/vmware/govmomi/vim25"
 	"github.com/vmware/govmomi/vim25/methods"
@@ -215,6 +216,7 @@ func (f Folder) MoveInto(ctx context.Context, list []types.ManagedObjectReferenc
 }
 
 func (f Folder) PlaceVmsXCluster(ctx context.Context, spec types.PlaceVmsXClusterSpec) (*types.PlaceVmsXClusterResult, error) {
+	types.Add("ClusterClusterInitialPlacementAction", reflect.TypeOf((*types.ClusterClusterInitialPlacementActionEx)(nil)).Elem())
 	req := types.PlaceVmsXCluster{
 		This:          f.Reference(),
 		PlacementSpec: spec,

simulator/folder.go

@@ -774,7 +774,7 @@ func addPlacementFault(body *methods.PlaceVmsXClusterBody, vmName string, vmRef
 	body.Res.Returnval.Faults = append(body.Res.Returnval.Faults, faults)
 }
 
-func generateRelocatePlacementAction(ctx *Context, inputRelocateSpec *types.VirtualMachineRelocateSpec, pool *ResourcePool,
+func generateRelocatePlacementAction(ctx *Context, vmSpec types.PlaceVmsXClusterSpecVmPlacementSpec, pool *ResourcePool,
 	cluster *ClusterComputeResource, hostRequired, datastoreRequired bool) *types.ClusterClusterRelocatePlacementAction {
 	var relocateSpec *types.VirtualMachineRelocateSpec
 
@@ -788,7 +788,7 @@ func generateRelocatePlacementAction(ctx *Context, inputRelocateSpec *types.Virt
 	}
 
 	if datastoreRequired {
-		relocateSpec = inputRelocateSpec
+		relocateSpec = vmSpec.RelocateSpec
 
 		ds := ctx.Map.Get(cluster.Datastore[rand.Intn(len(cluster.Datastore))]).(*Datastore)
 
@@ -799,6 +799,27 @@ func generateRelocatePlacementAction(ctx *Context, inputRelocateSpec *types.Virt
 		}
 	}
 
+	// Get all networks available in the cluster.
+	clusterNetworks := make(map[string]bool)
+	for _, netRef := range cluster.Network {
+		clusterNetworks[netRef.Value] = true
+	}
+
+	// Select candidate networks that are also available in the target cluster.
+	unique := make(map[string]types.ManagedObjectReference)
+	for _, nic := range vmSpec.CandidateNetworks {
+		for _, cand := range nic.Networks {
+			if clusterNetworks[cand.Value] {
+				unique[cand.Value] = cand
+			}
+		}
+	}
+
+	// Store in AvailableNetworks.
+	for _, ref := range unique {
+		placementAction.AvailableNetworks = append(placementAction.AvailableNetworks, ref)
+	}
+
 	placementAction.RelocateSpec = relocateSpec
 	return &placementAction
 }
@@ -852,7 +873,7 @@ func generateRecommendationForRelocate(ctx *Context, req *types.PlaceVmsXCluster
 			Target:     &cluster.Self,
 		}
 
-		placementAction := generateRelocatePlacementAction(ctx, spec.RelocateSpec, pool, cluster, hostRequired, datastoreRequired)
+		placementAction := generateRelocatePlacementAction(ctx, spec, pool, cluster, hostRequired, datastoreRequired)
 
 		reco.Action = append(reco.Action, placementAction)
 
@@ -1002,11 +1023,10 @@ func fillConfigSpecWithDatastore(ctx *Context, inputConfigSpec, configSpec *type
 	}
 }
 
-func generateInitialPlacementAction(ctx *Context, inputConfigSpec *types.VirtualMachineConfigSpec, pool *ResourcePool,
-	cluster *ClusterComputeResource, hostRequired, datastoreRequired bool) *types.ClusterClusterInitialPlacementAction {
-	var configSpec *types.VirtualMachineConfigSpec
+func generateInitialPlacementAction(ctx *Context, vmSpec *types.PlaceVmsXClusterSpecVmPlacementSpec, pool *ResourcePool,
+	cluster *ClusterComputeResource, hostRequired, datastoreRequired bool) types.BaseClusterAction {
 
-	placementAction := types.ClusterClusterInitialPlacementAction{
+	placementAction := &types.ClusterClusterInitialPlacementActionEx{
 		Pool: pool.Self,
 	}
 
@@ -1016,18 +1036,40 @@ func generateInitialPlacementAction(ctx *Context, inputConfigSpec *types.Virtual
 	}
 
 	if datastoreRequired {
-		configSpec = inputConfigSpec
+		configSpec := vmSpec.ConfigSpec // value copy
 
 		// TODO: This is just an initial implementation aimed at returning some data but it is not
 		// necessarily fully consistent, like we should ensure the host, if also required, has the
 		// datastore mounted.
 		ds := ctx.Map.Get(cluster.Datastore[rand.Intn(len(cluster.Datastore))]).(*Datastore)
 
-		fillConfigSpecWithDatastore(ctx, inputConfigSpec, configSpec, ds)
+		fillConfigSpecWithDatastore(ctx, &vmSpec.ConfigSpec, &configSpec, ds)
+		placementAction.ConfigSpec = &configSpec
+	} else {
+		placementAction.ConfigSpec = &vmSpec.ConfigSpec
 	}
 
-	placementAction.ConfigSpec = configSpec
-	return &placementAction
+	// Get all networks available in the cluster.
+	clusterNetworks := make(map[string]bool)
+	for _, netRef := range cluster.Network {
+		clusterNetworks[netRef.Value] = true
+	}
+
+	// Select candidate networks that are also available in the target cluster.
+	unique := make(map[string]types.ManagedObjectReference)
+	for _, nic := range vmSpec.CandidateNetworks {
+		for _, cand := range nic.Networks {
+			if clusterNetworks[cand.Value] {
+				unique[cand.Value] = cand
+			}
+		}
+	}
+
+	// Store in AvailableNetworks.
+	for _, ref := range unique {
+		placementAction.AvailableNetworks = append(placementAction.AvailableNetworks, ref)
+	}
+	return placementAction
 }
 
 func generateRecommendationForCreateAndPowerOn(ctx *Context, req *types.PlaceVmsXCluster) *methods.PlaceVmsXClusterBody {
@@ -1072,7 +1114,7 @@ func generateRecommendationForCreateAndPowerOn(ctx *Context, req *types.PlaceVms
 			Target:     &cluster.Self,
 		}
 
-		placementAction := generateInitialPlacementAction(ctx, &spec.ConfigSpec, pool, cluster, hostRequired, datastoreRequired)
+		placementAction := generateInitialPlacementAction(ctx, &spec, pool, cluster, hostRequired, datastoreRequired)
 
 		reco.Action = append(reco.Action, placementAction)
 

simulator/folder_test.go

@@ -721,6 +721,38 @@ func TestPlaceVmsXClusterCreateAndPowerOnWithCandidateNetworks(t *testing.T) {
 		if len(res.PlacementInfos) != len(spec.VmPlacementSpecs) {
 			t.Errorf("%d PlacementInfos vs %d VmPlacementSpecs", len(res.PlacementInfos), len(spec.VmPlacementSpecs))
 		}
+
+		// Validate AvailableNetworks returned in placement recommendations.
+		for _, pinfo := range res.PlacementInfos {
+			for i, action := range pinfo.Recommendation.Action {
+				// Ensure the action is of expected extended type.
+				initPlaceAction, ok := action.(*types.ClusterClusterInitialPlacementActionEx)
+				if !ok {
+					t.Errorf("Action[%d] is not ClusterClusterInitialPlacementActionEx, got %T", i, action)
+					continue
+				}
+				if len(initPlaceAction.AvailableNetworks) == 0 {
+					t.Errorf("AvailableNetworks is empty for VM %v", pinfo.Vm)
+				} else {
+					t.Logf("AvailableNetworks for VM %v:", pinfo.Vm)
+					for _, net := range initPlaceAction.AvailableNetworks {
+						t.Logf("- %s", net.Value)
+					}
+				}
+				// Define the expected networks that should be present in AvailableNetworks.
+				expected := map[string]bool{
+					netA.Reference().Value: true,
+					netB.Reference().Value: true,
+				}
+
+				// Verify that all returned networks are part of the expected set.
+				for _, actual := range initPlaceAction.AvailableNetworks {
+					if !expected[actual.Value] {
+						t.Errorf("unexpected network in availableNetworks: %s", actual.Value)
+					}
+				}
+			}
+		}
 	}, vpx)
 }
 
@@ -850,14 +882,36 @@ func TestPlaceVmsXClusterRelocate(t *testing.T) {
 					t.Errorf("Test %v: %d PlacementInfos vs %d VmPlacementSpecs", testNo, len(res.PlacementInfos), len(placeVmsXClusterSpec.VmPlacementSpecs))
 				}
 
+				// Validate AvailableNetworks returned in placement recommendations.
 				for _, pinfo := range res.PlacementInfos {
 					for _, action := range pinfo.Recommendation.Action {
-						if relocateAction, ok := action.(*types.ClusterClusterRelocatePlacementAction); ok {
-							if relocateAction.TargetHost == nil {
-								t.Errorf("Test %v: received nil host recommendation", testNo)
-							}
-						} else {
+						relocateAction, ok := action.(*types.ClusterClusterRelocatePlacementAction)
+						if !ok {
 							t.Errorf("Test %v: received wrong action type in recommendation", testNo)
+							continue
+						}
+						if relocateAction.TargetHost == nil {
+							t.Errorf("Test %v: received nil host recommendation", testNo)
+						}
+						// Check if AvailableNetworks field is populated.
+						if len(relocateAction.AvailableNetworks) == 0 {
+							t.Errorf("AvailableNetworks is empty for VM %v", pinfo.Vm)
+						} else {
+							t.Logf("AvailableNetworks for VM %v:", pinfo.Vm)
+							for _, net := range relocateAction.AvailableNetworks {
+								t.Logf("- %s", net.Value)
+							}
+						}
+						// Define the expected networks that should be present in AvailableNetworks.
+						expected := map[string]bool{
+							netA.Reference().Value: true,
+							netB.Reference().Value: true,
+						}
+						// Verify that all returned networks are part of the expected set.
+						for _, actual := range relocateAction.AvailableNetworks {
+							if !expected[actual.Value] {
+								t.Errorf("unexpected network in availableNetworks: %s", actual.Value)
+							}
 						}
 					}
 				}

vim25/types/unreleased.go

@@ -145,9 +145,10 @@ func init() {
 
 type ClusterClusterRelocatePlacementAction struct {
 	ClusterAction
-	TargetHost   *ManagedObjectReference     `xml:"targetHost,omitempty"`
-	Pool         ManagedObjectReference      `xml:"pool"`
-	RelocateSpec *VirtualMachineRelocateSpec `xml:"relocateSpec,omitempty"`
+	TargetHost        *ManagedObjectReference     `xml:"targetHost,omitempty"`
+	Pool              ManagedObjectReference      `xml:"pool"`
+	RelocateSpec      *VirtualMachineRelocateSpec `xml:"relocateSpec,omitempty"`
+	AvailableNetworks []ManagedObjectReference    `xml:"availableNetworks,omitempty"`
 }
 
 func init() {
@@ -163,3 +164,68 @@ type PodVMOverheadInfo struct {
 	PodVMOverheadWithoutPageSharing int32 `xml:"podVMOverheadWithoutPageSharing"`
 	PodVMOverheadWithPageSharing    int32 `xml:"podVMOverheadWithPageSharing"`
 }
+
+// Describes an action for the initial placement of a virtual machine in a cluster.
+//
+// This action is used by the cross cluster placement API when a virtual machine
+// needs to be placed across a set of given clusters. See `Folder.PlaceVmsXCluster`.
+// This action encapsulates details about the chosen cluster (via the resource pool
+// inside that cluster), the chosen host and the chosen datastores for the disks of
+// the virtual machine.
+type ClusterClusterInitialPlacementActionEx struct {
+	ClusterAction
+
+	// The host where the virtual machine should be initially placed.
+	//
+	// This field is optional because the primary use case of
+	// `Folder.PlaceVmsXCluster` is to select the best cluster for placing VMs. This
+	// `ClusterClusterInitialPlacementAction.targetHost` denotes the best host
+	// within the best cluster and it is only returned if the client asks for it,
+	// which is determined by `PlaceVmsXClusterSpec.hostRecommRequired`.
+	// If `PlaceVmsXClusterSpec.hostRecommRequired` is set to true, then the
+	// targetHost is returned with a valid value and if it is either set to false
+	// or left unset, then targetHost is also left unset. When this field is unset,
+	// then it means that the client did not ask for the target host within the
+	// recommended cluster. It does not mean that there is no recommended host
+	// for placing this VM in the recommended cluster.
+	//
+	// Refers instance of `HostSystem`.
+	TargetHost *ManagedObjectReference `xml:"targetHost,omitempty" json:"targetHost,omitempty"`
+
+	// The chosen resource pool for placing the virtual machine.
+	//
+	// This is non-optional because recommending the best cluster (by recommending the
+	// resource pool in the best cluster) is the primary use case for the
+	// `ClusterClusterInitialPlacementAction`.
+	//
+	// Refers instance of `ResourcePool`.
+	Pool ManagedObjectReference `xml:"pool" json:"pool"`
+
+	// The config spec of the virtual machine to be placed.
+	//
+	// The `Folder.PlaceVmsXCluster` method takes input of `VirtualMachineConfigSpec`
+	// from client and populates the backing for each virtual disk and the VM home
+	// path in it unless the input ConfigSpec already provides them. The existing
+	// settings in the input ConfigSpec are preserved and not overridden in the
+	// returned ConfigSpec in this action as well as the resulting
+	// `ClusterRecommendation`. This field is set based on whether the client needs
+	// `Folder.PlaceVmsXCluster` to recommend a backing datastore for the disks of
+	// the candidate VMs or not, which is specified via
+	// `PlaceVmsXClusterSpec.datastoreRecommRequired`. If
+	// `PlaceVmsXClusterSpec.datastoreRecommRequired` is set to true, then this
+	// `ClusterClusterInitialPlacementAction.configSpec` is also set with the
+	// backing of each disk populated. If
+	// `PlaceVmsXClusterSpec.datastoreRecommRequired` is either set to false or left
+	// unset, then this field is also left unset. When this field is left unset,
+	// then it means that the client did not ask to populate the backing datastore
+	// for the disks of the candidate VMs.
+	ConfigSpec *VirtualMachineConfigSpec `xml:"configSpec,omitempty" json:"configSpec,omitempty"`
+
+	AvailableNetworks []ManagedObjectReference `xml:"availableNetworks,omitempty" json:"availableNetworks,omitempty"`
+}
+
+func init() {
+	minAPIVersionForType["ClusterClusterInitialPlacementActionEx"] = "9.1.0.0"
+	t["ClusterClusterInitialPlacementActionEx"] = reflect.TypeOf((*ClusterClusterInitialPlacementActionEx)(nil)).Elem()
+	Add("ClusterClusterInitialPlacementAction", reflect.TypeOf((*ClusterClusterInitialPlacementActionEx)(nil)).Elem())
+}