plugin

Documentation

Overview

Package plugin has the functions necessary for discovering and launching plugins. This exposes both builtin plugins as well as external, custom plugins.

Index

• Variables
• func BuiltinFactory(name string, typ component.Type) interface{}
• func CallDynamicFunc(log hclog.Logger, f interface{}, args ...argmapper.Arg) (*argmapper.Result, error)
• func DefaultPaths(pwd string) ([]string, error)
• func Discover(cfg *config.Plugin, paths []string) (*exec.Cmd, error)
• func Factory(cmd *exec.Cmd, typ component.Type) interface{}
• func ReattachPluginFactory(reattach *plugin.ReattachConfig, typ component.Type) interface{}
• type Instance

Variables

var (
	// Builtins is the map of all available builtin plugins and their
	// options for launching them.
	Builtins = map[string][]sdk.Option{
		"files":                    files.Options,
		"pack":                     pack.Options,
		"docker":                   docker.Options,
		"docker-pull":              dockerpull.Options,
		"exec":                     exec.Options,
		"google-cloud-run":         cloudrun.Options,
		"azure-container-instance": aci.Options,
		"kubernetes":               k8s.Options,
		"kubernetes-apply":         k8sapply.Options,
		"aws-ecs":                  ecs.Options,
		"aws-ecr":                  ecr.Options,
		"nomad":                    nomad.Options,
		"nomad-jobspec":            jobspec.Options,
		"aws-ami":                  ami.Options,
		"aws-ec2":                  ec2.Options,
		"aws-alb":                  alb.Options,
		"aws-ssm":                  ssm.Options,
		"aws-lambda":               lambda.Options,
		"vault":                    vault.Options,
		"terraform-cloud":          tfc.Options,
	}

	// BaseFactories is the set of base plugin factories. This will include any
	// built-in or well-known plugins by default. This should be used as the base
	// for building any set of factories.
	BaseFactories = map[component.Type]*factory.Factory{
		component.MapperType:         mustFactory(factory.New((*interface{})(nil))),
		component.BuilderType:        mustFactory(factory.New(component.TypeMap[component.BuilderType])),
		component.RegistryType:       mustFactory(factory.New(component.TypeMap[component.RegistryType])),
		component.PlatformType:       mustFactory(factory.New(component.TypeMap[component.PlatformType])),
		component.ReleaseManagerType: mustFactory(factory.New(component.TypeMap[component.ReleaseManagerType])),
		component.ConfigSourcerType:  mustFactory(factory.New(component.TypeMap[component.ConfigSourcerType])),
	}

	// ConfigSourcers are the list of built-in config sourcers. These will
	// eventually be moved out to exec-based plugins but for now we just
	// hardcode them. This is used by the CEB.
	ConfigSourcers = map[string]*Instance{
		"aws-ssm": {
			Component: &pluginAWSSSM.ConfigSourcer{},
		},
		"kubernetes": {
			Component: &k8s.ConfigSourcer{},
		},
		"vault": {
			Component: &pluginVault.ConfigSourcer{},
		},
		"terraform-cloud": {
			Component: &tfc.ConfigSourcer{},
		},
	}
)

Functions

func BuiltinFactory

func BuiltinFactory(name string, typ component.Type) interface{}

BuiltinFactory creates a factory for a built-in plugin type.

func CallDynamicFunc

func CallDynamicFunc(
	log hclog.Logger,
	f interface{},
	args ...argmapper.Arg,
) (*argmapper.Result, error)

CallDynamicFunc is a helper to call the dynamic functions that Waypoint plugins return, i.e. a `DeployFunc`.

The value f must be either a function pointer or an *argmapper.Func directly. The called function will always have access to the given logger and the logger will also be used by argmapper.

If f is nil then (nil, nil) is returned. This is for prior compatibility reasons so please always check the return value even if err is nil.

If error is nil, then the result is guaranteed to not be erroneous. Callers do NOT need to check result.Err().

func DefaultPaths

func DefaultPaths(pwd string) ([]string, error)

DefaultPaths returns the default search paths for plugins. These are:

• pwd given
• "$pwd/.waypoint/plugins"
• "$XDG_CONFIG_DIR/waypoint/plugins"

func Discover

func Discover(cfg *config.Plugin, paths []string) (*exec.Cmd, error)

Discover finds the given plugin and returns the command for it. The command can subsequently be used with Factory to build a factory for a specific plugin type. If the plugin is not found `(nil, nil)` is returned.

The plugin binary must have the form "waypoint-plugin-<name>" (with a ".exe" extension on Windows).

This will search the paths given. You can use DefaultPaths() to get the default set of paths.

func Factory

func Factory(cmd *exec.Cmd, typ component.Type) interface{}

Factory returns the factory function for a plugin that is already represented by an *exec.Cmd. This returns an *Instance and NOT the component interface value directly. This instance lets you more carefully manage the lifecycle of the plugin as well as get additional information about the plugin.

func ReattachPluginFactory

func ReattachPluginFactory(reattach *plugin.ReattachConfig, typ component.Type) interface{}

ReattachPluginFactory produces a provider factory that uses the passed reattach information to connect to go-plugin processes that are already running, and implements Instance against it.

Types

type Instance

type Instance struct {
	// Component is the dispensed component
	Component interface{}

	// Mappers is the list of mappers that this plugin is providing.
	Mappers []*argmapper.Func

	// Closer is a function that should be called to clean up resources
	// associated with this plugin.
	Close func()
}

Instance is the result generated by the factory. This lets us pack a bit more information into plugin-launched components.