plugins

package
v0.67.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2024 License: Apache-2.0 Imports: 26 Imported by: 92

Documentation

Overview

Package plugins implements plugin management for the policy engine.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConsoleLogger added in v0.29.0 

func ConsoleLogger(logger logging.Logger) func(*Manager)

ConsoleLogger sets the passed logger to be used by plugins that are configured with console logging enabled.

func EnablePrintStatements added in v0.34.0 

func EnablePrintStatements(yes bool) func(*Manager)

func GetCompilerOnContext added in v0.12.2 

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

GetCompilerOnContext gets the compiler cached on the storage context.

func GracefulShutdownPeriod added in v0.25.0 

func GracefulShutdownPeriod(gracefulShutdownPeriod int) func(*Manager)

GracefulShutdownPeriod passes the configured graceful shutdown period to plugins

func Info added in v0.10.2 

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 added in v0.20.0 

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

InitBundles provides the initial set of bundles to load.

func InitFiles added in v0.20.0 

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

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

func Logger added in v0.28.0 

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

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

func MaxErrors added in v0.20.0 

func MaxErrors(n int) func(*Manager)

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

func PrintHook added in v0.34.0 

func PrintHook(h print.Hook) func(*Manager)

func SetCompilerOnContext added in v0.12.2 

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 added in v0.25.0 

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.

func WithDistributedTracingOpts added in v0.54.0 

func WithDistributedTracingOpts(tr tracing.Options) func(*Manager)

WithDistributedTracingOpts sets the options to be used by distributed tracing.

func WithEnableTelemetry added in v0.60.0 

func WithEnableTelemetry(enableTelemetry bool) func(*Manager)

WithEnableTelemetry controls whether OPA will send telemetry reports to an external service.

func WithHooks added in v0.54.0 

func WithHooks(hs hooks.Hooks) func(*Manager)

WithHooks allows passing hooks to the plugin manager.

func WithParserOptions added in v0.61.0 

func WithParserOptions(opts ast.ParserOptions) func(*Manager)

WithParserOptions sets the parser options to be used by the plugin manager.

func WithPrometheusRegister added in v0.38.0 

func WithPrometheusRegister(prometheusRegister prometheus.Registerer) func(*Manager)

WithPrometheusRegister sets the passed prometheus.Registerer to be used by plugins

func WithRouter added in v0.36.0 

func WithRouter(r *mux.Router) func(*Manager)

func WithTelemetryGatherers added in v0.60.0 

func WithTelemetryGatherers(gs map[string]report.Gatherer) func(*Manager)

WithTelemetryGatherers allows registration of telemetry gatherers which enable injection of additional data in the telemetry report

func WithTracerProvider added in v0.46.0 

func WithTracerProvider(tracerProvider *trace.TracerProvider) func(*Manager)

WithTracerProvider sets the passed *trace.TracerProvider to be used by plugins

Types

type Factory added in v0.10.3 

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 added in v0.26.0 

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) ConsoleLogger added in v0.29.0 

func (m *Manager) ConsoleLogger() logging.Logger

ConsoleLogger gets the console logger for this plugin manager.

func (*Manager) EnablePrintStatements added in v0.34.0 

func (m *Manager) EnablePrintStatements() bool

func (*Manager) GetCompiler added in v0.8.1 

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

GetCompiler returns the manager's compiler.

func (*Manager) GetRouter added in v0.36.0 

func (m *Manager) GetRouter() *mux.Router

GetRouter returns the managers router if set

func (*Manager) GetWasmResolvers added in v0.25.0 

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

GetWasmResolvers returns the manager's set of Wasm Resolvers.

func (*Manager) Init added in v0.20.0 

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 added in v0.23.0 

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 added in v0.27.0 

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

Logger gets the standard logger for this plugin manager.

func (*Manager) ParserOptions added in v0.61.0 

func (m *Manager) ParserOptions() ast.ParserOptions

func (*Manager) Plugin added in v0.10.2 

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

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

func (*Manager) PluginStatus added in v0.17.0 

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

PluginStatus returns the current statuses of any plugins registered.

func (*Manager) Plugins added in v0.10.2 

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

Plugins returns the list of plugins registered with the manager.

func (*Manager) PrintHook added in v0.34.0 

func (m *Manager) PrintHook() print.Hook

func (*Manager) PrometheusRegister added in v0.38.0 

func (m *Manager) PrometheusRegister() prometheus.Registerer

PrometheusRegister gets the prometheus.Registerer for this plugin manager.

func (*Manager) PublicKeys added in v0.22.0 

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

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

func (*Manager) Reconfigure added in v0.10.2 

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 added in v0.26.0 

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 added in v0.8.1 

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

RegisterCompilerTrigger registers for change notifications when the compiler is changed.

func (*Manager) RegisterNDCacheTrigger added in v0.48.0 

func (m *Manager) RegisterNDCacheTrigger(trigger func(bool))

func (*Manager) RegisterPluginStatusListener added in v0.17.0 

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

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

func (*Manager) ServerInitialized added in v0.32.0 

func (m *Manager) ServerInitialized()

ServerInitialized signals a channel indicating that the OPA server has finished initialization.

func (*Manager) ServerInitializedChannel added in v0.32.0 

func (m *Manager) ServerInitializedChannel() <-chan struct{}

ServerInitializedChannel returns a receive-only channel that is closed when the OPA server has finished initialization. Be aware that the socket of the server listener may not be open by the time this channel is closed. There is a very small window where the socket may still be closed, due to a race condition.

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 added in v0.9.2 

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. Note that a graceful shutdown period configured with the Manager instance will override the timeout of the passed in context (if applicable).

func (*Manager) TracerProvider added in v0.46.0 

func (m *Manager) TracerProvider() *trace.TracerProvider

TracerProvider gets the *trace.TracerProvider for this plugin manager.

func (*Manager) UnregisterPluginStatusListener added in v0.17.0 

func (m *Manager) UnregisterPluginStatusListener(name string)

UnregisterPluginStatusListener removes a StatusListener registered with the same name.

func (*Manager) UpdatePluginStatus added in v0.17.0 

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 added in v0.17.0 

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 added in v0.17.0 

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

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

func (*Status) String added in v0.29.0 

func (s *Status) String() string

type StatusListener added in v0.17.0 

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

StatusListener defines a handler to register for status updates.

type TriggerMode added in v0.32.0 

type TriggerMode string

TriggerMode defines the trigger mode utilized by a Plugin for bundle download, log upload etc. 

const (
	// TriggerPeriodic represents periodic polling mechanism
	TriggerPeriodic TriggerMode = "periodic"

	// TriggerManual represents manual triggering mechanism
	TriggerManual TriggerMode = "manual"

	// DefaultTriggerMode represents default trigger mechanism
	DefaultTriggerMode TriggerMode = "periodic"
)

func ValidateAndInjectDefaultsForTriggerMode added in v0.33.0 

func ValidateAndInjectDefaultsForTriggerMode(a, b *TriggerMode) (*TriggerMode, error)

ValidateAndInjectDefaultsForTriggerMode validates the trigger mode and injects default values

type Triggerable added in v0.32.0 

type Triggerable interface {
	Trigger(context.Context) error
}

Triggerable defines the interface plugins use for manual plugin triggers.

Source Files

View all Source files

Directories

Path Synopsis
Package bundle implements bundle loading.
 Package bundle implements bundle loading.
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.
status
Package rest implements a REST client for communicating with remote services.
 Package rest implements a REST client for communicating with remote services.
server
decoding
Package decoding implements the configuration side of the upgraded gzip decompression framework.
 Package decoding implements the configuration side of the upgraded gzip decompression framework.
encoding
metrics
Package status implements status reporting.
 Package status implements status reporting.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.