plugins

Documentation

Index

• Constants
• Variables
• func FlagToEnvName(flagName, prefix string) string
• type Description
• type DirectoryPluginLoader
  • func (l *DirectoryPluginLoader) Load() (Plugins, error)
• type DummyPluginLoader
  • func (l *DummyPluginLoader) Load() (Plugins, error)
• type EmptyEnvProvider
  • func (p *EmptyEnvProvider) Env() (EnvList, error)
• type Env
  • func FlagToEnv(flag *pflag.Flag, prefix string) Env
  • func (e Env) String() string
• type EnvList
  • func (e EnvList) Merge(s ...string) EnvList
  • func (e EnvList) Slice() []string
• type EnvProvider
• type ExecPluginRunner
  • func (r *ExecPluginRunner) Run(plugin *Plugin, ctx RunningContext) error
• type Flag
  • func (f Flag) Shorthanded() bool
  • func (f Flag) Validate() error
  • func (f Flag) ValidateShorthand() error
• type MultiEnvProvider
  • func (p MultiEnvProvider) Env() (EnvList, error)
• type MultiPluginLoader
  • func (l MultiPluginLoader) Load() (Plugins, error)
• type OSEnvProvider
  • func (p *OSEnvProvider) Env() (EnvList, error)
• type Plugin
  • func (p Plugin) IsValid() bool
  • func (p Plugin) Validate() error
• type PluginCallerEnvProvider
  • func (p *PluginCallerEnvProvider) Env() (EnvList, error)
• type PluginDescriptorEnvProvider
  • func (p *PluginDescriptorEnvProvider) Env() (EnvList, error)
• type PluginLoader
  • func KubectlPluginsPathPluginLoader() PluginLoader
  • func PathFromEnvVarPluginLoader(envVarName string, subdirs ...string) PluginLoader
  • func UserDirPluginLoader() PluginLoader
  • func XDGDataDirsPluginLoader() PluginLoader
• type PluginRunner
• type Plugins
• type RunningContext
• type Source
• type TolerantMultiPluginLoader
  • func (l TolerantMultiPluginLoader) Load() (Plugins, error)

Constants

const PluginDescriptorFilename = "plugin.yaml"

PluginDescriptorFilename is the default file name for plugin descriptions.

Variables

var (
	// ErrIncompletePlugin indicates plugin is incomplete.
	ErrIncompletePlugin = fmt.Errorf("incomplete plugin descriptor: name, shortDesc and command fields are required")
	// ErrInvalidPluginName indicates plugin name is invalid.
	ErrInvalidPluginName = fmt.Errorf("plugin name can't contain spaces")
	// ErrIncompleteFlag indicates flag is incomplete.
	ErrIncompleteFlag = fmt.Errorf("incomplete flag descriptor: name and desc fields are required")
	// ErrInvalidFlagName indicates flag name is invalid.
	ErrInvalidFlagName = fmt.Errorf("flag name can't contain spaces")
	// ErrInvalidFlagShorthand indicates flag shorthand is invalid.
	ErrInvalidFlagShorthand = fmt.Errorf("flag shorthand must be only one letter")
)

Functions

func FlagToEnvName

func FlagToEnvName(flagName, prefix string) string

FlagToEnvName converts a flag string into a UNIX like environment variable name.

e.g --some-flag => "PREFIX_SOME_FLAG"

Types

type Description

type Description struct {
	Name      string  `json:"name"`
	ShortDesc string  `json:"shortDesc"`
	LongDesc  string  `json:"longDesc,omitempty"`
	Example   string  `json:"example,omitempty"`
	Command   string  `json:"command"`
	Flags     []Flag  `json:"flags,omitempty"`
	Tree      Plugins `json:"tree,omitempty"`
}

Description holds everything needed to register a plugin as a command. Usually comes from a descriptor file.

type DirectoryPluginLoader

type DirectoryPluginLoader struct {
	Directory string
}

DirectoryPluginLoader is a PluginLoader that loads plugin descriptions from a given directory in the filesystem. Plugins are located in subdirs under the loader "root", where each subdir must contain, at least, a plugin descriptor file called "plugin.yaml" that translates into a PluginDescription.

func (*DirectoryPluginLoader) Load

func (l *DirectoryPluginLoader) Load() (Plugins, error)

Load reads the directory the loader holds and loads plugin descriptions.

type DummyPluginLoader

type DummyPluginLoader struct{}

DummyPluginLoader is a noop PluginLoader.

func (*DummyPluginLoader) Load

func (l *DummyPluginLoader) Load() (Plugins, error)

Load loads nothing.

type EmptyEnvProvider

type EmptyEnvProvider struct{}

EmptyEnvProvider satisfies the EnvProvider interface.

func (*EmptyEnvProvider) Env

func (p *EmptyEnvProvider) Env() (EnvList, error)

Env returns an empty environment.

type Env

type Env struct {
	N string
	V string
}

Env represents an environment variable with its name and value.

func FlagToEnv

func FlagToEnv(flag *pflag.Flag, prefix string) Env

FlagToEnv converts a flag and its value into an Env.

e.g --some-flag some-value => Env{N: "PREFIX_SOME_FLAG", V="SOME_VALUE"}

func (Env) String

func (e Env) String() string

String returns "name=value" string.

type EnvList

type EnvList []Env

EnvList is a list of Env.

func (EnvList) Merge

func (e EnvList) Merge(s ...string) EnvList

Merge converts "name=value" strings into Env values and merges them into e.

func (EnvList) Slice

func (e EnvList) Slice() []string

Slice returns a slice of "name=value" strings.

type EnvProvider

type EnvProvider interface {
	// Env returns the env list.
	Env() (EnvList, error)
}

EnvProvider provides the environment in which the plugin will run.

type ExecPluginRunner

type ExecPluginRunner struct{}

ExecPluginRunner is a PluginRunner that uses Go's os/exec to run plugins.

func (*ExecPluginRunner) Run

func (r *ExecPluginRunner) Run(plugin *Plugin, ctx RunningContext) error

Run takes a given plugin and runs it in a given context using os/exec, returning any error found while running.

type Flag

type Flag struct {
	Name      string `json:"name"`
	Shorthand string `json:"shorthand,omitempty"`
	Desc      string `json:"desc"`
	DefValue  string `json:"defValue,omitempty"`
}

Flag describes a single flag supported by a given plugin.

func (Flag) Shorthanded

func (f Flag) Shorthanded() bool

Shorthanded returns true if flag shorthand data is valid.

func (Flag) Validate

func (f Flag) Validate() error

Validate validates flag data.

func (Flag) ValidateShorthand

func (f Flag) ValidateShorthand() error

ValidateShorthand validates flag shorthand data.

type MultiEnvProvider

type MultiEnvProvider []EnvProvider

MultiEnvProvider satisfies the EnvProvider interface for multiple env providers.

func (MultiEnvProvider) Env

func (p MultiEnvProvider) Env() (EnvList, error)

Env returns the combined env list of multiple env providers, returns on first error.

type MultiPluginLoader

type MultiPluginLoader []PluginLoader

MultiPluginLoader is a PluginLoader that can encapsulate multiple plugin loaders, a successful loading means every encapsulated loader was able to load without errors.

func (MultiPluginLoader) Load

func (l MultiPluginLoader) Load() (Plugins, error)

Load calls Load() for each of the encapsulated Loaders.

type OSEnvProvider

type OSEnvProvider struct{}

OSEnvProvider satisfies the EnvProvider interface.

func (*OSEnvProvider) Env

func (p *OSEnvProvider) Env() (EnvList, error)

Env returns the current environment from the operating system.

type Plugin

type Plugin struct {
	Description
	Source
	Context RunningContext `json:"-"`
}

Plugin is the representation of a CLI extension (plugin).

func (Plugin) IsValid

func (p Plugin) IsValid() bool

IsValid returns true if plugin data is valid.

func (Plugin) Validate

func (p Plugin) Validate() error

Validate validates plugin data.

type PluginCallerEnvProvider

type PluginCallerEnvProvider struct{}

PluginCallerEnvProvider satisfies the EnvProvider interface.

func (*PluginCallerEnvProvider) Env

func (p *PluginCallerEnvProvider) Env() (EnvList, error)

Env returns env with the path to the caller binary (usually full path to 'kubectl').

type PluginDescriptorEnvProvider

type PluginDescriptorEnvProvider struct {
	Plugin *Plugin
}

PluginDescriptorEnvProvider satisfies the EnvProvider interface.

func (*PluginDescriptorEnvProvider) Env

func (p *PluginDescriptorEnvProvider) Env() (EnvList, error)

Env returns env with information about the running plugin.

type PluginLoader

type PluginLoader interface {
	// Load loads the plugin descriptions.
	Load() (Plugins, error)
}

PluginLoader is capable of loading a list of plugin descriptions.

func KubectlPluginsPathPluginLoader

func KubectlPluginsPathPluginLoader() PluginLoader

KubectlPluginsPathPluginLoader returns a PluginLoader that loads plugins from one or more directories specified by the KUBECTL_PLUGINS_PATH env var.

func PathFromEnvVarPluginLoader

func PathFromEnvVarPluginLoader(envVarName string, subdirs ...string) PluginLoader

PathFromEnvVarPluginLoader returns a PluginLoader that loads plugins from one or more directories specified by the provided env var name. In case the env var is not set, the PluginLoader just loads nothing. A list of subdirectories can be provided, which will be appended to each path specified by the env var.

func UserDirPluginLoader

func UserDirPluginLoader() PluginLoader

UserDirPluginLoader returns a PluginLoader that loads plugins from the "plugins" directory under the user's kubeconfig dir (usually "~/.kube/plugins/").

func XDGDataDirsPluginLoader

func XDGDataDirsPluginLoader() PluginLoader

XDGDataDirsPluginLoader returns a PluginLoader that loads plugins from one or more directories specified by the XDG system directory structure spec in the XDG_DATA_DIRS env var, plus the "kubectl/plugins/" suffix. According to the spec, if XDG_DATA_DIRS is not set it defaults to "/usr/local/share:/usr/share".

type PluginRunner

type PluginRunner interface {
	Run(plugin *Plugin, ctx RunningContext) error
}

PluginRunner is capable of running a plugin in a given running context.

type Plugins

type Plugins []*Plugin

Plugins is a list of plugins.

type RunningContext

type RunningContext struct {
	In          io.Reader
	Out         io.Writer
	ErrOut      io.Writer
	Args        []string
	EnvProvider EnvProvider
	WorkingDir  string
}

RunningContext holds the context in which a given plugin is running - the in, out, and err streams, arguments and environment passed to it, and the working directory.

type Source

type Source struct {
	Dir            string `json:"-"`
	DescriptorName string `json:"-"`
}

Source holds the location of a given plugin in the filesystem.

type TolerantMultiPluginLoader

type TolerantMultiPluginLoader []PluginLoader

TolerantMultiPluginLoader is a PluginLoader than encapsulates multiple plugins loaders, but is tolerant to errors while loading from them.

func (TolerantMultiPluginLoader) Load

func (l TolerantMultiPluginLoader) Load() (Plugins, error)

Load calls Load() for each of the encapsulated Loaders.