sdk

README

Vagrant Plugin SDK

This repository is a Go library that enables users to write custom Vagrant plugins.

Plugins in Vagrant are separate binaries which communicate with the Vagrant application; the plugin communicates using gRPC, and while it is theoretically possible to build a plugin in any language supported by the gRPC framework. We recommend that the developers leverage the Vagrant SDK.

Generating protos

All Go & Ruby protos are wired into go-generate. To generate them you'll need a few binaries on your path:

• protoc - installation instructions on the gRPC Docs
• grpc_tools_ruby_protoc - from the grpc-tools gem, which bundles that binary prebuilt
• stringer - from the go tools pkg
• mockery - from the go library hosted at vektra/mockery

You also need to ensure the output directory is present:

$ mkdir -p ruby-proto

Once that's all set up you should be ready to roll:

$ go generate .

Documentation

Index

• func Main(opts ...Option)
• type Option
  • func InProcess(tc *plugin.ServeTestConfig) Option
  • func WithComponent(comp interface{}, options interface{}) Option
  • func WithComponents(cs ...interface{}) Option
  • func WithLogger(l hclog.Logger) Option
  • func WithMappers(ms ...interface{}) Option
  • func WithName(n string) Option

Functions

func Main

func Main(opts ...Option)

Main is the primary entrypoint for plugins serving components. This function never returns; it blocks until the program is exited. This should be called immediately in main() in your plugin binaries, no prior setup should be done.

Types

type Option

type Option func(*config)

Option modifies config. Zero or more can be passed to Main.

func InProcess

func InProcess(tc *plugin.ServeTestConfig) Option

func WithComponent

func WithComponent(comp interface{}, options interface{}) Option

WithComponent registers a single component along with options for that component

func WithComponents

func WithComponents(cs ...interface{}) Option

WithComponents specifies a list of components to serve from the plugin binary. This will append to the list of components to serve. You can currently only serve at most one of each type of plugin.

func WithLogger

func WithLogger(l hclog.Logger) Option

func WithMappers

func WithMappers(ms ...interface{}) Option

WithMappers specifies a list of mappers to apply to the plugin.

Mappers are functions that take zero or more arguments and return one result (optionally with an error). These can be used to convert argument types as needed for your plugin functions. For example, you can convert a proto type to a richer Go struct.

Mappers must take zero or more arguments and return exactly one or two values where the second return type must be an error. Example:

func() *Value
func() (*Value, error)
-- the above with any arguments

This will append the mappers to the list of available mappers. A set of default mappers is always included to convert from SDK proto types to richer Go structs.

func WithName

func WithName(n string) Option