plugins

package
v1.18.2 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2024 License: Apache-2.0 Imports: 17 Imported by: 49

README

Gloo Plugins

This directory defines the plugins that Gloo uses for configuration translation.

To implement a new plugin, create a new struct that implements the Plugin interface, and add it to the registry.

There are several types of plugins. Plugins declare their types in their definition (see gzip for an example, which declares itself to be an HttpFilterPlugin, or csrf, which declares itself to be several types of plugins). Note that because of this, the plugin type does not need to be specified when it is added to the registry; rather, the plugin registry iterates through all plugins and determines their types dynamically and adds them accordingly to the group of plugins by that type. Naturally, each time a plugin is declared to be of a certain type, it must implement the requisite interfaces to be associated as that plugin's type. These interface types are also defined in plugins.go.

This architecture defines how Gloo is able to extensibly implement support for several types of Gateway proxy settings (Virtual Hosts, Http Filters, Upstreams, etc.) while separating their translation implementations from the control plane's core logic.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FilterStageComparison added in v0.18.27 

func FilterStageComparison[WellKnown ~int](a, b FilterStage[WellKnown]) int

FilterStageComparison helps implement the sort.Interface Less function for use in other implementations of sort.Interface returns -1 if less than, 0 if equal, 1 if greater than It is not sufficient to return a Less bool because calling functions need to know if equal or greater when Less is false

func StagedFilterListContainsName added in v1.8.0 

func StagedFilterListContainsName(filters StagedHttpFilterList, filterName string) bool

StagedFilterListContainsName checks for a given named filter. This is not a check of the type url but rather the now mostly unused name

Types

type BaseConfigurationError added in v1.17.0 

type BaseConfigurationError struct {
	// contains filtered or unexported fields
}

BaseConfigurationError is a basic implementation of the ConfigurationError

func NewConfigurationError added in v1.17.0 

func NewConfigurationError(message string) *BaseConfigurationError

NewConfigurationError returns a ConfigurationError that is not a warning

func NewWarningConfigurationError added in v1.17.0 

func NewWarningConfigurationError(message string) *BaseConfigurationError

NewWarningConfigurationError returns a ConfigurationError that is a warning

func (BaseConfigurationError) Error added in v1.17.0 

func (b BaseConfigurationError) Error() string

func (BaseConfigurationError) IsWarning added in v1.17.0 

func (b BaseConfigurationError) IsWarning() bool

type ConfigurationError added in v1.17.0 

type ConfigurationError interface {
	error

	// IsWarning returns true if the error is a warning.
	// Warnings can occur due to eventual consistency in resources selected by config which should not result
	// in the validation webhook rejecting the configuration.
	IsWarning() bool
}

ConfigurationError is an interface for errors that can be returned by plugins. In Gloo Gateway, an invalid state of translation (which results in a Go error, returned by our plugins) can be interpreted as either:

  • Error (this requires user intervention)
  • Warning (this _may_ not require user intervention)

ref: https://docs.solo.io/gloo-edge/latest/guides/traffic_management/configuration_validation/ Historically, this distinction of warnings and errors wasn't possible in plugins, and everything was treated as an error. This interface is used to distinguish errors and validation warnings. It is the responsibility of plugins to return errors that implement this interface if they need to distinguish Go errors that should be treated as warnings

In the future, we may expand the methods on this interface, to allow plugins further granularity of reporting errors. At the time of authoring this, the only available options were: warnings/errors

type EndpointPlugin added in v1.4.0 

type EndpointPlugin interface {
	Plugin
	ProcessEndpoints(params Params, in *v1.Upstream, out *envoy_config_endpoint_v3.ClusterLoadAssignment) error
}

EndpointPlugin modifies an Envoy ClusterLoadAssignment (formerly known as an Endpoint) which has been created for the input Gloo Upstream. This allows the ClusterLoadAssignments to be edited before being sent to Envoy via EDS. NOTE: If one wishes to also modify the corresponding envoy Cluster the above UpstreamPlugin interface should be used.

type ExtendedFilterChain added in v1.14.4 

type ExtendedFilterChain struct {
	*envoy_config_listener_v3.FilterChain
	PassthroughCipherSuites []string
	TerminatingCipherSuites []string
}

ExtendedFilterChain is a FilterChain with additional information This extra information may not end up on the final filter chain But may be used to compute other aspects of the listener that are pulled along with filter chain.

type Filter added in v1.17.0 

type Filter interface {
	proto.Message
	GetName() string
	GetTypedConfig() *anypb.Any
}

type FilterChainMutatorPlugin added in v1.14.4 

type FilterChainMutatorPlugin interface {
	ListenerPlugin // TODO change this to Plugin, and update the places it's used
	ProcessFilterChain(params Params, in *v1.Listener, inFilters []*ExtendedFilterChain, out *envoy_config_listener_v3.Listener) error
}

type FilterStage 

type FilterStage[WellKnown ~int] struct {
	RelativeTo WellKnown
	Weight     int
}

func AfterStage added in v0.18.27 

func AfterStage[WellKnown ~int](wellKnown WellKnown) FilterStage[WellKnown]

func BeforeStage added in v0.18.27 

func BeforeStage[WellKnown ~int](wellKnown WellKnown) FilterStage[WellKnown]

func ConvertFilterStage added in v1.15.0 

func ConvertFilterStage(in *filters.FilterStage) *FilterStage[WellKnownFilterStage]

ConvertFilterStage converts user-specified FilterStage options to the FilterStage representation used for translation.

func DuringStage added in v0.18.27 

func DuringStage[WellKnown ~int](wellKnown WellKnown) FilterStage[WellKnown]

func RelativeToStage added in v0.18.27 

func RelativeToStage[WellKnown ~int](wellKnown WellKnown, weight int) FilterStage[WellKnown]

type HTTPFilterStage added in v1.17.0 

type HTTPFilterStage = FilterStage[WellKnownFilterStage]

type HttpConnectionManagerPlugin added in v1.9.25 

type HttpConnectionManagerPlugin interface {
	Plugin
	ProcessHcmNetworkFilter(params Params, parentListener *v1.Listener, listener *v1.HttpListener, out *envoyhttp.HttpConnectionManager) error
}

HttpConnectionManager Plugins

type HttpFilterPlugin 

type HttpFilterPlugin interface {
	Plugin
	HttpFilters(params Params, listener *v1.HttpListener) ([]StagedHttpFilter, error)
}

type InitParams 

type InitParams struct {
	Ctx      context.Context
	Settings *v1.Settings
}

type ListenerPlugin 

type ListenerPlugin interface {
	Plugin
	ProcessListener(params Params, in *v1.Listener, out *envoy_config_listener_v3.Listener) error
}

type NetworkFilterPlugin added in v1.15.0 

type NetworkFilterPlugin interface {
	Plugin
	NetworkFiltersHTTP(params Params, listener *v1.HttpListener) ([]StagedNetworkFilter, error)
	NetworkFiltersTCP(params Params, listener *v1.TcpListener) ([]StagedNetworkFilter, error)
}

type NetworkFilterStage added in v1.17.0 

type NetworkFilterStage = FilterStage[WellKnownFilterStage]

type Params 

type Params struct {
	Ctx      context.Context
	Settings *v1.Settings
	Snapshot *v1snap.ApiSnapshot
	Messages map[*core.ResourceRef][]string
}

func (Params) CopyWithoutContext added in v1.12.39 

func (p Params) CopyWithoutContext() Params

CopyWithoutContext returns a version of params without ctx Mainly should be used for tests. Still copies pointer to snapshot.

type Plugin 

type Plugin interface {
	// Name returns a unique identifier for a plugin
	Name() string

	// Init is used to re-initialize plugins and is executed for each translation loop
	// This is done for 2 reasons:
	//	1. Each translation run relies on its own context. If a plugin spawns a go-routine
	//		we need to be able to cancel that go-routine on the next translation
	//	2. Plugins are built with the assumption that they will be short lived, only for the
	//		duration of a single translation loop
	Init(params InitParams)
}

Plugin is a named unit of translation, used to produce Envoy configuration

type PluginRegistry added in v1.9.25 

type PluginRegistry interface {
	GetPlugins() []Plugin
	GetListenerPlugins() []ListenerPlugin
	GetTcpFilterChainPlugins() []TcpFilterChainPlugin
	GetHttpFilterPlugins() []HttpFilterPlugin
	GetUpstreamHttpFilterPlugins() []UpstreamHttpFilterPlugin
	GetNetworkFilterPlugins() []NetworkFilterPlugin
	GetHttpConnectionManagerPlugins() []HttpConnectionManagerPlugin
	GetVirtualHostPlugins() []VirtualHostPlugin
	GetResourceGeneratorPlugins() []ResourceGeneratorPlugin
	GetUpstreamPlugins() []UpstreamPlugin
	GetEndpointPlugins() []EndpointPlugin
	GetRoutePlugins() []RoutePlugin
	GetRouteActionPlugins() []RouteActionPlugin
	GetWeightedDestinationPlugins() []WeightedDestinationPlugin
}

A PluginRegistry is used to provide Plugins to relevant translators Historically, all plugins were passed around as an argument, and each translator would iterate over all plugins, and only apply the relevant ones. This interface enables translators to only know of the relevant plugins

type PluginRegistryFactory added in v1.9.25 

type PluginRegistryFactory func(ctx context.Context) PluginRegistry

A PluginRegistryFactory generates a PluginRegistry It is executed each translation loop, ensuring we have up to date configuration of all plugins

type ResourceGeneratorPlugin added in v1.6.10 

type ResourceGeneratorPlugin interface {
	Plugin
	GeneratedResources(params Params,
		inClusters []*envoy_config_cluster_v3.Cluster,
		inEndpoints []*envoy_config_endpoint_v3.ClusterLoadAssignment,
		inRouteConfigurations []*envoy_config_route_v3.RouteConfiguration,
		inListeners []*envoy_config_listener_v3.Listener,
	) ([]*envoy_config_cluster_v3.Cluster, []*envoy_config_endpoint_v3.ClusterLoadAssignment, []*envoy_config_route_v3.RouteConfiguration, []*envoy_config_listener_v3.Listener, error)
}

ResourceGeneratorPlugin modifies a set of xDS resources before they are persisted as a Snapshot

type RouteActionParams added in v0.18.32 

type RouteActionParams struct {
	RouteParams
	Route *v1.Route
}

type RouteActionPlugin 

type RouteActionPlugin interface {
	Plugin
	ProcessRouteAction(params RouteActionParams, inAction *v1.RouteAction, out *envoy_config_route_v3.RouteAction) error
}

RouteActionPlugin modifies an Envoy RouteAction which has been created for the input Gloo Route. NOTE: any route action plugin can be implemented as a route plugin suggestion: if your plugin requires configuration from a RoutePlugin field, implement the RoutePlugin interface

type RouteParams added in v0.14.0 

type RouteParams struct {
	VirtualHostParams
	VirtualHost *v1.VirtualHost
}

type RoutePlugin 

type RoutePlugin interface {
	Plugin
	ProcessRoute(params RouteParams, in *v1.Route, out *envoy_config_route_v3.Route) error
}

RoutePlugin modifies an Envoy Route which has been created for the input Gloo Route. This allows the routes in a RouteConfiguration to be edited before being send to Envoy via RDS.

type StagedFilter added in v1.17.0 

type StagedFilter[WellKnown ~int, FilterType Filter] struct {
	Filter FilterType
	Stage  FilterStage[WellKnown]
}

type StagedFilterList added in v1.17.0 

type StagedFilterList[WellKnown ~int, FilterType Filter] []StagedFilter[WellKnown, FilterType]

func (StagedFilterList[WellKnown, FilterType]) Len added in v1.17.0 

func (s StagedFilterList[WellKnown, FilterType]) Len() int

func (StagedFilterList[WellKnown, FilterType]) Less added in v1.17.0 

func (s StagedFilterList[WellKnown, FilterType]) Less(i, j int) bool

filters by Relative Stage, Weighting, Name, Config Type-Url, Config Value, and (to ensure stability) index. The assumption is that if two filters are in the same stage, their order doesn't matter, and we just need to make sure it is stable.

func (StagedFilterList[WellKnown, FilterType]) Swap added in v1.17.0 

func (s StagedFilterList[WellKnown, FilterType]) Swap(i, j int)

type StagedHttpFilter 

type StagedHttpFilter = StagedFilter[WellKnownFilterStage, *envoyhttp.HttpFilter]

func MustNewStagedFilter added in v1.9.25 

func MustNewStagedFilter(name string, config proto.Message, stage FilterStage[WellKnownFilterStage]) StagedHttpFilter

MustNewStagedFilter creates an instance of the named filter with the desired stage. Returns a filter even if an error occurred. Should rarely be used as disregarding an error is bad practice but does make appending easier. If not directly appending consider using NewStagedFilter instead of this function.

func NewStagedFilter added in v0.11.1 

func NewStagedFilter(name string, config proto.Message, stage FilterStage[WellKnownFilterStage]) (StagedHttpFilter, error)

NewStagedFilter creates an instance of the named filter with the desired stage. Errors if the config is nil or we cannot determine the type of the config. Config type determination may fail if the config is both unknown and has no fields.

type StagedHttpFilterList added in v0.18.27 

type StagedHttpFilterList = StagedFilterList[WellKnownFilterStage, *envoyhttp.HttpFilter]

type StagedNetworkFilter added in v1.9.25 

type StagedNetworkFilter = StagedFilter[WellKnownFilterStage, *envoy_config_listener_v3.Filter]

type StagedNetworkFilterList added in v1.9.25 

type StagedNetworkFilterList = StagedFilterList[WellKnownFilterStage, *envoy_config_listener_v3.Filter]

type StagedUpstreamHttpFilter added in v1.17.0 

type StagedUpstreamHttpFilter = StagedFilter[WellKnownUpstreamHTTPFilterStage, *envoyhttp.HttpFilter]

type StagedUpstreamHttpFilterList added in v1.17.0 

type StagedUpstreamHttpFilterList = StagedFilterList[WellKnownUpstreamHTTPFilterStage, *envoyhttp.HttpFilter]

type TcpFilterChainPlugin added in v1.9.25 

type TcpFilterChainPlugin interface {
	Plugin
	CreateTcpFilterChains(params Params, parentListener *v1.Listener, in *v1.TcpListener) ([]*envoy_config_listener_v3.FilterChain, error)
}

type UpstreamHTTPFilterStage added in v1.17.0 

type UpstreamHTTPFilterStage = FilterStage[WellKnownUpstreamHTTPFilterStage]

type UpstreamHttpFilterPlugin added in v1.17.0 

type UpstreamHttpFilterPlugin interface {
	Plugin
	UpstreamHttpFilters(params Params, listener *v1.HttpListener) ([]StagedUpstreamHttpFilter, error)
}

type UpstreamPlugin 

type UpstreamPlugin interface {
	Plugin
	ProcessUpstream(params Params, in *v1.Upstream, out *envoy_config_cluster_v3.Cluster) error
}

UpstreamPlugin modifies the Envoy Cluster which has been created for the input Gloo Upstream. This allows the Cluster to be edited before being sent to Envoy via CDS

type VirtualHostParams added in v0.15.0 

type VirtualHostParams struct {
	Params
	Proxy        *v1.Proxy
	Listener     *v1.Listener
	HttpListener *v1.HttpListener
}

type VirtualHostPlugin 

type VirtualHostPlugin interface {
	Plugin
	ProcessVirtualHost(params VirtualHostParams, in *v1.VirtualHost, out *envoy_config_route_v3.VirtualHost) error
}

type WeightedDestinationPlugin added in v0.18.7 

type WeightedDestinationPlugin interface {
	Plugin
	ProcessWeightedDestination(
		params RouteActionParams,
		in *v1.WeightedDestination,
		out *envoy_config_route_v3.WeightedCluster_ClusterWeight,
	) error
}

type WellKnownFilterStage added in v0.18.27 

type WellKnownFilterStage int

WellKnownFilterStages are represented by an integer that reflects their relative ordering 

const (
	FaultStage     WellKnownFilterStage = iota // Fault injection // First Filter Stage
	CorsStage                                  // Cors stage
	WafStage                                   // Web application firewall stage
	AuthNStage                                 // Authentication stage
	AuthZStage                                 // Authorization stage
	RateLimitStage                             // Rate limiting stage
	AcceptedStage                              // Request passed all the checks and will be forwarded upstream
	OutAuthStage                               // Add auth for the upstream (i.e. aws λ)
	RouteStage                                 // Request is going to upstream // Last Filter Stage
)

The set of WellKnownFilterStages, whose order corresponds to the order used to sort filters If new well known filter stages are added, they should be inserted in a position corresponding to their order

type WellKnownUpstreamHTTPFilterStage added in v1.17.0 

type WellKnownUpstreamHTTPFilterStage int
const (
	TransformationStage WellKnownUpstreamHTTPFilterStage = iota // Transformation stage
)

The set of WellKnownUpstreamHTTPFilterStages, whose order corresponds to the order used to sort filters If new well known filter stages are added, they should be inserted in a position corresponding to their order

Source Files

View all Source files

Directories

Path Synopsis
aws
ec2
ec2/util
mocks
Package mock_consul is a generated GoMock package.
 Package mock_consul is a generated GoMock package.
Package enterprise_warning creates the EnterpriseWarning plugin.
 Package enterprise_warning creates the EnterpriseWarning plugin.
internal
common
mocks
Package mock_kubernetes is a generated GoMock package.
 Package mock_kubernetes is a generated GoMock package.
serviceconverter
Package registry is responsible for managing
 Package registry is responsible for managing
headers
httpprotocolhelpers
httpprotocolvalidation
transformation
upgradeconfig
upstreamproxyprotocol
validator

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.