Merge pull request #498 from castorsky/feature/datasource-virtual_machine

feat: add datasource for virtual machines

Author: kp2099

.web-docs/README.md

@@ -49,6 +49,11 @@ packer plugins install github.com/hashicorp/vsphere
   This builder deploys and publishes new virtual machine to a vSphere Supervisor cluster using VM
   Service.
 
+#### Data Sources
+
+- [vsphere-virtualmachine](/packer/integrations/hashicorp/vsphere/latest/components/data-source/vsphere-virtualmachine) -
+  This data source returns the name of a virtual machine that matches all defined filters.
+
 #### Post-Processors
 
 - [vsphere](/packer/integrations/hashicorp/vsphere/latest/components/post-processor/vsphere) -

.web-docs/components/data-source/virtualmachine/README.md

@@ -0,0 +1,235 @@
+Type: `vsphere-virtualmachine`
+Artifact BuilderId: `vsphere.virtualmachine`
+
+This data source retrieves information about existing virtual machines from vSphere
+and returns the name of a virtual machine that matches all specified filters. This
+virtual machine can be used in the vSphere Clone builder to select a template.
+
+## Configuration Reference
+
+### Filters Configuration
+
+**Optional:**
+
+<!-- Code generated from the comments of the Config struct in datasource/virtualmachine/data.go; DO NOT EDIT MANUALLY -->
+
+- `name` (string) - Basic filter with glob support (e.g. `ubuntu_basic*`). Defaults to `*`.
+  Using strict globs will not reduce execution time because vSphere API
+  returns the full inventory. But can be used for better readability over
+  regular expressions.
+
+- `name_regex` (string) - Extended name filter with regular expressions support
+  (e.g. `ubuntu[-_]basic[0-9]*`). Default is empty. The match of the
+  regular expression is checked by substring. Use `^` and `$` to define a
+  full string. For example, the `^[^_]+$` filter will search names
+  without any underscores. The expression must use
+  [Go Regex Syntax](https://pkg.go.dev/regexp/syntax).
+
+- `template` (bool) - Filter to return only objects that are virtual machine templates.
+  Defaults to `false` and returns all virtual machines.
+
+- `host` (string) - Filter to search virtual machines only on the specified ESX host.
+
+- `tag` ([]Tag) - Filter to return only the virtual machines that have attached all specified tags.
+  Specify one or more `tag` blocks to define list of tags for the filter.
+  
+  HCL Example:
+  
+  ```hcl
+  	tag {
+  	  category = "team"
+  	  name     = "operations"
+  	}
+  	tag {
+  	  category = "sla"
+  	  name     = "gold"
+  	}
+  ```
+
+- `latest` (bool) - This filter determines how to handle multiple virtual machines that were matched
+  with all previous filters. Virtual machine creation time is being used to find
+  the latest. By default, multiple matching machines results in an error.
+
+<!-- End of code generated from the comments of the Config struct in datasource/virtualmachine/data.go; -->
+
+
+### Tags Filter Configuration
+
+**Required:**
+
+<!-- Code generated from the comments of the Tag struct in datasource/virtualmachine/data.go; DO NOT EDIT MANUALLY -->
+
+- `name` (string) - Name of the tag added to virtual machine which must pass the `tag`
+  filter.
+
+- `category` (string) - Name of the tag category that contains the tag.
+  
+  -> **Note:** Both `name` and `category` must be specified in the `tag`
+  filter.
+
+<!-- End of code generated from the comments of the Tag struct in datasource/virtualmachine/data.go; -->
+
+
+### Connection Configuration
+
+**Optional:**
+
+<!-- Code generated from the comments of the ConnectConfig struct in builder/vsphere/common/step_connect.go; DO NOT EDIT MANUALLY -->
+
+- `vcenter_server` (string) - The fully qualified domain name or IP address of the vCenter instance
+  instance.
+
+- `username` (string) - The username to authenticate with the vCenter instance.
+
+- `password` (string) - The password to authenticate with the vCenter instance.
+
+- `insecure_connection` (bool) - Do not validate the certificate of the vCenter instance.
+  Defaults to `false`.
+  
+  -> **Note:** This option is beneficial in scenarios where the certificate
+  is self-signed or does not meet standard validation criteria.
+
+- `datacenter` (string) - The name of the datacenter object in the vSphere inventory.
+  
+  -> **Note:** Required if more than one datacenter object exists in the
+  vSphere inventory.
+
+<!-- End of code generated from the comments of the ConnectConfig struct in builder/vsphere/common/step_connect.go; -->
+
+
+## Output
+
+<!-- Code generated from the comments of the DatasourceOutput struct in datasource/virtualmachine/data.go; DO NOT EDIT MANUALLY -->
+
+- `vm_name` (string) - Name of the found virtual machine.
+
+<!-- End of code generated from the comments of the DatasourceOutput struct in datasource/virtualmachine/data.go; -->
+
+
+## Example Usage
+
+### Filter by Tags and Get Latest
+
+This example demonstrates how to connect to vSphere cluster and search for the latest
+virtual machine that matches the specified tag filters.
+
+```hcl
+data "vsphere-virtualmachine" "example" {
+  vcenter_server = "vcenter.example.com"
+  username       = "administrator@vsphere.local"
+  password       = "VMware1!"
+  datacenter     = "dc-01"
+  latest         = true
+
+  tag {
+    category = "team"
+    name     = "operations"
+  }
+
+  tag {
+    category = "sla"
+    name     = "gold"
+  }
+}
+
+locals {
+  vm_name = data.vsphere-virtualmachine.example.vm_name
+}
+
+source "null" "example" {
+    communicator = "none"
+}
+
+build {
+  sources = [
+    "source.null.example"
+  ]
+
+  provisioner "shell-local" {
+    inline = [
+      "echo vm_name: ${local.vm_name}",
+    ]
+  }
+}
+```
+
+### Filter by Name with Glob Pattern
+
+This example shows how to use the `name` filter with glob patterns to find virtual
+machines matching a specific naming convention.
+
+```hcl
+data "vsphere-virtualmachine" "example" {
+  vcenter_server = "vcenter.example.com"
+  username       = "administrator@vsphere.local"
+  password       = "VMware1!"
+  datacenter     = "dc-01"
+  name           = "linux-debian-13-*"
+  latest         = true
+}
+
+locals {
+  vm_result = data.vsphere-virtualmachine.example.vm_name
+}
+```
+
+### Filter by Name with Regular Expression
+
+This example demonstrates using the `name_regex` filter for more complex pattern
+matching with regular expressions.
+
+```hcl
+data "vsphere-virtualmachine" "example" {
+  vcenter_server = "vcenter.example.com"
+  username       = "administrator@vsphere.local"
+  password       = "VMware1!"
+  datacenter     = "dc-01"
+  name_regex     = "^linux-debian-[0-9]+-.+$"
+  latest         = true
+}
+
+locals {
+  vm_result = data.vsphere-virtualmachine.example.vm_name
+}
+```
+
+### Filter for VM Templates Only
+
+This example shows how to use the `template` filter to search only for virtual
+machine templates.
+
+```hcl
+data "vsphere-virtualmachine" "example" {
+  vcenter_server = "vcenter.example.com"
+  username       = "administrator@vsphere.local"
+  password       = "VMware1!"
+  datacenter     = "dc-01"
+  name           = "linux-debian-13-*"
+  template       = true
+}
+
+locals {
+  result_template = data.vsphere-virtualmachine.example.vm_name
+}
+```
+
+### Filter by ESX Host
+
+This example demonstrates filtering virtual machines by a specific ESX host,
+combined with other filters.
+
+```hcl
+data "vsphere-virtualmachine" "example" {
+  vcenter_server = "vcenter.example.com"
+  username       = "administrator@vsphere.local"
+  password       = "VMware1!"
+  datacenter     = "dc-01"
+  host           = "esxi-01.example.com"
+  name           = "linux-debian-13-*"
+  latest         = true
+}
+
+locals {
+  vm_result = data.vsphere-virtualmachine.example.vm_name
+}
+```

.web-docs/metadata.hcl

@@ -33,4 +33,9 @@ integration {
     name = "vSphere Template"
     slug = "vsphere-template"
   }
+  component {
+    type = "data-source"
+    name = "vSphere Virtual Machine"
+    slug = "vsphere-virtualmachine"
+  }
 }

builder/vsphere/common/step_connect.go

@@ -59,6 +59,8 @@ type StepConnect struct {
 }
 
 func (s *StepConnect) Run(_ context.Context, state multistep.StateBag) multistep.StepAction {
+	// Convert common.ConnectConfig to driver.ConnectConfig
+	// Both structs have identical fields to avoid import cycles
 	d, err := driver.NewDriver(&driver.ConnectConfig{
 		VCenterServer:      s.Config.VCenterServer,
 		Username:           s.Config.Username,

builder/vsphere/driver/cluster.go

@@ -14,7 +14,7 @@ type Cluster struct {
 // Returns a Cluster object or an error if not found or if the retrieval
 // process fails.
 func (d *VCenterDriver) FindCluster(name string) (*Cluster, error) {
-	c, err := d.finder.ClusterComputeResource(d.ctx, name)
+	c, err := d.Finder.ClusterComputeResource(d.Ctx, name)
 	if err != nil {
 		return nil, err
 	}

builder/vsphere/driver/datastore.go

@@ -37,7 +37,7 @@ type DatastoreDriver struct {
 // NewDatastore creates a new Datastore object.
 func (d *VCenterDriver) NewDatastore(ref *types.ManagedObjectReference) Datastore {
 	return &DatastoreDriver{
-		ds:     object.NewDatastore(d.client.Client, *ref),
+		ds:     object.NewDatastore(d.Client.Client, *ref),
 		driver: d,
 	}
 }
@@ -68,7 +68,7 @@ func (d *VCenterDriver) FindDatastore(name string, host string) (Datastore, erro
 		name = inf.Name
 	}
 
-	ds, err := d.finder.Datastore(d.ctx, name)
+	ds, err := d.Finder.Datastore(d.Ctx, name)
 	if err != nil {
 		return nil, fmt.Errorf("error finding datastore with name %s: %s", name, err)
 	}
@@ -87,10 +87,10 @@ func (d *VCenterDriver) GetDatastoreName(id string) (string, error) {
 		Type:  "Datastore",
 		Value: id,
 	}
-	pc := property.DefaultCollector(d.vimClient)
+	pc := property.DefaultCollector(d.VimClient)
 	var me mo.ManagedEntity
 
-	err := pc.RetrieveOne(d.ctx, obj, []string{"name"}, &me)
+	err := pc.RetrieveOne(d.Ctx, obj, []string{"name"}, &me)
 	if err != nil {
 		return id, err
 	}
@@ -108,22 +108,22 @@ func (ds *DatastoreDriver) Info(params ...string) (*mo.Datastore, error) {
 		p = params
 	}
 	var info mo.Datastore
-	err := ds.ds.Properties(ds.driver.ctx, ds.ds.Reference(), p, &info)
+	err := ds.ds.Properties(ds.driver.Ctx, ds.ds.Reference(), p, &info)
 	if err != nil {
 		return nil, err
 	}
 	return &info, nil
 }
 
 func (ds *DatastoreDriver) DirExists(filepath string) bool {
-	_, err := ds.ds.Stat(ds.driver.ctx, filepath)
+	_, err := ds.ds.Stat(ds.driver.Ctx, filepath)
 	var notFoundError *object.DatastoreNoSuchDirectoryError
 	return !errors.As(err, &notFoundError)
 }
 
 // FileExists checks if a file exists in a datastore.
 func (ds *DatastoreDriver) FileExists(path string) bool {
-	_, err := ds.ds.Stat(ds.driver.ctx, path)
+	_, err := ds.ds.Stat(ds.driver.Ctx, path)
 	return err == nil
 }
 
@@ -145,9 +145,9 @@ func (ds *DatastoreDriver) ResolvePath(path string) string {
 // GetDatastoreFilePath retrieves the full path of a file in a specified datastore directory by its datastore ID and name.
 func (d *VCenterDriver) GetDatastoreFilePath(datastoreID, dir, filename string) (string, error) {
 	ref := types.ManagedObjectReference{Type: "Datastore", Value: datastoreID}
-	ds := object.NewDatastore(d.vimClient, ref)
+	ds := object.NewDatastore(d.VimClient, ref)
 
-	b, err := ds.Browser(d.ctx)
+	b, err := ds.Browser(d.Ctx)
 	if err != nil {
 		return filename, err
 	}
@@ -157,12 +157,12 @@ func (d *VCenterDriver) GetDatastoreFilePath(datastoreID, dir, filename string)
 		MatchPattern: []string{pat},
 	}
 
-	task, err := b.SearchDatastore(d.ctx, dir, &spec)
+	task, err := b.SearchDatastore(d.Ctx, dir, &spec)
 	if err != nil {
 		return filename, err
 	}
 
-	info, err := task.WaitForResult(d.ctx, nil)
+	info, err := task.WaitForResult(d.Ctx, nil)
 	if err != nil {
 		return filename, err
 	}
@@ -182,7 +182,7 @@ func (d *VCenterDriver) GetDatastoreFilePath(datastoreID, dir, filename string)
 // in the datastore, with optional host context.
 func (ds *DatastoreDriver) UploadFile(src, dst, host string, setHost bool) error {
 	p := soap.DefaultUpload
-	ctx := ds.driver.ctx
+	ctx := ds.driver.Ctx
 
 	if setHost && host != "" {
 		h, err := ds.driver.FindHost(host)
@@ -197,22 +197,22 @@ func (ds *DatastoreDriver) UploadFile(src, dst, host string, setHost bool) error
 
 // Delete deletes a file from a datastore by a path.
 func (ds *DatastoreDriver) Delete(path string) error {
-	dc, err := ds.driver.finder.Datacenter(ds.driver.ctx, ds.ds.DatacenterPath)
+	dc, err := ds.driver.Finder.Datacenter(ds.driver.Ctx, ds.ds.DatacenterPath)
 	if err != nil {
 		return err
 	}
 	fm := ds.ds.NewFileManager(dc, false)
-	return fm.Delete(ds.driver.ctx, path)
+	return fm.Delete(ds.driver.Ctx, path)
 }
 
 // MakeDirectory creates a directory in a datastore by a path.
 func (ds *DatastoreDriver) MakeDirectory(path string) error {
-	dc, err := ds.driver.finder.Datacenter(ds.driver.ctx, ds.ds.DatacenterPath)
+	dc, err := ds.driver.Finder.Datacenter(ds.driver.Ctx, ds.ds.DatacenterPath)
 	if err != nil {
 		return err
 	}
 	fm := ds.ds.NewFileManager(dc, false)
-	return fm.FileManager.MakeDirectory(ds.driver.ctx, path, dc, true)
+	return fm.FileManager.MakeDirectory(ds.driver.Ctx, path, dc, true)
 }
 
 // RemoveDatastorePrefix removes the datastore prefix from a path.