package find

import "github.com/vmware/govmomi/find"

Package find implements inventory listing and searching.

The Finder is an alternative to the object.SearchIndex FindByInventoryPath() and FindChild() methods. SearchIndex.FindByInventoryPath requires an absolute path, whereas the Finder also supports relative paths and patterns via path.Match. SearchIndex.FindChild requires a parent to find the child, whereas the Finder also supports an ancestor via recursive object traversal.

The various Finder methods accept a "path" argument, which can absolute or relative to the Folder for the object type. The Finder supports two modes, "list" and "find". The "list" mode behaves like the "ls" command, only searching within the immediate path. The "find" mode behaves like the "find" command, with the search starting at the immediate path but also recursing into sub Folders relative to the Datacenter. The default mode is "list" if the given path contains a "/", otherwise "find" mode is used.

The exception is to use a "..." wildcard with a path to find all objects recursively underneath any root object. For example: VirtualMachineList("/DC1/...")

Finder methods can also convert a managed object reference (aka MOID) to an object instance. For example: VirtualMachine("VirtualMachine:vm-123") or VirtualMachine("vm-123")

See also: https://github.com/vmware/govmomi/blob/main/govc/README.md#usage

Index

Examples

Functions

func InventoryPath 

func InventoryPath(ctx context.Context, client *vim25.Client, obj types.ManagedObjectReference) (string, error)

InventoryPath composes the given object's inventory path. There is no vSphere property or method that provides an inventory path directly. This method uses the ManagedEntity.Parent field to determine the ancestry tree of the object and the ManagedEntity.Name field for each ancestor to compose the path.

Types

type DefaultMultipleFoundError 

type DefaultMultipleFoundError struct {
	// contains filtered or unexported fields
}

func (DefaultMultipleFoundError) Error 

func (e DefaultMultipleFoundError) Error() string

type DefaultNotFoundError 

type DefaultNotFoundError struct {
	// contains filtered or unexported fields
}

func (*DefaultNotFoundError) Error 

func (e *DefaultNotFoundError) Error() string

type Finder 

type Finder struct {
	// contains filtered or unexported fields
}

func NewFinder 

func NewFinder(client *vim25.Client, all ...bool) *Finder

func (*Finder) ClusterComputeResource 

func (f *Finder) ClusterComputeResource(ctx context.Context, path string) (*object.ClusterComputeResource, error)

func (*Finder) ClusterComputeResourceList 

func (f *Finder) ClusterComputeResourceList(ctx context.Context, path string) ([]*object.ClusterComputeResource, error)

func (*Finder) ClusterComputeResourceOrDefault 

func (f *Finder) ClusterComputeResourceOrDefault(ctx context.Context, path string) (*object.ClusterComputeResource, error)

func (*Finder) ComputeResource 

func (f *Finder) ComputeResource(ctx context.Context, path string) (*object.ComputeResource, error)

func (*Finder) ComputeResourceList 

func (f *Finder) ComputeResourceList(ctx context.Context, path string) ([]*object.ComputeResource, error)

func (*Finder) ComputeResourceOrDefault 

func (f *Finder) ComputeResourceOrDefault(ctx context.Context, path string) (*object.ComputeResource, error)

func (*Finder) Datacenter 

func (f *Finder) Datacenter(ctx context.Context, path string) (*object.Datacenter, error)

func (*Finder) DatacenterList 

func (f *Finder) DatacenterList(ctx context.Context, path string) ([]*object.Datacenter, error)

func (*Finder) DatacenterOrDefault 

func (f *Finder) DatacenterOrDefault(ctx context.Context, path string) (*object.Datacenter, error)

func (*Finder) Datastore 

func (f *Finder) Datastore(ctx context.Context, path string) (*object.Datastore, error)

func (*Finder) DatastoreCluster 

func (f *Finder) DatastoreCluster(ctx context.Context, path string) (*object.StoragePod, error)

func (*Finder) DatastoreClusterList 

func (f *Finder) DatastoreClusterList(ctx context.Context, path string) ([]*object.StoragePod, error)

func (*Finder) DatastoreClusterOrDefault 

func (f *Finder) DatastoreClusterOrDefault(ctx context.Context, path string) (*object.StoragePod, error)

func (*Finder) DatastoreList 

func (f *Finder) DatastoreList(ctx context.Context, path string) ([]*object.Datastore, error)

func (*Finder) DatastoreOrDefault 

func (f *Finder) DatastoreOrDefault(ctx context.Context, path string) (*object.Datastore, error)

func (*Finder) DefaultClusterComputeResource 

func (f *Finder) DefaultClusterComputeResource(ctx context.Context) (*object.ClusterComputeResource, error)

func (*Finder) DefaultComputeResource 

func (f *Finder) DefaultComputeResource(ctx context.Context) (*object.ComputeResource, error)

func (*Finder) DefaultDatacenter 

func (f *Finder) DefaultDatacenter(ctx context.Context) (*object.Datacenter, error)

func (*Finder) DefaultDatastore 

func (f *Finder) DefaultDatastore(ctx context.Context) (*object.Datastore, error)

func (*Finder) DefaultDatastoreCluster 

func (f *Finder) DefaultDatastoreCluster(ctx context.Context) (*object.StoragePod, error)

func (*Finder) DefaultFolder 

func (f *Finder) DefaultFolder(ctx context.Context) (*object.Folder, error)

func (*Finder) DefaultHostSystem 

func (f *Finder) DefaultHostSystem(ctx context.Context) (*object.HostSystem, error)

func (*Finder) DefaultNetwork 

func (f *Finder) DefaultNetwork(ctx context.Context) (object.NetworkReference, error)

func (*Finder) DefaultResourcePool 

func (f *Finder) DefaultResourcePool(ctx context.Context) (*object.ResourcePool, error)

func (*Finder) Element 

func (f *Finder) Element(ctx context.Context, ref types.ManagedObjectReference) (*list.Element, error)

Element is deprecated, use InventoryPath() instead.

func (*Finder) Folder 

func (f *Finder) Folder(ctx context.Context, path string) (*object.Folder, error)

func (*Finder) FolderList 

func (f *Finder) FolderList(ctx context.Context, path string) ([]*object.Folder, error)

func (*Finder) FolderOrDefault 

func (f *Finder) FolderOrDefault(ctx context.Context, path string) (*object.Folder, error)

func (*Finder) HostSystem 

func (f *Finder) HostSystem(ctx context.Context, path string) (*object.HostSystem, error)

func (*Finder) HostSystemList 

func (f *Finder) HostSystemList(ctx context.Context, path string) ([]*object.HostSystem, error)

func (*Finder) HostSystemOrDefault 

func (f *Finder) HostSystemOrDefault(ctx context.Context, path string) (*object.HostSystem, error)

func (*Finder) ManagedObjectList 

func (f *Finder) ManagedObjectList(ctx context.Context, path string, include ...string) ([]list.Element, error)

func (*Finder) ManagedObjectListChildren 

func (f *Finder) ManagedObjectListChildren(ctx context.Context, path string, include ...string) ([]list.Element, error)

func (*Finder) Network 

func (f *Finder) Network(ctx context.Context, path string) (object.NetworkReference, error)

Network finds a NetworkReference using a Name, Inventory Path, ManagedObject ID, Logical Switch UUID or Segment ID. With standard vSphere networking, Portgroups cannot have the same name within the same network folder. With NSX, Portgroups can have the same name, even within the same Switch. In this case, using an inventory path results in a MultipleFoundError. A MOID, switch UUID or segment ID can be used instead, as both are unique. See also: https://kb.vmware.com/s/article/79872#Duplicate_names Examples: - Name: "dvpg-1" - Inventory Path: "vds-1/dvpg-1" - Cluster Path: "/dc-1/host/cluster-1/dvpg-1" - ManagedObject ID: "DistributedVirtualPortgroup:dvportgroup-53" - Logical Switch UUID: "da2a59b8-2450-4cb2-b5cc-79c4c1d2144c" - Segment ID: "/infra/segments/vnet_ce50e69b-1784-4a14-9206-ffd7f1f146f7"

func (*Finder) NetworkList 

func (f *Finder) NetworkList(ctx context.Context, path string) ([]object.NetworkReference, error)

func (*Finder) NetworkOrDefault 

func (f *Finder) NetworkOrDefault(ctx context.Context, path string) (object.NetworkReference, error)

func (*Finder) ObjectReference 

func (f *Finder) ObjectReference(ctx context.Context, ref types.ManagedObjectReference) (object.Reference, error)

ObjectReference converts the given ManagedObjectReference to a type from the object package via object.NewReference with the object.Common.InventoryPath field set.

func (*Finder) ResourcePool 

func (f *Finder) ResourcePool(ctx context.Context, path string) (*object.ResourcePool, error)

func (*Finder) ResourcePoolList 

func (f *Finder) ResourcePoolList(ctx context.Context, path string) ([]*object.ResourcePool, error)

func (*Finder) ResourcePoolListAll 

func (f *Finder) ResourcePoolListAll(ctx context.Context, path string) ([]*object.ResourcePool, error)

ResourcePoolListAll combines ResourcePoolList and VirtualAppList VirtualAppList is only called if ResourcePoolList does not find any pools with the given path.

func (*Finder) ResourcePoolOrDefault 

func (f *Finder) ResourcePoolOrDefault(ctx context.Context, path string) (*object.ResourcePool, error)

func (*Finder) SetDatacenter 

func (f *Finder) SetDatacenter(dc *object.Datacenter) *Finder

func (*Finder) VirtualApp 

func (f *Finder) VirtualApp(ctx context.Context, path string) (*object.VirtualApp, error)

func (*Finder) VirtualAppList 

func (f *Finder) VirtualAppList(ctx context.Context, path string) ([]*object.VirtualApp, error)

func (*Finder) VirtualMachine 

func (f *Finder) VirtualMachine(ctx context.Context, path string) (*object.VirtualMachine, error)

func (*Finder) VirtualMachineList 

func (f *Finder) VirtualMachineList(ctx context.Context, path string) ([]*object.VirtualMachine, error)

type MultipleFoundError 

type MultipleFoundError struct {
	// contains filtered or unexported fields
}
Example

Code:play  

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/vmware/govmomi/find"
	"github.com/vmware/govmomi/simulator"
	"github.com/vmware/govmomi/vim25"
)

func main() {
	model := simulator.VPX()
	model.Portgroup = 2

	simulator.Run(func(ctx context.Context, c *vim25.Client) error {
		finder := find.NewFinder(c)

		_, err := finder.Network(ctx, "DC0_DVPG*")
		_, ok := err.(*find.MultipleFoundError) // returns DC0_DVPG{0,1}
		if !ok {
			return errors.New("expected error")
		}

		net0, err := finder.Network(ctx, "DC0_DVPG0")
		if err != nil {
			return err
		}
		fmt.Println(net0.GetInventoryPath())

		net1, err := finder.Network(ctx, "DC0_DVPG1")
		if err != nil {
			return err
		}
		fmt.Println(net1.GetInventoryPath())

		return nil
	}, model)
}

Output:

/DC0/network/DC0_DVPG0
/DC0/network/DC0_DVPG1

func (*MultipleFoundError) Error 

func (e *MultipleFoundError) Error() string

type NotFoundError 

type NotFoundError struct {
	// contains filtered or unexported fields
}

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

Source Files

doc.go error.go finder.go recurser.go

Version
v0.48.1 (latest)
Published
Feb 11, 2025
Platform
linux/amd64
Imports
15 packages
Last checked
2 months ago –

Tools for package owners.