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 ArgNamedAny(n string, v *opaqueany.Any) argmapper.Arg
• 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, paths []string) (*exec.Cmd, error)
• func Factory(cmd *exec.Cmd, typ component.Type) interface{}
• func ParseReattachPlugins(in string) (map[string]*goplugin.ReattachConfig, error)
• func ReattachPluginFactory(reattach *plugin.ReattachConfig, typ component.Type) interface{}
• type Config
• type Instance
• type Plugin
  • func Open(ctx context.Context, log hclog.Logger, req *PluginRequest) (*Plugin, interface{}, error)
  • func (p *Plugin) Close() error
  • func (p *Plugin) Invoke(ctx context.Context, log hclog.Logger, fn interface{}, args ...interface{}) (interface{}, error)
• type PluginRequest

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,
		"helm":                     k8shelm.Options,
		"aws-ecs":                  ecs.Options,
		"aws-ecr":                  ecr.Options,
		"aws-ecr-pull":             awsecrpull.Options,
		"nomad":                    nomad.Options,
		"nomad-jobspec":            jobspec.Options,
		"nomad-jobspec-canary":     jobspec.Options,
		"aws-ami":                  ami.Options,
		"aws-ec2":                  ec2.Options,
		"aws-alb":                  alb.Options,
		"aws-ssm":                  ssm.Options,
		"aws-lambda":               lambda.Options,
		"lambda-function-url":      lambdaFunctionUrl.Options,
		"vault":                    vault.Options,
		"terraform-cloud":          tfc.Options,
		"null":                     null.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])),
		component.TaskLauncherType:   mustFactory(factory.New(component.TypeMap[component.TaskLauncherType])),
	}

	// 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: &ssm.ConfigSourcer{},
		},
		"kubernetes": {
			Component: &k8s.ConfigSourcer{},
		},
		"null": {
			Component: &null.ConfigSourcer{},
		},
		"vault": {
			Component: &vault.ConfigSourcer{},
		},
		"terraform-cloud": {
			Component: &tfc.ConfigSourcer{},
		},
	}
)

var InsideODR bool

Indicates that the process is running inside an ondemand runner. This information is passed to the plugins so they can configure themselves specially for this unique context.

Functions

func ArgNamedAny

func ArgNamedAny(n string, v *opaqueany.Any) argmapper.Arg

ArgNamedAny returns an argmapper.Arg that specifies the Any value with the proper subtype.

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, 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 ParseReattachPlugins

func ParseReattachPlugins(in string) (map[string]*goplugin.ReattachConfig, error)

ParseReattachPlugins parses information on reattaching to plugins out of a JSON-encoded environment variable. Example input: WP_REATTACH_PLUGINS='{"pack":{"Protocol":"grpc","ProtocolVersion":1,"Pid":24025,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/ns/grk8kk196_106v37w9hk8hxm0000gq/T/plugin047564716"}}}'

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 Config

type Config struct {
	// Name of the plugin. This is expected to match the plugin binary
	// "waypoint-plugin-<name>" including casing.
	Name string

	// Checksum is the SHA256 checksum to validate this plugin.
	// If set, the binary will be validated against this checksum.
	Checksum string
}

Config contains the information about a plugin's loading information.

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.

type Plugin

type Plugin struct {
	Instance *Instance
	// contains filtered or unexported fields
}

Plugin is the state of a created plugin to be invoked, returned by Open.

func Open

func Open(
	ctx context.Context, log hclog.Logger, req *PluginRequest,
) (*Plugin, interface{}, error)

Open resolves the plugin information in req and returns a Plugin value to have Invoke called upon it. Open also returns the raw component interface, which is used to get the function value that will be invoked

func (*Plugin) Close

func (p *Plugin) Close() error

Close must be called to cleanup the plugin process when it is no longer needed.

func (*Plugin) Invoke

func (p *Plugin) Invoke(
	ctx context.Context, log hclog.Logger, fn interface{}, args ...interface{},
) (interface{}, error)

Invoke calls the given fn interface{} value as an argmapper function. The additional args are passed to the function on invocation. The fn value is obtained by casting the component returned by OpenPlugin to a component interface (ie component.TaskLauncher) and then one of the *Func() functions is called on the specific type.

type PluginRequest

type PluginRequest struct {
	// Config contains the information about the plugin itself. This will
	// be used to locate the plugin so it can be started.
	Config

	// The different components
	Type component.Type
	Name string

	Dir string

	ConfigData []byte
	JsonConfig bool
}

PluginRequest describes a plugin that should be setup to have its functions invoked. Config is used to identify the plugin by name, and Type is used to identify which one of the plugin types should be addressed within the plugin process.