package plugins

import "github.com/open-policy-agent/opa/plugins"

Package plugins implements plugin management for the policy engine.

Index ¶

• func GetCompilerOnContext(context *storage.Context) *ast.Compiler
• func Info(term *ast.Term) func(*Manager)
• func SetCompilerOnContext(context *storage.Context, compiler *ast.Compiler)
• type Factory
• type Manager
• func New(raw []byte, id string, store storage.Store, opts ...func(*Manager)) (*Manager, error)
• func (m *Manager) Client(name string) rest.Client
• func (m *Manager) GetCompiler() *ast.Compiler
• func (m *Manager) Labels() map[string]string
• func (m *Manager) Plugin(name string) Plugin
• func (m *Manager) PluginStatus() map[string]*Status
• func (m *Manager) Plugins() []string
• func (m *Manager) Reconfigure(config *config.Config) error
• func (m *Manager) Register(name string, plugin Plugin)
• func (m *Manager) RegisterCompilerTrigger(f func(txn storage.Transaction))
• func (m *Manager) RegisterPluginStatusListener(name string, listener StatusListener)
• func (m *Manager) Services() []string
• func (m *Manager) Start(ctx context.Context) error
• func (m *Manager) Stop(ctx context.Context)
• func (m *Manager) UnregisterPluginStatusListener(name string)
• func (m *Manager) UpdatePluginStatus(pluginName string, status *Status)
• type Plugin
• type State
• type Status
• type StatusListener

Functions ¶

func GetCompilerOnContext ¶

func GetCompilerOnContext(context *storage.Context) *ast.Compiler

GetCompilerOnContext gets the compiler cached on the storage context.

func Info ¶

func Info(term *ast.Term) func(*Manager)

Info sets the runtime information on the manager. The runtime information is propagated to opa.runtime() built-in function calls.

func SetCompilerOnContext ¶

func SetCompilerOnContext(context *storage.Context, compiler *ast.Compiler)

SetCompilerOnContext puts the compiler into the storage context. Calling this function before committing updated policies to storage allows the manager to skip parsing and compiling of modules. Instead, the manager will use the compiler that was stored on the context.

Types ¶

type Factory ¶

type Factory interface {
	Validate(manager *Manager, config []byte) (interface{}, error)
	New(manager *Manager, config interface{}) Plugin
}

Factory defines the interface OPA uses to instantiate your plugin.

When OPA processes it's configuration it looks for factories that have been registered by calling runtime.RegisterPlugin. Factories are registered to a name which is used to key into the configuration blob. If your plugin has not been configured, your factory will not be invoked.

plugins:
  my_plugin1:
    some_key: foo
  # my_plugin2:
  #   some_key2: bar

If OPA was started with the configuration above and received two calls to runtime.RegisterPlugins (one with NAME "my_plugin1" and one with NAME "my_plugin2"), it would only invoke the factory for for my_plugin1.

OPA instantiates and reconfigures plugins in two steps. First, OPA will call Validate to check the configuration. Assuming the configuration is valid, your factory should return a configuration value that can be used to construct your plugin. Second, OPA will call New to instantiate your plugin providing the configuration value returned from the Validate call.

Validate receives a slice of bytes representing plugin configuration and returns a configuration value that can be used to instantiate your plugin. The manager is provided to give access to the OPA's compiler, storage layer, and global configuration. Your Validate function will typically:

1. Deserialize the raw config bytes
2. Validate the deserialized config for semantic errors
3. Inject default values
4. Return a deserialized/parsed config

New receives a valid configuration for your plugin and returns a plugin object. Your New function will typically:

1. Cast the config value to it's own type
2. Instantiate a plugin object
3. Return the plugin object
4. Update status via `plugins.Manager#UpdatePluginStatus`

After a plugin has been created subsequent status updates can be send anytime the plugin enters a ready or error state.

type Manager ¶

type Manager struct {
	Store  storage.Store
	Config *config.Config
	Info   *ast.Term
	ID     string
	// contains filtered or unexported fields
}

Manager implements lifecycle management of plugins and gives plugins access to engine-wide components like storage.

func New ¶

func New(raw []byte, id string, store storage.Store, opts ...func(*Manager)) (*Manager, error)

New creates a new Manager using config.

func (*Manager) Client ¶

func (m *Manager) Client(name string) rest.Client

Client returns a client for communicating with a remote service.

func (*Manager) GetCompiler ¶

func (m *Manager) GetCompiler() *ast.Compiler

GetCompiler returns the manager's compiler.

func (*Manager) Labels ¶

func (m *Manager) Labels() map[string]string

Labels returns the set of labels from the configuration.

func (*Manager) Plugin ¶

func (m *Manager) Plugin(name string) Plugin

Plugin returns the plugin registered with name or nil if name is not found.

func (*Manager) PluginStatus ¶

func (m *Manager) PluginStatus() map[string]*Status

PluginStatus returns the current statuses of any plugins registered.

func (*Manager) Plugins ¶

func (m *Manager) Plugins() []string

Plugins returns the list of plugins registered with the manager.

func (*Manager) Reconfigure ¶

func (m *Manager) Reconfigure(config *config.Config) error

Reconfigure updates the configuration on the manager.

func (*Manager) Register ¶

func (m *Manager) Register(name string, plugin Plugin)

Register adds a plugin to the manager. When the manager is started, all of the plugins will be started.

func (*Manager) RegisterCompilerTrigger ¶

func (m *Manager) RegisterCompilerTrigger(f func(txn storage.Transaction))

RegisterCompilerTrigger registers for change notifications when the compiler is changed.

func (*Manager) RegisterPluginStatusListener ¶

func (m *Manager) RegisterPluginStatusListener(name string, listener StatusListener)

RegisterPluginStatusListener registers a StatusListener to be called when plugin status updates occur.

func (*Manager) Services ¶

func (m *Manager) Services() []string

Services returns a list of services that m can provide clients for.

func (*Manager) Start ¶

func (m *Manager) Start(ctx context.Context) error

Start starts the manager.

func (*Manager) Stop ¶

func (m *Manager) Stop(ctx context.Context)

Stop stops the manager, stopping all the plugins registered with it

func (*Manager) UnregisterPluginStatusListener ¶

func (m *Manager) UnregisterPluginStatusListener(name string)

UnregisterPluginStatusListener removes a StatusListener registered with the same name.

func (*Manager) UpdatePluginStatus ¶

func (m *Manager) UpdatePluginStatus(pluginName string, status *Status)

UpdatePluginStatus updates a named plugins status. Any registered listeners will be called with a copy of the new state of all plugins.

type Plugin ¶

type Plugin interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context)
	Reconfigure(ctx context.Context, config interface{})
}

Plugin defines the interface OPA uses to manage your plugin.

When OPA starts it will start all of the plugins it was configured to instantiate. Each time a new plugin is configured (via discovery), OPA will start it. You can use the Start call to spawn additional goroutines or perform initialization tasks.

Currently OPA will not call Stop on plugins.

When OPA receives new configuration for your plugin via discovery it will first Validate the configuration using your factory and then call Reconfigure.

type State ¶

type State string

State defines the state that a Plugin instance is currently in with pre-defined states.

const (
	// StateNotReady indicates that the Plugin is not in an error state, but isn't
	// ready for normal operation yet. This should only happen at
	// initialization time.
	StateNotReady State = "NOT_READY"

	// StateOK signifies that the Plugin is operating normally.
	StateOK State = "OK"

	// StateErr indicates that the Plugin is in an error state and should not
	// be considered as functional.
	StateErr State = "ERROR"
)

type Status ¶

type Status struct {
	State State `json:"state"`
}

Status has a Plugin's current status plus an optional Message.

type StatusListener ¶

type StatusListener func(status map[string]*Status)

StatusListener defines a handler to register for status updates.

Source Files ¶

plugins.go

Directories ¶