plugins

Documentation

Overview

Deprecated: This package is intended for older projects transitioning from OPA v0.x and will remain for the lifetime of OPA v1.x, but its use is not recommended. For newer features and behaviours, such as defaulting to the Rego v1 syntax, use the corresponding components in the github.com/open-policy-agent/opa/v1 package instead. See https://www.openpolicyagent.org/docs/latest/v0-compatibility/ for more information.

Package plugins implements plugin management for the policy engine.

Index

• Constants
• func ConsoleLogger(logger logging.Logger) func(*Manager)
• func EnablePrintStatements(yes bool) func(*Manager)
• func GetCompilerOnContext(context *storage.Context) *ast.Compiler
• func GracefulShutdownPeriod(gracefulShutdownPeriod int) func(*Manager)
• func Info(term *ast.Term) func(*Manager)
• func InitBundles(b map[string]*bundle.Bundle) func(*Manager)
• func InitFiles(f loader.Result) func(*Manager)
• func Logger(logger logging.Logger) func(*Manager)
• func MaxErrors(n int) func(*Manager)
• func PrintHook(h print.Hook) func(*Manager)
• func SetCompilerOnContext(context *storage.Context, compiler *ast.Compiler)
• func SetWasmResolversOnContext(context *storage.Context, rs []*wasm.Resolver)
• func WithDistributedTracingOpts(tr tracing.Options) func(*Manager)
• func WithEnableTelemetry(enableTelemetry bool) func(*Manager)
• func WithHooks(hs hooks.Hooks) func(*Manager)
• func WithParserOptions(opts ast.ParserOptions) func(*Manager)
• func WithPrometheusRegister(prometheusRegister prometheus.Registerer) func(*Manager)
• func WithRouter(r *mux.Router) func(*Manager)
• func WithTelemetryGatherers(gs map[string]report.Gatherer) func(*Manager)
• func WithTracerProvider(tracerProvider *trace.TracerProvider) func(*Manager)
• type Factory
• type Manager
  • func New(raw []byte, id string, store storage.Store, opts ...func(*Manager)) (*Manager, error)
• type Plugin
• type State
• type Status
• type StatusListener
• type TriggerMode
  • func ValidateAndInjectDefaultsForTriggerMode(a, b *TriggerMode) (*TriggerMode, error)
• type Triggerable

Constants

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 = v1.StateNotReady

	// StateOK signifies that the Plugin is operating normally.
	StateOK = v1.StateOK

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

	// 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 = v1.StateWarn
)

const (
	// TriggerPeriodic represents periodic polling mechanism
	TriggerPeriodic = v1.TriggerPeriodic

	// TriggerManual represents manual triggering mechanism
	TriggerManual = v1.TriggerManual

	// DefaultTriggerMode represents default trigger mechanism
	DefaultTriggerMode = v1.DefaultTriggerMode
)

Functions

func ConsoleLogger

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

func EnablePrintStatements(yes bool) func(*Manager)

func GetCompilerOnContext

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

GetCompilerOnContext gets the compiler cached on the storage context.

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 logging.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 PrintHook

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

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.

func WithDistributedTracingOpts

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

WithDistributedTracingOpts sets the options to be used by distributed tracing.

func WithEnableTelemetry

func WithEnableTelemetry(enableTelemetry bool) func(*Manager)

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

func WithHooks

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

WithHooks allows passing hooks to the plugin manager.

func WithParserOptions

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

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

func WithPrometheusRegister

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

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

func WithRouter

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

func WithTelemetryGatherers

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

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

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

Types

type Factory

type Factory = v1.Factory

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 = v1.Manager

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.

type Plugin

type Plugin = v1.Plugin

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 = v1.State

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

type Status

type Status = v1.Status

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

type StatusListener

type StatusListener v1.StatusListener

StatusListener defines a handler to register for status updates.

type TriggerMode

type TriggerMode = v1.TriggerMode

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

func ValidateAndInjectDefaultsForTriggerMode

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

ValidateAndInjectDefaultsForTriggerMode validates the trigger mode and injects default values

type Triggerable

type Triggerable = v1.Triggerable

Triggerable defines the interface plugins use for manual plugin triggers.