catalog

Documentation

Index

• func Load(ctx context.Context, config Config, cat Catalog) (_ io.Closer, err error)
• func PluginNameFromHostServiceContext(ctx context.Context) (string, bool)
• func WithPluginName(ctx context.Context, name string) context.Context
• type BuiltIn
  • func MakeBuiltIn(name string, pluginServer pluginsdk.PluginServer, ...) BuiltIn
• type BuiltInConfig
• type Catalog
• type Config
• type Configurer
• type Constraints
  • func AtLeastOne() Constraints
  • func ExactlyOne() Constraints
  • func MaybeOne() Constraints
  • func ZeroOrMore() Constraints
  • func (c Constraints) Check(count int) error
• type CoreConfig
• type Facade
• type HCLPluginConfig
  • func (c HCLPluginConfig) IsEnabled() bool
• type HCLPluginConfigMap
• type HostServiceServer
• type Plugin
  • func LoadBuiltIn(ctx context.Context, builtIn BuiltIn, config BuiltInConfig) (_ Plugin, err error)
• type PluginConfig
  • func ParsePluginConfigsFromHCL(config string) ([]PluginConfig, error)
  • func PluginConfigFromHCL(pluginType, pluginName string, hclPluginConfig HCLPluginConfig) (PluginConfig, error)
  • func PluginConfigsFromHCL(hclPlugins HCLPluginConfigMap) ([]PluginConfig, error)
  • func (c *PluginConfig) IsExternal() bool
• type PluginInfo
• type PluginRepo
• type ServiceRepo
• type Version

Functions

func Load

func Load(ctx context.Context, config Config, cat Catalog) (_ io.Closer, err error)

Load loads and configures plugins defined in the configuration. The given catalog is populated with plugin and service facades for versions implemented by the loaded plugins. The returned io.Closer can be used to close down the loaded plugins, at which point, all facades bound to the given catalog are considered invalidated. If any plugin fails to load or configure, all plugins are unloaded, the catalog is cleared, and the function returns an error.

func PluginNameFromHostServiceContext

func PluginNameFromHostServiceContext(ctx context.Context) (string, bool)

func WithPluginName

func WithPluginName(ctx context.Context, name string) context.Context

Types

type BuiltIn

type BuiltIn struct {
	Name     string
	Plugin   pluginsdk.PluginServer
	Services []pluginsdk.ServiceServer
}

func MakeBuiltIn

func MakeBuiltIn(name string, pluginServer pluginsdk.PluginServer, serviceServers ...pluginsdk.ServiceServer) BuiltIn

type BuiltInConfig

type BuiltInConfig struct {
	// Log is the logger to be wired to the external plugin.
	Log logrus.FieldLogger

	// HostServices are the host service servers provided to the plugin.
	HostServices []pluginsdk.ServiceServer
}

type Catalog

type Catalog interface {
	// Plugins returns a map of plugin repositories, keyed by the plugin type.
	Plugins() map[string]PluginRepo

	// Services returns service repositories.
	Services() []ServiceRepo
}

Catalog is a set of plugin and service repositories.

type Config

type Config struct {
	// Log is the logger. It is used for general purpose logging and also
	// provided to the plugins.
	Log logrus.FieldLogger

	// PluginConfigs is the list of plugin configurations.
	PluginConfigs []PluginConfig

	// HostServices are the servers for host services provided by SPIRE to
	// plugins.
	HostServices []HostServiceServer

	// CoreConfig is the core configuration provided to each plugin.
	CoreConfig CoreConfig
}

type Configurer

type Configurer interface {
	Configure(ctx context.Context, coreConfig CoreConfig, configuration string) error
}

type Constraints

type Constraints struct {
	// Min is the minimum number of plugins required of a specific type. If
	// zero, there is no lower bound (i.e. the plugin type is optional).
	Min int

	// Max is the the maximum number of plugins required of a specific type. If
	// zero, there is no upper bound.
	Max int
}

func AtLeastOne

func AtLeastOne() Constraints

func ExactlyOne

func ExactlyOne() Constraints

func MaybeOne

func MaybeOne() Constraints

func ZeroOrMore

func ZeroOrMore() Constraints

func (Constraints) Check

func (c Constraints) Check(count int) error

type CoreConfig

type CoreConfig struct {
	TrustDomain spiffeid.TrustDomain
}

type Facade

type Facade interface {
	// ServiceClient is used to initialize the service client with the
	// connection to the plugin providing the service server.
	pluginsdk.ServiceClient

	// InitInfo is used to initialize the facade with information for the
	// loaded plugin providing the service server.
	InitInfo(info PluginInfo)

	// InitLog initializes the facade with the logger for the loaded plugin
	// that provides the service server.
	InitLog(log logrus.FieldLogger)
}

Facade is a facade for a specific plugin or service version.

type HCLPluginConfig

type HCLPluginConfig struct {
	PluginCmd      string   `hcl:"plugin_cmd"`
	PluginArgs     []string `hcl:"plugin_args"`
	PluginChecksum string   `hcl:"plugin_checksum"`
	PluginData     ast.Node `hcl:"plugin_data"`
	Enabled        *bool    `hcl:"enabled"`
}

HCLPluginConfig serves as an intermediary struct. We pass this to the HCL library for parsing, except the parser won't parse pluginData as a string.

func (HCLPluginConfig) IsEnabled

func (c HCLPluginConfig) IsEnabled() bool

type HCLPluginConfigMap

type HCLPluginConfigMap map[string]map[string]HCLPluginConfig

type HostServiceServer

type HostServiceServer struct {
	// ServiceServer is the service server for the host service.
	ServiceServer pluginsdk.ServiceServer

	// LegacyType is the legacy type for the host service used to initialize
	// legacy plugins. This is optional for new host services that did not
	// existing before the plugin SDK was introduced.
	LegacyType string
}

type Plugin

type Plugin interface {
	// Closer is used to unload the plugin. Any facades initialized by the
	// call to bind are considered invalidated after the plugin is closed.
	io.Closer

	// Bind binds the given facades to the plugin. It also returns a Configurer
	// that can be used to configure the plugin. If the plugin does not support
	// a given facade, an error will be returned. This function is designed
	// only for use by unit-tests for built-in plugin implementations or fake
	// facade implementations that rely on built-ins.
	Bind(facades ...Facade) (Configurer, error)
}

Plugin is a loaded plugin.

func LoadBuiltIn

func LoadBuiltIn(ctx context.Context, builtIn BuiltIn, config BuiltInConfig) (_ Plugin, err error)

type PluginConfig

type PluginConfig struct {
	Name     string
	Type     string
	Path     string
	Args     []string
	Checksum string
	Data     string
	Disabled bool
}

func ParsePluginConfigsFromHCL

func ParsePluginConfigsFromHCL(config string) ([]PluginConfig, error)

func PluginConfigFromHCL

func PluginConfigFromHCL(pluginType, pluginName string, hclPluginConfig HCLPluginConfig) (PluginConfig, error)

func PluginConfigsFromHCL

func PluginConfigsFromHCL(hclPlugins HCLPluginConfigMap) ([]PluginConfig, error)

func (*PluginConfig) IsExternal

func (c *PluginConfig) IsExternal() bool

type PluginInfo

type PluginInfo interface {
	// The name of the plugin (e.g. "aws_iid").
	Name() string

	// The type of the plugin (e.g. KeyManager).
	Type() string
}

PluginInfo provides the information for the loaded plugin.

type PluginRepo

type PluginRepo interface {
	ServiceRepo

	// Constraints returns the constraints required by the plugin repository.
	// The Load funcion will ensure that these constraints are satisfied before
	// returning successfully.
	Constraints() Constraints

	// LegacyVersion is called when the catalog detects a legacy plugin to
	// obtain the legacy plugin version. If no legacy version exists for this
	// plugin, this function returns false, which causes the Load() function to
	// fail.
	LegacyVersion() (Version, bool)

	// BuiltIns provides the list of built ins that are available for the
	// given plugin repository.
	BuiltIns() []BuiltIn
}

PluginRepo is a repository of plugin facades for a given plugin type.

type ServiceRepo

type ServiceRepo interface {
	// Binder returns a function that is used by the catalog system to "bind"
	// the facade returned by selected version to the repository. It MUST
	// return void and take a single argument of type X, where X can be
	// assigned to by any of the facade implementation types returned by the
	// provided versions (see Versions).
	Binder() interface{}

	// Versions returns the versions supported by the repository, ordered by
	// most to least preferred. The first version supported by the plugin will
	// be used. When a deprecated version is bound, warning messaging will
	// recommend the first version in the list as a replacement, unless it is
	// also deprecated.
	Versions() []Version

	// Clear is called when loading fails to clear the repository of any
	// previously bound facades.
	Clear()
}

ServiceRepo is a repository for service facades for a given service.

type Version

type Version interface {
	// New returns a new facade for this version. Instantiated facades are only
	// bound via the repo binder when they match a gRPC service name provided
	// by the plugin.
	New() Facade

	// Deprecated returns whether or not the version is deprecated.
	Deprecated() bool
}

Version represents a plugin or service version. It is used to instantiate facades for the versions that are bound to the plugin or service repositories (see the Binder method on the ServiceRepo).