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 PathFromEnvVarPluginLoader(envVarName string, subdirs ...string) PluginLoader
  • func PluginsEnvVarPluginLoader() PluginLoader
  • func UserDirPluginLoader() PluginLoader
  • func XDGDataPluginLoader() PluginLoader
• type PluginRunner
• type Plugins
• type RunningContext
• type Source
• type TolerantMultiPluginLoader
  • func (l TolerantMultiPluginLoader) Load() (Plugins, error)

Constants

const PluginDescriptorFilename = "plugin.yaml"

Variables

var (
	IncompletePluginError     = fmt.Errorf("incomplete plugin descriptor: name, shortDesc and command fields are required")
	InvalidPluginNameError    = fmt.Errorf("plugin name can't contain spaces")
	IncompleteFlagError       = fmt.Errorf("incomplete flag descriptor: name and desc fields are required")
	InvalidFlagNameError      = fmt.Errorf("flag name can't contain spaces")
	InvalidFlagShorthandError = fmt.Errorf("flag shorthand must be only one letter")
)

Functions

func FlagToEnvName

func FlagToEnvName(flagName, prefix string) string

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"`
}

PluginDescription 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 loads nothing.

func (*DummyPluginLoader) Load

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

type EmptyEnvProvider

type EmptyEnvProvider struct{}

func (*EmptyEnvProvider) Env

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

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

func (Env) String

func (e Env) String() string

type EnvList

type EnvList []Env

EnvList is a list of Env

func (EnvList) Merge

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

func (EnvList) Slice

func (e EnvList) Slice() []string

type EnvProvider

type EnvProvider interface {
	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

func (Flag) Validate

func (f Flag) Validate() error

func (Flag) ValidateShorthand

func (f Flag) ValidateShorthand() error

type MultiEnvProvider

type MultiEnvProvider []EnvProvider

MultiEnvProvider is an EnvProvider for multiple env providers, returns on first error.

func (MultiEnvProvider) Env

func (p MultiEnvProvider) Env() (EnvList, 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)

type OSEnvProvider

type OSEnvProvider struct{}

OSEnvProvider provides current environment from the operating system.

func (*OSEnvProvider) Env

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

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

func (Plugin) Validate

func (p Plugin) Validate() error

type PluginCallerEnvProvider

type PluginCallerEnvProvider struct{}

PluginCallerEnvProvider provides env with the path to the caller binary (usually full path to 'kubectl').

func (*PluginCallerEnvProvider) Env

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

type PluginDescriptorEnvProvider

type PluginDescriptorEnvProvider struct {
	Plugin *Plugin
}

PluginDescriptorEnvProvider provides env vars with information about the running plugin.

func (*PluginDescriptorEnvProvider) Env

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

type PluginLoader

type PluginLoader interface {
	Load() (Plugins, error)
}

PluginLoader is capable of loading a list of plugin descriptions.

func PathFromEnvVarPluginLoader

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

PathFromEnvVarPluginLoader is 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 PluginsEnvVarPluginLoader

func PluginsEnvVarPluginLoader() PluginLoader

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

func UserDirPluginLoader

func UserDirPluginLoader() PluginLoader

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

func XDGDataPluginLoader

func XDGDataPluginLoader() PluginLoader

XDGDataPluginLoader is 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:"-"`
}

PluginSource 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)