Help us shape the future of Go! Take the 2026 Go Developer Survey

xds

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Mar 19, 2025 License: MPL-2.0 Imports: 470 Imported by: 0

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

View Source 
const (
	// 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
)
View Source 
const (
	UnnamedSubset = ""
)

Variables

View Source 
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.",
		},
		{
			Name: []string{"xds", "server", "streamsUnauthenticated"},
			Help: "Counts the number of active xDS streams handled by the server that are unauthenticated because ACLs are not enabled or ACL tokens were missing.",
		},
	}
	StatsCounters = []prometheus.CounterDefinition{
		{
			Name: []string{"xds", "server", "streamDrained"},
			Help: "Counts the number of xDS streams that are drained when rebalancing the load between servers.",
		},
	}
	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 

func CustomizeClusterName(clusterName string, chain *structs.CompiledDiscoveryChain) string

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 

type ADSDeltaStream = envoy_discovery_v3.AggregatedDiscoveryService_DeltaAggregatedResourcesServer

ADSDeltaStream is a shorter way of referring to this thing...

type ADSStream 

type ADSStream = envoy_discovery_v3.AggregatedDiscoveryService_StreamAggregatedResourcesServer

ADSStream is a shorter way of referring to this thing...

type ConfigFetcher 

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 JWTInfo 

type JWTInfo struct {
	// Provider issuer
	// this information is coming from the config entry
	Issuer string
	// Provider is the intention provider
	Provider *structs.IntentionJWTProvider
}

type PendingUpdate 

type PendingUpdate struct {
	Remove  bool
	Version string
}

type ProxyConfigSource 

type ProxyConfigSource interface {
	Watch(id structs.ServiceID, nodeName string, token string) (<-chan *proxycfg.ConfigSnapshot, limiter.SessionTerminatedChan, proxycfg.CancelFunc, error)
}

ProxyConfigSource is the interface xds.Server requires to consume proxy config updates.

type ResourceGenerator 

type ResourceGenerator struct {
	Logger         hclog.Logger
	CfgFetcher     ConfigFetcher
	IncrementalXDS bool

	ProxyFeatures xdscommon.SupportedProxyFeatures
}

ResourceGenerator is associated with a single gRPC stream and creates xDS resources for a single client.

func NewResourceGenerator 

func NewResourceGenerator(
	logger hclog.Logger,
	cfgFetcher ConfigFetcher,
	incrementalXDS bool,
) *ResourceGenerator

func (*ResourceGenerator) AllResourcesFromSnapshot 

func (g *ResourceGenerator) AllResourcesFromSnapshot(cfgSnap *proxycfg.ConfigSnapshot) (map[string][]proto.Message, error)

type Server 

type Server struct {
	NodeName     string
	Logger       hclog.Logger
	CfgSrc       ProxyConfigSource
	ResolveToken ACLResolverFunc
	CfgFetcher   ConfigFetcher

	// 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 

func NewServer(
	nodeName string,
	logger hclog.Logger,
	cfgMgr ProxyConfigSource,
	resolveTokenSecret ACLResolverFunc,
	cfgFetcher ConfigFetcher,
) *Server

func (*Server) DeltaAggregatedResources 

func (s *Server) DeltaAggregatedResources(stream ADSDeltaStream) error

DeltaAggregatedResources implements envoy_discovery_v3.AggregatedDiscoveryServiceServer

func (*Server) Register 

func (s *Server) Register(srv *grpc.Server)

Register the XDS server handlers to the given gRPC server.

func (*Server) StreamAggregatedResources deprecated 

func (s *Server) StreamAggregatedResources(stream ADSStream) error

StreamAggregatedResources implements envoy_discovery_v3.AggregatedDiscoveryServiceServer. This is the ADS endpoint which is the only xDS API we directly support for now.

Deprecated: use DeltaAggregatedResources instead

type TestADSDeltaStream 

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

TestADSDeltaStream mocks discovery.AggregatedDiscoveryService_DeltaAggregatedResourcesServer to allow testing the ADS handler.

func NewTestADSDeltaStream 

func NewTestADSDeltaStream(t testing.T, ctx context.Context) *TestADSDeltaStream

func (*TestADSDeltaStream) Context 

func (s *TestADSDeltaStream) Context() context.Context

Context implements grpc.ServerStream as part of ADSDeltaStream

func (*TestADSDeltaStream) Recv 

func (s *TestADSDeltaStream) Recv() (*envoy_discovery_v3.DeltaDiscoveryRequest, error)

Recv implements ADSDeltaStream

func (*TestADSDeltaStream) RecvMsg 

func (s *TestADSDeltaStream) RecvMsg(m interface{}) error

RecvMsg implements grpc.ServerStream as part of ADSDeltaStream

func (*TestADSDeltaStream) Send 

func (s *TestADSDeltaStream) Send(r *envoy_discovery_v3.DeltaDiscoveryResponse) error

Send implements ADSDeltaStream

func (*TestADSDeltaStream) SendHeader 

func (s *TestADSDeltaStream) SendHeader(metadata.MD) error

SendHeader implements grpc.ServerStream as part of ADSDeltaStream

func (*TestADSDeltaStream) SendMsg 

func (s *TestADSDeltaStream) SendMsg(m interface{}) error

SendMsg implements grpc.ServerStream as part of ADSDeltaStream

func (*TestADSDeltaStream) SetHeader 

func (s *TestADSDeltaStream) SetHeader(metadata.MD) error

SetHeader implements grpc.ServerStream as part of ADSDeltaStream

func (*TestADSDeltaStream) SetSendErr 

func (s *TestADSDeltaStream) SetSendErr(err error)

func (*TestADSDeltaStream) SetTrailer 

func (s *TestADSDeltaStream) SetTrailer(metadata.MD)

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 

func NewTestEnvoy(t testing.T, proxyID, token string) *TestEnvoy

NewTestEnvoy creates a TestEnvoy instance.

func (*TestEnvoy) Close 

func (e *TestEnvoy) Close() error

Close closes the client and cancels it's request context.

func (*TestEnvoy) SendDeltaReq 

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.

func (*TestEnvoy) SendDeltaReqACK 

func (e *TestEnvoy) SendDeltaReqACK(
	t testing.T,
	typeURL string,
	nonce uint64,
)

func (*TestEnvoy) SendDeltaReqNACK 

func (e *TestEnvoy) SendDeltaReqNACK(
	t testing.T,
	typeURL string,
	nonce uint64,
	errorDetail *status.Status,
)

func (*TestEnvoy) SetSendErr 

func (e *TestEnvoy) SetSendErr(err error)

Source Files

View all Source files

Directories

Path Synopsis

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.