Documentation

Overview

    Package plugins implements plugin management for the policy engine.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func GetCompilerOnContext

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

      GetCompilerOnContext gets the compiler cached on the storage context.

      func GetConsoleLogger

      func GetConsoleLogger() *logrus.Logger

        GetConsoleLogger return plugin console logger

        func GracefulShutdownPeriod

        func GracefulShutdownPeriod(gracefulShutdownPeriod int) func(*Manager)

          GracefulShutdownPeriod passes the configured graceful shutdown period to plugins

          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 InitBundles

            func InitBundles(b map[string]*bundle.Bundle) func(*Manager)

              InitBundles provides the initial set of bundles to load.

              func InitFiles

              func InitFiles(f loader.Result) func(*Manager)

                InitFiles provides the initial set of other data/policy files to load.

                func Logger

                func Logger(logger sdk.Logger) func(*Manager)

                  Logger configures the passed logger on the plugin manager (useful to configure default fields)

                  func MaxErrors

                  func MaxErrors(n int) func(*Manager)

                    MaxErrors sets the error limit for the manager's shared compiler.

                    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.

                      func SetWasmResolversOnContext

                      func SetWasmResolversOnContext(context *storage.Context, rs []*wasm.Resolver)

                        SetWasmResolversOnContext puts a set of Wasm Resolvers into the storage context. Calling this function before committing updated wasm modules to storage allows the manager to skip initializing modules before using them. 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) AuthPlugin

                              func (m *Manager) AuthPlugin(name string) rest.HTTPAuthPlugin

                                AuthPlugin returns the HTTPAuthPlugin registered with name or nil if name is not found.

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

                                    func (m *Manager) GetWasmResolvers() []*wasm.Resolver

                                      GetWasmResolvers returns the manager's set of Wasm Resolvers.

                                      func (*Manager) Init

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

                                        Init returns an error if the manager could not initialize itself. Init() should be called before Start(). Init() is idempotent.

                                        func (*Manager) InterQueryBuiltinCacheConfig

                                        func (m *Manager) InterQueryBuiltinCacheConfig() *cache.Config

                                          InterQueryBuiltinCacheConfig returns the configuration for the inter-query cache.

                                          func (*Manager) Labels

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

                                            Labels returns the set of labels from the configuration.

                                            func (*Manager) Logger

                                            func (m *Manager) Logger() sdk.Logger

                                              Logger gets the logger implementation associated with this plugin manager

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

                                                    func (m *Manager) PublicKeys() map[string]*keys.Config

                                                      PublicKeys returns a public keys that can be used for verifying signed bundles.

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

                                                          func (m *Manager) RegisterCacheTrigger(trigger func(*cache.Config))

                                                            RegisterCacheTrigger accepts a func that receives new inter-query cache config generated by a reconfigure of the plugin manager, so that it can be propagated to existing inter-query caches.

                                                            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. Init() should be called once before Start().

                                                                    func (*Manager) Stop

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

                                                                      Stop stops the manager, stopping all the plugins registered with it. Any plugin that needs to perform cleanup should do so within the duration of the graceful shutdown period passed with the context as a timeout.

                                                                      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"
                                                                              
                                                                              	// StateWarn indicates the Plugin is operating, but in a potentially dangerous or
                                                                              	// degraded state. It may be used to indicate manual remediation is needed, or to
                                                                              	// alert admins of some other noteworthy state.
                                                                              	StateWarn State = "WARN"
                                                                              )

                                                                              type Status

                                                                              type Status struct {
                                                                              	State   State  `json:"state"`
                                                                              	Message string `json:"message,omitempty"`
                                                                              }

                                                                                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

                                                                                  Directories

                                                                                  Path Synopsis
                                                                                  Package bundle implements bundle downloading.
                                                                                  Package bundle implements bundle downloading.
                                                                                  Package discovery implements configuration discovery.
                                                                                  Package discovery implements configuration discovery.
                                                                                  Package logs implements decision log buffering and uploading.
                                                                                  Package logs implements decision log buffering and uploading.
                                                                                  Package rest implements a REST client for communicating with remote services.
                                                                                  Package rest implements a REST client for communicating with remote services.
                                                                                  Package status implements status reporting.
                                                                                  Package status implements status reporting.