Go Plugin Development: Guests

Outside of these components, the caller must provide all other arguments that are required.

The most basic guest plugin is composed of:

A detection function that determines if the plugin is usable on the system (is the expected guest)
A set of capabilities that define actions that can be run against the guest
An entry point defining the plugin options

Note: To quickly get started writing Go guest plugins, clone the vagrant-guest-plugin-skeleton template and follow the Readme.

The file structure of a guest plugin looks like:

- myplugin
  |- main.go
  \- guest
    |- myguest.go
    \- cap
      |- mycapability.go

Where main.go defines the plugin options. guest/myguest.go defines the core plugin functionality including the detection of the guest. cap/* has the definitions of all the guest plugin capabilities. These capabilities are the same as those for Ruby plugins.

Writing a guest plugin

A guest must satisfy the interface defined for a guest component

    GuestDetectFunc() interface{}
    ParentFunc() interface{}
    HasCapabilityFunc() interface{}
    CapabilityFunc(capName string) interface{}

Src: https://github.com/hashicorp/vagrant-plugin-sdk/blob/main/component/component.go

GuestDetectFunc: returns a function that defines the code that determines if the guest is detected. The returned function must return a bool.

ParentFunc: returns a function that defines the code that determines the most immediate parent plugin. A child plugin will inherit all the capabilities defined in the parent. The returned function must return a string.

HasCapabilityFunc: returns a function that defines a lookup for a capability. The returned function must return an bool.

CapabilityFunc: returns a capability function that is defined by the plugin registered by a given name.

An example guest plugin

// file: myplugin/guest/myguest.go
package guest
 
import (
 "github.com/hashicorp/vagrant-plugin-sdk/component"
 sdkcore "github.com/hashicorp/vagrant-plugin-sdk/core"
)
 
// AlwaysTrueGuest is a Guest implementation for myplugin.
type AlwaysTrueGuest struct {
}
 
// DetectFunc implements component.Guest
func (h *AlwaysTrueGuest) GuestDetectFunc() interface{} {
  return h.Detect
}
 
func (h *AlwaysTrueGuest) Detect(t sdkcore.Target) (bool, error) {
  return true, nil
}
 
// ParentsFunc implements component.Guest
func (h *AlwaysTrueGuest) ParentFunc() interface{} {
  return h.Parent
}
 
func (h *AlwaysTrueGuest) Parent() string {
  // This plugin has no parents
  return ""
}
 
// HasCapabilityFunc implements component.Guest
func (h *AlwaysTrueGuest) HasCapabilityFunc() interface{} {
  return h.CheckCapability
}
 
func (h *AlwaysTrueGuest) CheckCapability(n *component.NamedCapability) bool {
  // This plugin has no capabilities
  return false
}
 
// CapabilityFunc implements component.Guest
func (h *AlwaysTrueGuest) CapabilityFunc(name string) interface{} {
  return fmt.Errorf("requested capability %s not found", name)
}
 
var (
 _ component.Guest = (*AlwaysTrueGuest)(nil)
)
 
// file: myplugin/main.go
package myplugin
 
import (
 sdk "github.com/hashicorp/vagrant-plugin-sdk"
 "github.com/hashicorp/vagrant/builtin/myplugin/guest"
)
 
// Options are the SDK options to use for instantiation.
var ComponentOptions = []sdk.Option{
 sdk.WithComponents(
    // Include the defined guest as a component defined in this plugin
   &guest.AlwaysTrueGuest{},
 ),
}
 
func main() {
 sdk.Main(ComponentOptions...)
 os.Exit(0)
}

In this example, the guest plugin will always be detected. It does not define any capabilities, or have any parent plugins.

Defining and registering guest capabilities

A guest plugin may have capabilities two ways:

By defining and implementing the capability in the plugin
By inheriting the capability from a parent guest plugin

Define a capability by writing out a function that returns the desired capability

// file: myplugin/guest/cap/mycapability.go
package cap
 
import (
 "io/ioutil"
 
 "github.com/hashicorp/vagrant-plugin-sdk/terminal"
)
 
func WriteHelloFunc() interface{} {
 return WriteHello
}
 
func WriteHello(trm terminal.UI) error {
 trm.Output("Hello world")
 return nil
}

Make the capability available to the plugin by filling in the capability functions

myplugin/guest/myguest.go
// HasCapabilityFunc implements component.Guest
func (h *AlwaysTrueGuest) HasCapabilityFunc() interface{} {
 return h.CheckCapability
}
 
func (h *AlwaysTrueGuest) CheckCapability(n *component.NamedCapability) bool {
 if n.Capability == "write_hello" {
   return true
 }
 return false
}
 
// CapabilityFunc implements component.Guest
func (h *AlwaysTrueGuest) CapabilityFunc(name string) interface{} {
 if name == "write_hello" {
   return h.WriteHelloCap
 }
 return errors.New("Invalid capability requested")
}
 
func (h *AlwaysTrueGuest) WriteHelloCap(ui terminal.UI) error {
 return cap.WriteHello(ui)
}

A guest plugin may inherit the capabilities of a parent function by defining a parent in the plugin implementation. This is done by setting the return value of the Parent function to the name of the desired parent plugin. Go based guest plugins may use Ruby based plugins as their parent.

// file: myplugin/guest/myguest.go
 
...
 
// ParentsFunc implements component.Guest
func (h *AlwaysTrueGuest) ParentFunc() interface{} {
  return h.Parent
}
 
func (h *AlwaysTrueGuest) Parent() string {
  // This plugin sets the parent to the "debian" plugin which is provided
  // as a Ruby plugin. This AlwaysTrueGuest now inherits all the capabilities
  // of the debian Ruby guest plugin. 
  return "debian"
}