Documentation
¶
Overview ¶
Package xds provides an implementation of a gRPC service that exports Envoy's xDS API for config discovery. Specifically we support the Aggregated Discovery Service (ADS) only as we control all config.
A full description of the XDS protocol can be found at https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol
xds.Server also support ext_authz network filter API to authorize incoming connections to Envoy.
Index ¶
- Constants
- Variables
- func CustomizeClusterName(clusterName string, chain *structs.CompiledDiscoveryChain) string
- func ToOutlierDetection(p *structs.PassiveHealthCheck) *envoy_cluster_v3.OutlierDetection
- type ACLResolverFunc
- type ADSDeltaStream
- type ADSStream
- type ConfigFetcher
- type GatewayConfig
- type PendingUpdate
- type ProxyConfig
- type ProxyConfigSource
- type ResourceGenerator
- type Server
- type SessionLimiter
- type TestADSDeltaStream
- func (s *TestADSDeltaStream) Context() context.Context
- func (s *TestADSDeltaStream) Recv() (*envoy_discovery_v3.DeltaDiscoveryRequest, error)
- func (s *TestADSDeltaStream) RecvMsg(m interface{}) error
- func (s *TestADSDeltaStream) Send(r *envoy_discovery_v3.DeltaDiscoveryResponse) error
- func (s *TestADSDeltaStream) SendHeader(metadata.MD) error
- func (s *TestADSDeltaStream) SendMsg(m interface{}) error
- func (s *TestADSDeltaStream) SetHeader(metadata.MD) error
- func (s *TestADSDeltaStream) SetSendErr(err error)
- func (s *TestADSDeltaStream) SetTrailer(metadata.MD)
- type TestEnvoy
- func (e *TestEnvoy) Close() error
- func (e *TestEnvoy) SendDeltaReq(t testing.T, typeURL string, req *envoy_discovery_v3.DeltaDiscoveryRequest)
- func (e *TestEnvoy) SendDeltaReqACK(t testing.T, typeURL string, nonce uint64)
- func (e *TestEnvoy) SendDeltaReqNACK(t testing.T, typeURL string, nonce uint64, errorDetail *status.Status)
- func (e *TestEnvoy) SetSendErr(err error)
Constants ¶
const ( // PublicListenerName is the name we give the public listener in Envoy config. PublicListenerName = "public_listener" // OutboundListenerName is the name we give the outbound Envoy listener when transparent proxy mode is enabled. OutboundListenerName = "outbound_listener" // LocalAppClusterName is the name we give the local application "cluster" in // Envoy config. Note that all cluster names may collide with service names // since we want cluster names and service names to match to enable nice // metrics correlation without massaging prefixes on cluster names. // // We should probably make this more unlikely to collide however changing it // potentially breaks upgrade compatibility without restarting all Envoy's as // it will no longer match their existing cluster name. Changing this will // affect metrics output so could break dashboards (for local app traffic). // // We should probably just make it configurable if anyone actually has // services named "local_app" in the future. LocalAppClusterName = "local_app" // LocalAgentClusterName is the name we give the local agent "cluster" in // Envoy config. Note that all cluster names may collide with service names // since we want cluster names and service names to match to enable nice // metrics correlation without massaging prefixes on cluster names. // // We should probably make this more unlikely to collied however changing it // potentially breaks upgrade compatibility without restarting all Envoy's as // it will no longer match their existing cluster name. Changing this will // affect metrics output so could break dashboards (for local agent traffic). // // We should probably just make it configurable if anyone actually has // services named "local_agent" in the future. LocalAgentClusterName = "local_agent" // OriginalDestinationClusterName is the name we give to the passthrough // cluster which redirects transparently-proxied requests to their original // destination outside the mesh. This cluster prevents Consul from blocking // connections to destinations outside of the catalog when in transparent // proxy mode. OriginalDestinationClusterName = "original-destination" // DefaultAuthCheckFrequency is the default value for // Server.AuthCheckFrequency to use when the zero value is provided. DefaultAuthCheckFrequency = 5 * time.Minute )
const (
UnnamedSubset = ""
)
Variables ¶
var StatsCounters = []prometheus.CounterDefinition{ { Name: []string{"xds", "server", "streamDrained"}, Help: "Counts the number of xDS streams that are drained when rebalancing the load between servers.", }, }
var StatsGauges = []prometheus.GaugeDefinition{ { Name: []string{"xds", "server", "streams"}, Help: "Measures the number of active xDS streams handled by the server split by protocol version.", }, }
var StatsSummaries = []prometheus.SummaryDefinition{ { Name: []string{"xds", "server", "streamStart"}, Help: "Measures the time in milliseconds after an xDS stream is opened until xDS resources are first generated for the stream.", }, }
Functions ¶
func CustomizeClusterName ¶ added in v1.6.0
func CustomizeClusterName(clusterName string, chain *structs.CompiledDiscoveryChain) string
func ToOutlierDetection ¶ added in v1.10.0
func ToOutlierDetection(p *structs.PassiveHealthCheck) *envoy_cluster_v3.OutlierDetection
Return an envoy.OutlierDetection populated by the values from this struct. If all values are zero a default empty OutlierDetection will be returned to enable outlier detection with default values.
Types ¶
type ACLResolverFunc ¶
type ACLResolverFunc func(id string) (acl.Authorizer, error)
ACLResolverFunc is a shim to resolve ACLs. Since ACL enforcement is so far entirely agent-local and all uses private methods this allows a simple shim to be written in the agent package to allow resolving without tightly coupling this to the agent.
type ADSDeltaStream ¶ added in v1.10.0
type ADSDeltaStream = envoy_discovery_v3.AggregatedDiscoveryService_DeltaAggregatedResourcesServer
ADSDeltaStream is a shorter way of referring to this thing...
type ConfigFetcher ¶ added in v1.6.2
type ConfigFetcher interface {
AdvertiseAddrLAN() string
}
ConfigFetcher is the interface the agent needs to expose for the xDS server to fetch agent config, currently only one field is fetched
type GatewayConfig ¶ added in v1.8.0
type GatewayConfig struct { // BindTaggedAddresses when set will cause all of the services tagged // addresses to have listeners bound to them in addition to the main service // address listener. This is only suitable when the tagged addresses are IP // addresses of network interfaces Envoy can see. i.e. When using DNS names // for those addresses or where an external entity maps that IP to the Envoy // (like AWS EC2 mapping a public IP to the private interface) then this // cannot be used. See the BindAddresses config instead BindTaggedAddresses bool `mapstructure:"envoy_gateway_bind_tagged_addresses" alias:"envoy_mesh_gateway_bind_tagged_addresses"` // BindAddresses additional bind addresses to configure listeners for BindAddresses map[string]structs.ServiceAddress `mapstructure:"envoy_gateway_bind_addresses" alias:"envoy_mesh_gateway_bind_addresses"` // NoDefaultBind indicates that we should not bind to the default address of the // gateway service NoDefaultBind bool `mapstructure:"envoy_gateway_no_default_bind" alias:"envoy_mesh_gateway_no_default_bind"` // DNSDiscoveryType indicates the DNS service discovery type. // See: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#arch-overview-service-discovery-types DNSDiscoveryType string `mapstructure:"envoy_dns_discovery_type"` // ConnectTimeoutMs is the number of milliseconds to timeout making a new // connection to this upstream. Defaults to 5000 (5 seconds) if not set. ConnectTimeoutMs int `mapstructure:"connect_timeout_ms"` // TCP keepalive settings for remote gateway upstreams (mesh gateways and terminating gateway upstreams). // See: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto#envoy-v3-api-msg-config-core-v3-tcpkeepalive TcpKeepaliveEnable bool `mapstructure:"envoy_gateway_remote_tcp_enable_keepalive"` TcpKeepaliveTime int `mapstructure:"envoy_gateway_remote_tcp_keepalive_time"` TcpKeepaliveInterval int `mapstructure:"envoy_gateway_remote_tcp_keepalive_interval"` TcpKeepaliveProbes int `mapstructure:"envoy_gateway_remote_tcp_keepalive_probes"` }
func ParseGatewayConfig ¶ added in v1.8.0
func ParseGatewayConfig(m map[string]interface{}) (GatewayConfig, error)
ParseGatewayConfig returns the GatewayConfig parsed from an opaque map. If an error occurs during parsing, it is returned along with the default config. This allows the caller to choose whether and how to report the error
type PendingUpdate ¶ added in v1.10.0
type ProxyConfig ¶ added in v1.5.0
type ProxyConfig struct { // PublicListenerJSON is a complete override ("escape hatch") for the // upstream's public listener. The Connect server TLS certificate and // validation context will be injected overriding any TLS settings present. An // AuthZ filter will also be prepended to each filterChain provided to enforce // Connect's access control. // // Note: This escape hatch is compatible with the discovery chain. PublicListenerJSON string `mapstructure:"envoy_public_listener_json"` // ListenerTracingJSON is a complete override ("escape hatch") for the // listeners tracing configuration. // // Note: This escape hatch is compatible with the discovery chain. ListenerTracingJSON string `mapstructure:"envoy_listener_tracing_json"` // LocalClusterJSON is a complete override ("escape hatch") for the // local application cluster. // // Note: This escape hatch is compatible with the discovery chain. LocalClusterJSON string `mapstructure:"envoy_local_cluster_json"` // LocalConnectTimeoutMs is the number of milliseconds to timeout making a new // connection to the local app instance. Defaults to 5000 (5 seconds) if not // set. LocalConnectTimeoutMs int `mapstructure:"local_connect_timeout_ms"` // LocalRequestTimeoutMs is the number of milliseconds to timeout HTTP requests // to the local app instance. If not set, no value is set, Envoy defaults are // respected (15s) LocalRequestTimeoutMs *int `mapstructure:"local_request_timeout_ms"` // LocalIdleTimeoutMs is the number of milliseconds to timeout HTTP streams // to the local app instance. If not set, no value is set, Envoy defaults are // respected (300s) LocalIdleTimeoutMs *int `mapstructure:"local_idle_timeout_ms"` // Protocol describes the service's protocol. Valid values are "tcp", // "http" and "grpc". Anything else is treated as tcp. This enables // protocol aware features like per-request metrics and connection // pooling, tracing, routing etc. Protocol string `mapstructure:"protocol"` // BindAddress overrides the address the proxy's listener binds to. This // enables proxies in network namespaces to bind to a different address // than the host address. BindAddress string `mapstructure:"bind_address"` // BindPort overrides the port the proxy's listener binds to. This // enable proxies in network namespaces to bind to a different port // than the host port being advertised. BindPort int `mapstructure:"bind_port"` // MaxInboundConnections is the maximum number of inbound connections to // the proxy. If not set, the default is 0 (no limit). MaxInboundConnections int `mapstructure:"max_inbound_connections"` // BalanceInboundConnections indicates how the proxy should attempt to distribute // connections across worker threads. Only used by envoy proxies. BalanceInboundConnections string `json:",omitempty" alias:"balance_inbound_connections"` }
ProxyConfig describes the keys we understand from Connect.Proxy.Config. Note that this only includes config keys that affects runtime config delivered by xDS. For Envoy config keys that affect bootstrap generation see command/connect/envoy/bootstrap_config.go.
func ParseProxyConfig ¶ added in v1.5.0
func ParseProxyConfig(m map[string]interface{}) (ProxyConfig, error)
ParseProxyConfig returns the ProxyConfig parsed from the an opaque map. If an error occurs during parsing it is returned along with the default config this allows caller to choose whether and how to report the error.
type ProxyConfigSource ¶ added in v1.13.0
type ProxyConfigSource interface {
Watch(id structs.ServiceID, nodeName string, token string) (<-chan *proxycfg.ConfigSnapshot, proxycfg.CancelFunc, error)
}
ProxyConfigSource is the interface xds.Server requires to consume proxy config updates.
type ResourceGenerator ¶ added in v1.10.0
type ResourceGenerator struct { Logger hclog.Logger CfgFetcher ConfigFetcher IncrementalXDS bool ProxyFeatures supportedProxyFeatures }
ResourceGenerator is associated with a single gRPC stream and creates xDS resources for a single client.
type Server ¶
type Server struct { NodeName string Logger hclog.Logger CfgSrc ProxyConfigSource ResolveToken ACLResolverFunc CfgFetcher ConfigFetcher SessionLimiter SessionLimiter // AuthCheckFrequency is how often we should re-check the credentials used // during a long-lived gRPC Stream after it has been initially established. // This is only used during idle periods of stream interactions (i.e. when // there has been no recent DiscoveryRequest). AuthCheckFrequency time.Duration // ResourceMapMutateFn exclusively exists for testing purposes. ResourceMapMutateFn func(resourceMap *xdscommon.IndexedResources) // contains filtered or unexported fields }
Server represents a gRPC server that can handle xDS requests from Envoy. All of it's public members must be set before the gRPC server is started.
A full description of the XDS protocol can be found at https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol
func NewServer ¶ added in v1.10.0
func NewServer( nodeName string, logger hclog.Logger, serverlessPluginEnabled bool, cfgMgr ProxyConfigSource, resolveToken ACLResolverFunc, cfgFetcher ConfigFetcher, limiter SessionLimiter, ) *Server
func (*Server) DeltaAggregatedResources ¶ added in v1.5.2
func (s *Server) DeltaAggregatedResources(stream ADSDeltaStream) error
DeltaAggregatedResources implements envoy_discovery_v3.AggregatedDiscoveryServiceServer
func (*Server) Register ¶ added in v1.12.0
Register the XDS server handlers to the given gRPC server.
func (*Server) StreamAggregatedResources
deprecated
type SessionLimiter ¶ added in v1.14.0
SessionLimiter is the interface exposed by limiter.SessionLimiter. We depend on an interface rather than the concrete type so we can mock it in tests.
type TestADSDeltaStream ¶ added in v1.10.0
type TestADSDeltaStream struct {
// contains filtered or unexported fields
}
TestADSDeltaStream mocks discovery.AggregatedDiscoveryService_DeltaAggregatedResourcesServer to allow testing the ADS handler.
func NewTestADSDeltaStream ¶ added in v1.10.0
func NewTestADSDeltaStream(t testing.T, ctx context.Context) *TestADSDeltaStream
func (*TestADSDeltaStream) Context ¶ added in v1.10.0
Context implements grpc.ServerStream as part of ADSDeltaStream
func (*TestADSDeltaStream) Recv ¶ added in v1.10.0
func (s *TestADSDeltaStream) Recv() (*envoy_discovery_v3.DeltaDiscoveryRequest, error)
Recv implements ADSDeltaStream
func (*TestADSDeltaStream) RecvMsg ¶ added in v1.10.0
func (s *TestADSDeltaStream) RecvMsg(m interface{}) error
RecvMsg implements grpc.ServerStream as part of ADSDeltaStream
func (*TestADSDeltaStream) Send ¶ added in v1.10.0
func (s *TestADSDeltaStream) Send(r *envoy_discovery_v3.DeltaDiscoveryResponse) error
Send implements ADSDeltaStream
func (*TestADSDeltaStream) SendHeader ¶ added in v1.10.0
SendHeader implements grpc.ServerStream as part of ADSDeltaStream
func (*TestADSDeltaStream) SendMsg ¶ added in v1.10.0
func (s *TestADSDeltaStream) SendMsg(m interface{}) error
SendMsg implements grpc.ServerStream as part of ADSDeltaStream
func (*TestADSDeltaStream) SetHeader ¶ added in v1.10.0
SetHeader implements grpc.ServerStream as part of ADSDeltaStream
func (*TestADSDeltaStream) SetSendErr ¶ added in v1.10.0
func (s *TestADSDeltaStream) SetSendErr(err error)
func (*TestADSDeltaStream) SetTrailer ¶ added in v1.10.0
SetTrailer implements grpc.ServerStream as part of ADSDeltaStream
type TestEnvoy ¶
type TestEnvoy struct { EnvoyVersion string // contains filtered or unexported fields }
TestEnvoy is a helper to simulate Envoy ADS requests.
func NewTestEnvoy ¶
NewTestEnvoy creates a TestEnvoy instance.
func (*TestEnvoy) SendDeltaReq ¶ added in v1.10.0
func (e *TestEnvoy) SendDeltaReq( t testing.T, typeURL string, req *envoy_discovery_v3.DeltaDiscoveryRequest, )
SendDeltaReq sends a delta request from the test server.
NOTE: the input request is mutated before sending by injecting the node.