extensioncommon

package
v0.3.0-rc1.0...-9dd6c97 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2023 License: MPL-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var TrafficDirections = StringSet{string(TrafficDirectionInbound): {}, string(TrafficDirectionOutbound): {}}

Functions

func FilterClusterNames 

func FilterClusterNames(filter *envoy_listener_v3.Filter) map[string]struct{}

func GetHTTPConnectionManager 

func GetHTTPConnectionManager(filters ...*envoy_listener_v3.Filter) (*envoy_http_v3.HttpConnectionManager, int, error)

GetHTTPConnectionManager returns the Envoy HttpConnectionManager filter from the list of network filters. It also returns the index within the list of filters where the connection manager was found in case the caller needs this information. It returns a non-nil error if the HttpConnectionManager is not found.

func GetListenerEnvoyID 

func GetListenerEnvoyID(l *envoy_listener_v3.Listener) string

GetListenerEnvoyID returns the Envoy ID string parsed from the name of the given Listener. If none is found, it returns the empty string.

func GetTCPProxy 

func GetTCPProxy(filter *envoy_listener_v3.Filter) *envoy_tcp_proxy_v3.TcpProxy

func InsertHTTPFilter 

func InsertHTTPFilter(filters []*envoy_listener_v3.Filter, filter *envoy_http_v3.HttpFilter, opts InsertOptions) ([]*envoy_listener_v3.Filter, error)

InsertHTTPFilter inserts the given HTTP filter into the HttpConnectionManager's filter chain in the location determined by the insert options. This list of filters must include the HttpConnectionManager network filter or the operation will fail.

It returns the modified list of filters including the updated HttpConnectionManager. If a matching location is not found to insert the filter, a non-nil error is returned.

func InsertNetworkFilter 

func InsertNetworkFilter(filters []*envoy_listener_v3.Filter, filter *envoy_listener_v3.Filter, opts InsertOptions) ([]*envoy_listener_v3.Filter, error)

InsertNetworkFilter inserts the given network filter into the filter chain in the location determined by the insert options.

It returns the modified list of filters including the new filter. If a matching location is not found to insert the filter, a non-nil error is returned.

func IsInboundPublicListener 

func IsInboundPublicListener(l *envoy_listener_v3.Listener) bool

IsInboundPublicListener returns true if the given Listener represents the inbound public Listener for the local service.

func IsLocalAppCluster 

func IsLocalAppCluster(c *envoy_cluster_v3.Cluster) bool

IsLocalAppCluster returns true if the given Cluster represents the local Cluster, which receives inbound traffic to the local proxy.

func IsLocalAppClusterLoadAssignment 

func IsLocalAppClusterLoadAssignment(a *envoy_endpoint_v3.ClusterLoadAssignment) bool

IsLocalAppClusterLoadAssignment returns true if the given ClusterLoadAssignment represents the local Cluster, which receives inbound traffic to the local proxy.

func IsOutboundTProxyListener 

func IsOutboundTProxyListener(l *envoy_listener_v3.Listener) bool

IsOutboundTProxyListener returns true if the given Listener represents the outbound TProxy Listener for the local service.

func IsRouteToLocalAppCluster 

func IsRouteToLocalAppCluster(r *envoy_route_v3.RouteConfiguration) bool

IsRouteToLocalAppCluster takes a RouteConfiguration and returns true if all routes within it target the local Cluster. Note that because we currently target RouteConfiguration in PatchRoute, we have to check multiple individual Route resources.

func MakeEnvoyHTTPFilter 

func MakeEnvoyHTTPFilter(name string, cfg proto.Message) (*envoy_http_v3.HttpFilter, error)

MakeEnvoyHTTPFilter generates an Envoy HTTP filter from the given proto message.

func MakeFilter 

func MakeFilter(name string, cfg proto.Message) (*envoy_listener_v3.Filter, error)

MakeFilter generates an Envoy listener filter from the given proto message.

func MakeTransportSocket 

func MakeTransportSocket(name string, config proto.Message) (*envoy_core_v3.TransportSocket, error)

MakeTransportSocket generates an Envoy transport socket from the given proto message.

func MakeUpstreamTLSTransportSocket 

func MakeUpstreamTLSTransportSocket(tlsContext *envoy_tls_v3.UpstreamTlsContext) (*envoy_core_v3.TransportSocket, error)

MakeUpstreamTLSTransportSocket generates an Envoy transport socket for the given TLS context.

func NormalizeEmptyToDefault 

func NormalizeEmptyToDefault(s string) string

func NormalizeServiceName 

func NormalizeServiceName(sn *api.CompoundServiceName)

func RouteClusterNames 

func RouteClusterNames(route *envoy_route_v3.RouteConfiguration) map[string]struct{}

Types

type BasicEnvoyExtender 

type BasicEnvoyExtender struct {
	Extension BasicExtension
}

BasicEnvoyExtender provides convenience functions for iterating and applying modifications to Envoy resources.

func (*BasicEnvoyExtender) CanApply 

func (b *BasicEnvoyExtender) CanApply(config *RuntimeConfig) bool

func (*BasicEnvoyExtender) Extend 

func (b *BasicEnvoyExtender) Extend(resources *xdscommon.IndexedResources, config *RuntimeConfig) (*xdscommon.IndexedResources, error)

func (*BasicEnvoyExtender) Validate 

func (b *BasicEnvoyExtender) Validate(config *RuntimeConfig) error

type BasicExtension 

type BasicExtension interface {
	// CanApply determines if the extension can mutate resources for the given runtime configuration.
	CanApply(*RuntimeConfig) bool

	// PatchRoute patches a route to include the custom Envoy configuration
	// required to integrate with the built in extension template.
	// See also PatchRoutes.
	PatchRoute(RoutePayload) (*envoy_route_v3.RouteConfiguration, bool, error)

	// PatchRoutes patches routes to include the custom Envoy configuration
	// required to integrate with the built in extension template.
	// This allows extensions to operate on a collection of routes.
	// For extensions that implement both PatchRoute and PatchRoutes,
	// PatchRoutes is always called first with the entire collection of routes.
	// Then PatchRoute is called for each individual route.
	PatchRoutes(*RuntimeConfig, RouteMap) (RouteMap, error)

	// PatchCluster patches a cluster to include the custom Envoy configuration
	// required to integrate with the built in extension template.
	// See also PatchClusters.
	PatchCluster(ClusterPayload) (*envoy_cluster_v3.Cluster, bool, error)

	// PatchClusters patches clusters to include the custom Envoy configuration
	// required to integrate with the built in extension template.
	// This allows extensions to operate on a collection of clusters.
	// For extensions that implement both PatchCluster and PatchClusters,
	// PatchClusters is always called first with the entire collection of clusters.
	// Then PatchClusters is called for each individual cluster.
	PatchClusters(*RuntimeConfig, ClusterMap) (ClusterMap, error)

	// PatchClusterLoadAssignment patches a cluster load assignment to include the custom Envoy configuration
	// required to integrate with the built in extension template.
	PatchClusterLoadAssignment(ClusterLoadAssignmentPayload) (*envoy_endpoint_v3.ClusterLoadAssignment, bool, error)

	// PatchListener patches a listener to include the custom Envoy configuration
	// required to integrate with the built in extension template.
	// See also PatchListeners.
	PatchListener(ListenerPayload) (*envoy_listener_v3.Listener, bool, error)

	// PatchListeners patches listeners to include the custom Envoy configuration
	// required to integrate with the built in extension template.
	// This allows extensions to operate on a collection of listeners.
	// For extensions that implement both PatchListener and PatchListeners,
	// PatchListeners is always called first with the entire collection of listeners.
	// Then PatchListeners is called for each individual listener.
	PatchListeners(*RuntimeConfig, ListenerMap) (ListenerMap, error)

	// PatchFilter patches an Envoy filter to include the custom Envoy
	// configuration required to integrate with the built in extension template.
	// See also PatchFilters.
	PatchFilter(FilterPayload) (*envoy_listener_v3.Filter, bool, error)

	// PatchFilters patches Envoy filters to include the custom Envoy
	// configuration required to integrate with the built in extension template.
	// This allows extensions to operate on a collection of filters.
	// For extensions that implement both PatchFilter and PatchFilters,
	// PatchFilters is always called first with the entire collection of filters.
	// Then PatchFilter is called for each individual filter.
	PatchFilters(cfg *RuntimeConfig, f []*envoy_listener_v3.Filter, isInboundListener bool) ([]*envoy_listener_v3.Filter, error)

	// Validate determines if the runtime configuration provided is valid for the extension.
	Validate(*RuntimeConfig) error
}

BasicExtension is the interface that each user of BasicEnvoyExtender must implement. It is responsible for modifying the xDS structures based on only the state of the extension.

type BasicExtensionAdapter 

type BasicExtensionAdapter struct{}

BasicExtensionAdapter is an adapter that provides default implementations for all of the EnvoyExtension interface functions. Extension implementations can extend the adapter and implement only the functions they are interested in. At a minimum, extensions must override the adapter's CanApply and Validate functions.

func (BasicExtensionAdapter) CanApply 

func (BasicExtensionAdapter) CanApply(_ *RuntimeConfig) bool

CanApply provides a default implementation of the CanApply interface that always returns false.

func (BasicExtensionAdapter) PatchCluster 

func (BasicExtensionAdapter) PatchCluster(p ClusterPayload) (*envoy_cluster_v3.Cluster, bool, error)

PatchCluster provides a default implementation of the PatchCluster interface that does nothing.

func (BasicExtensionAdapter) PatchClusterLoadAssignment 

func (BasicExtensionAdapter) PatchClusterLoadAssignment(p ClusterLoadAssignmentPayload) (*envoy_endpoint_v3.ClusterLoadAssignment, bool, error)

PatchClusterLoadAssignment provides a default implementation of the PatchClusterLoadAssignment interface that does nothing.

func (BasicExtensionAdapter) PatchClusters 

func (BasicExtensionAdapter) PatchClusters(_ *RuntimeConfig, c ClusterMap) (ClusterMap, error)

PatchClusters provides a default implementation of the PatchClusters interface that does nothing.

func (BasicExtensionAdapter) PatchFilter 

func (BasicExtensionAdapter) PatchFilter(p FilterPayload) (*envoy_listener_v3.Filter, bool, error)

PatchFilter provides a default implementation of the PatchFilter interface that does nothing.

func (BasicExtensionAdapter) PatchFilters 

func (BasicExtensionAdapter) PatchFilters(_ *RuntimeConfig, f []*envoy_listener_v3.Filter, _ bool) ([]*envoy_listener_v3.Filter, error)

PatchFilters provides a default implementation of the PatchFilters interface that does nothing.

func (BasicExtensionAdapter) PatchListener 

func (BasicExtensionAdapter) PatchListener(p ListenerPayload) (*envoy_listener_v3.Listener, bool, error)

PatchListener provides a default implementation of the PatchListener interface that does nothing.

func (BasicExtensionAdapter) PatchListeners 

func (BasicExtensionAdapter) PatchListeners(_ *RuntimeConfig, l ListenerMap) (ListenerMap, error)

PatchListeners provides a default implementation of the PatchListeners interface that does nothing.

func (BasicExtensionAdapter) PatchRoute 

func (BasicExtensionAdapter) PatchRoute(p RoutePayload) (*envoy_route_v3.RouteConfiguration, bool, error)

PatchRoute provides a default implementation of the PatchRoute interface that does nothing.

func (BasicExtensionAdapter) PatchRoutes 

func (BasicExtensionAdapter) PatchRoutes(_ *RuntimeConfig, r RouteMap) (RouteMap, error)

PatchRoutes provides a default implementation of the PatchRoutes interface that does nothing.

func (BasicExtensionAdapter) Validate 

func (BasicExtensionAdapter) Validate(_ *RuntimeConfig) error

Validate provides a default implementation of the Validate interface that always returns nil.

type ClusterLoadAssignmentMap 

type ClusterLoadAssignmentMap map[string]*envoy_endpoint_v3.ClusterLoadAssignment

ClusterLoadAssignmentMap is a map of cluster load assignments indexed by name.

type ClusterLoadAssignmentPayload 

type ClusterLoadAssignmentPayload = Payload[*envoy_endpoint_v3.ClusterLoadAssignment]

type ClusterMap 

type ClusterMap map[string]*envoy_cluster_v3.Cluster

ClusterMap is a map of clusters indexed by name.

type ClusterPayload 

type ClusterPayload = Payload[*envoy_cluster_v3.Cluster]

type EnvoyExtender 

type EnvoyExtender interface {

	// CanApply checks whether the extension configured for this extender is eligible
	// for application based on the specified RuntimeConfig.
	CanApply(*RuntimeConfig) bool

	// Validate ensures the data in config can successfuly be used
	// to apply the specified Envoy extension.
	Validate(*RuntimeConfig) error

	// Extend updates indexed xDS structures to include patches for
	// built-in extensions. It is responsible for applying extensions to
	// the the appropriate xDS resources. If any portion of this function fails,
	// it will attempt continue and return an error. The caller can then determine
	// if it is better to use a partially applied extension or error out.
	Extend(*xdscommon.IndexedResources, *RuntimeConfig) (*xdscommon.IndexedResources, error)
}

EnvoyExtender is the interface that all Envoy extensions must implement in order to be dynamically executed during runtime.

type FilterPayload 

type FilterPayload = Payload[*envoy_listener_v3.Filter]

type InsertLocation 

type InsertLocation string

InsertLocation indicates where to insert an Envoy resource within a list of resources. 

const (
	// InsertFirst inserts the resource as the first entry in the list.
	InsertFirst InsertLocation = "First"
	// InsertLast inserts the resource as the last entry in the list.
	InsertLast InsertLocation = "Last"
	// InsertBeforeFirstMatch inserts the resource before the first resource with a matching name.
	InsertBeforeFirstMatch InsertLocation = "BeforeFirstMatch"
	// InsertAfterFirstMatch inserts the resource after the first resource with a matching name.
	InsertAfterFirstMatch InsertLocation = "AfterFirstMatch"
	// InsertBeforeLastMatch inserts the resource before the last resource with a matching name.
	InsertBeforeLastMatch InsertLocation = "BeforeLastMatch"
	// InsertAfterLastMatch inserts the resource after the last resource with a matching name.
	InsertAfterLastMatch InsertLocation = "AfterLastMatch"
)

type InsertOptions 

type InsertOptions struct {
	// Location defines where to insert the resource within the list.
	Location InsertLocation
	// FilterName indicates the name of the resource to insert relative to.
	FilterName string
}

InsertOptions controls how and where to insert Envoy resources.

type ListenerMap 

type ListenerMap map[string]*envoy_listener_v3.Listener

ListenerMap is a map of listeners indexed by name.

type ListenerPayload 

type ListenerPayload = Payload[*envoy_listener_v3.Listener]

type Payload 

type Payload[K proto.Message] struct {
	RuntimeConfig    *RuntimeConfig
	ServiceName      *api.CompoundServiceName
	Upstream         *UpstreamData
	TrafficDirection TrafficDirection
	Message          K
}

Payload represents a single Envoy resource to be modified by extensions. It associates the RuntimeConfig of the local proxy, the TrafficDirection of the resource, and the CompoundServiceName and UpstreamData (if outbound) of a service the Envoy resource corresponds to.

func (Payload[K]) IsInbound 

func (p Payload[K]) IsInbound() bool

type RouteMap 

type RouteMap map[string]*envoy_route_v3.RouteConfiguration

RouteMap is a map of routes indexed by name.

type RoutePayload 

type RoutePayload = Payload[*envoy_route_v3.RouteConfiguration]

type RuntimeConfig 

type RuntimeConfig struct {
	// EnvoyExtension is the extension that will patch Envoy resources.
	EnvoyExtension api.EnvoyExtension

	// ServiceName is the name of the service the EnvoyExtension is being applied to. It is typically the local service
	// (IsSourcedFromUpstream = false), but can also be an upstream of the local service (IsSourcedFromUpstream = true).
	ServiceName api.CompoundServiceName

	// Upstreams represent the upstreams of the local service. This is consistent regardless of the value of
	// IsSourcedFromUpstream, which refers to the Envoy extension source.
	Upstreams map[api.CompoundServiceName]*UpstreamData

	// IsSourcedFromUpstream is set to true only in the exceptional cases where upstream service config contains
	// extensions that apply to the configured service's downstreams. In those cases, this value will be true when such
	// a downstream is the local service. In all other cases, IsSourcedFromUpstream will be false.
	//
	// This is used exclusively for specific extensions (currently, only AWS Lambda and Validate) in which we
	// intentionally apply the extension to downstreams rather than the local proxy of the configured service itself.
	// This is generally dangerous, since it circumvents ACLs for the affected downstream services (the upstream owner
	// may not have `service:write` for the downstreams).
	//
	// Extensions used this way MUST be designed to allow only trusted modifications of downstream proxies that impact
	// their ability to call the upstream service. Remote configurations MUST NOT be allowed to otherwise modify local
	// proxies until we support explicit extension capability controls or require privileges higher than the typical
	// `service:write` required to configure extensions.
	//
	// See UpstreamEnvoyExtender for the code that applies RuntimeConfig with this flag set.
	IsSourcedFromUpstream bool

	// Kind is mode the local Envoy proxy is running in. For now, only connect proxy and
	// terminating gateways are supported.
	Kind api.ServiceKind

	// Protocol is the protocol configured for the local service. It may be empty which implies tcp.
	Protocol string
}

RuntimeConfig is the configuration for an extension attached to a service on the local proxy. It should depend on the API client rather than the structs package because the API client is meant to be public.

func (*RuntimeConfig) GetClusterLoadAssignmentPayload 

func (cfg *RuntimeConfig) GetClusterLoadAssignmentPayload(c *envoy_endpoint_v3.ClusterLoadAssignment) ClusterLoadAssignmentPayload

func (*RuntimeConfig) GetClusterPayload 

func (cfg *RuntimeConfig) GetClusterPayload(c *envoy_cluster_v3.Cluster) ClusterPayload

func (*RuntimeConfig) GetFilterPayload 

func (c *RuntimeConfig) GetFilterPayload(f *envoy_listener_v3.Filter, l *envoy_listener_v3.Listener) FilterPayload

func (*RuntimeConfig) GetListenerPayload 

func (c *RuntimeConfig) GetListenerPayload(l *envoy_listener_v3.Listener) ListenerPayload

func (*RuntimeConfig) GetRoutePayload 

func (c *RuntimeConfig) GetRoutePayload(r *envoy_route_v3.RouteConfiguration) RoutePayload

func (RuntimeConfig) MatchesUpstreamServiceSNI 

func (c RuntimeConfig) MatchesUpstreamServiceSNI(sni string) bool

MatchesUpstreamServiceSNI indicates if the extension configuration is for an upstream service that matches the given SNI, if the RuntimeConfig corresponds to an upstream of the local service. Only used when IsSourcedFromUpstream is true.

func (RuntimeConfig) UpstreamEnvoyID 

func (c RuntimeConfig) UpstreamEnvoyID() string

UpstreamEnvoyID returns the unique Envoy identifier of the upstream service, if the RuntimeConfig corresponds to an upstream of the local service. Note that this could be the local service if it targets itself as an upstream. Only used when IsSourcedFromUpstream is true.

func (RuntimeConfig) UpstreamOutgoingProxyKind 

func (c RuntimeConfig) UpstreamOutgoingProxyKind() api.ServiceKind

UpstreamOutgoingProxyKind returns the service kind for the outgoing listener of the upstream service, if the RuntimeConfig corresponds to an upstream of the local service. Only used when IsSourcedFromUpstream is true.

type StringSet 

type StringSet map[string]struct{}

func (*StringSet) CheckRequired 

func (c *StringSet) CheckRequired(v, fieldName string) error

type TrafficDirection 

type TrafficDirection string

TrafficDirection determines whether inbound or outbound Envoy resources will be patched. 

const (
	TrafficDirectionInbound  TrafficDirection = "inbound"
	TrafficDirectionOutbound TrafficDirection = "outbound"
)

type UpstreamData 

type UpstreamData struct {
	// This is the SNI for the upstream service without accounting for any discovery chain magic.
	PrimarySNI string

	// SNIs is the SNIs header used to reach an upstream service.
	SNIs map[string]struct{}

	// EnvoyID is the envoy ID of an upstream service, structured <service> or <partition>/<ns>/<service> when using a
	// non-default namespace or partition.
	EnvoyID string

	// OutgoingProxyKind is the type of proxy of the upstream service. However, if the upstream is "typical" this will
	// be set to "connect-proxy" instead.
	OutgoingProxyKind api.ServiceKind

	// VIP is the tproxy virtual IP used to reach an upstream service.
	VIP string
}

UpstreamData has the SNI, EnvoyID, and OutgoingProxyKind of the upstream services for the local proxy and this data is used to choose which Envoy resources to patch.

type UpstreamEnvoyExtender 

type UpstreamEnvoyExtender struct {
	Extension BasicExtension
}

UpstreamEnvoyExtender facilitates uncommon scenarios in which an upstream service's extension needs to apply changes to downstram proxies. Separating this mode from the more typical case of extensions patching just the local proxy for the configured service allows us to more effectively enforce controls over this elevated level of privilege.

THIS EXTENDER SHOULD NOT BE USED BY ANY NEW EXTENSIONS! It is only intended for use by the builtin AWS Lambda extension and Validate (read-only) pseudo-extension to support their existing behavior. Future changes to the extension API will introduce stronger controls around privileged capabilities, at which point this extender can be removed.

See documentation in RuntimeConfig.IsSourcedFromUpstream for more details.

func (*UpstreamEnvoyExtender) CanApply 

func (ext *UpstreamEnvoyExtender) CanApply(config *RuntimeConfig) bool

func (*UpstreamEnvoyExtender) Extend 

func (ext *UpstreamEnvoyExtender) Extend(resources *xdscommon.IndexedResources, config *RuntimeConfig) (*xdscommon.IndexedResources, error)

func (*UpstreamEnvoyExtender) Validate 

func (ext *UpstreamEnvoyExtender) Validate(_ *RuntimeConfig) error

Source Files

View all Source files

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.