Documentation
¶
Overview ¶
Package xdsclient implements a full fledged gRPC client for the xDS API used by the xds resolver and balancer implementations.
Index ¶
- Constants
- Variables
- func DumpResources() *v3statuspb.ClientStatusResponse
- func SetClient(state resolver.State, c XDSClient) resolver.State
- type ClusterRequestsCounter
- type OptionsForTesting
- type Pool
- func (p *Pool) BootstrapConfigForTesting() *bootstrap.Config
- func (p *Pool) DumpResources() *v3statuspb.ClientStatusResponse
- func (p *Pool) GetClientForTesting(name string) (XDSClient, func(), error)
- func (p *Pool) NewClient(name string, metricsRecorder estats.MetricsRecorder) (XDSClient, func(), error)
- func (p *Pool) NewClientForTesting(opts OptionsForTesting) (XDSClient, func(), error)
- func (p *Pool) NewClientWithConfig(name string, metricsRecorder estats.MetricsRecorder, config *bootstrap.Config) (XDSClient, func(), error)
- func (p *Pool) SetFallbackBootstrapConfig(config *bootstrap.Config)
- func (p *Pool) UnsetBootstrapConfigForTesting()
- type XDSClient
Constants ¶
const ( // NameForServer represents the value to be passed as name when creating an xDS // client from xDS-enabled gRPC servers. This is a well-known dedicated key // value, and is defined in gRFC A71. NameForServer = "#server" )
Variables ¶
var ( // DefaultPool is the default pool for xDS clients. It is created at init // time and reads bootstrap configuration from env vars to create the xDS // client. DefaultPool = &Pool{ clients: make(map[string]*clientImpl), getConfiguration: sync.OnceValues(bootstrap.GetConfiguration), } )
Functions ¶
func DumpResources ¶
func DumpResources() *v3statuspb.ClientStatusResponse
DumpResources returns the status and contents of all xDS resources. It uses xDS clients from the default pool.
Types ¶
type ClusterRequestsCounter ¶
type ClusterRequestsCounter struct {
ClusterName string
EDSServiceName string
// contains filtered or unexported fields
}
ClusterRequestsCounter is used to track the total inflight requests for a service with the provided name.
func GetClusterRequestsCounter ¶
func GetClusterRequestsCounter(clusterName, edsServiceName string) *ClusterRequestsCounter
GetClusterRequestsCounter returns the ClusterRequestsCounter with the provided serviceName. If one does not exist, it creates it.
func (*ClusterRequestsCounter) EndRequest ¶
func (c *ClusterRequestsCounter) EndRequest()
EndRequest ends a request for a service, decrementing its number of requests by 1.
func (*ClusterRequestsCounter) StartRequest ¶
func (c *ClusterRequestsCounter) StartRequest(max uint32) error
StartRequest starts a request for a cluster, incrementing its number of requests by 1. Returns an error if the max number of requests is exceeded.
type OptionsForTesting ¶
type OptionsForTesting struct {
// Name is a unique name for this xDS client.
Name string
// WatchExpiryTimeout is the timeout for xDS resource watch expiry. If
// unspecified, uses the default value used in non-test code.
WatchExpiryTimeout time.Duration
// StreamBackoffAfterFailure is the backoff function used to determine the
// backoff duration after stream failures.
// If unspecified, uses the default value used in non-test code.
StreamBackoffAfterFailure func(int) time.Duration
// MetricsRecorder is the metrics recorder the xDS Client will use. If
// unspecified, uses a no-op MetricsRecorder.
MetricsRecorder estats.MetricsRecorder
// Config is the xDS bootstrap configuration that will be used to initialize
// the client. If unset, the client will use the config provided by env
// variables.
Config *bootstrap.Config
}
OptionsForTesting contains options to configure xDS client creation for testing purposes only.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool represents a pool of xDS clients that share the same bootstrap configuration.
func NewPool ¶
NewPool creates a new xDS client pool with the given bootstrap config.
If a nil bootstrap config is passed and SetFallbackBootstrapConfig is not called before a call to NewClient, the latter will fail. i.e. if there is an attempt to create an xDS client from the pool without specifying bootstrap configuration (either at pool creation time or by setting the fallback bootstrap configuration), xDS client creation will fail.
func (*Pool) BootstrapConfigForTesting ¶
BootstrapConfigForTesting returns the bootstrap configuration used by the pool. The caller should not mutate the returned config.
To be used only for testing purposes.
func (*Pool) DumpResources ¶
func (p *Pool) DumpResources() *v3statuspb.ClientStatusResponse
DumpResources returns the status and contents of all xDS resources.
func (*Pool) GetClientForTesting ¶
GetClientForTesting returns an xDS client created earlier using the given name from the pool. If the client with the given name doesn't already exist, it returns an error.
The second return value represents a close function which the caller is expected to invoke once they are done using the client. It is safe for the caller to invoke this close function multiple times.
Testing Only ¶
This function should ONLY be used for testing purposes.
func (*Pool) NewClient ¶
func (p *Pool) NewClient(name string, metricsRecorder estats.MetricsRecorder) (XDSClient, func(), error)
NewClient returns an xDS client with the given name from the pool. If the client doesn't already exist, it creates a new xDS client and adds it to the pool.
The second return value represents a close function which the caller is expected to invoke once they are done using the client. It is safe for the caller to invoke this close function multiple times.
func (*Pool) NewClientForTesting ¶
func (p *Pool) NewClientForTesting(opts OptionsForTesting) (XDSClient, func(), error)
NewClientForTesting returns an xDS client configured with the provided options from the pool. If the client doesn't already exist, it creates a new xDS client and adds it to the pool.
The second return value represents a close function which the caller is expected to invoke once they are done using the client. It is safe for the caller to invoke this close function multiple times.
Testing Only ¶
This function should ONLY be used for testing purposes.
func (*Pool) NewClientWithConfig ¶ added in v1.77.0
func (p *Pool) NewClientWithConfig(name string, metricsRecorder estats.MetricsRecorder, config *bootstrap.Config) (XDSClient, func(), error)
NewClientWithConfig returns an xDS client with the given name from the pool. If the client doesn't already exist, it creates a new xDS client and adds it to the pool.
The second return value represents a close function which the caller is expected to invoke once they are done using the client. It is safe for the caller to invoke this close function multiple times.
func (*Pool) SetFallbackBootstrapConfig ¶
SetFallbackBootstrapConfig is used to specify a bootstrap configuration that will be used as a fallback when the bootstrap environment variables are not defined. TODO(i/8661): remove SetFallbackBootstrapConfig function.
func (*Pool) UnsetBootstrapConfigForTesting ¶
func (p *Pool) UnsetBootstrapConfigForTesting()
UnsetBootstrapConfigForTesting unsets the bootstrap configuration used by the pool.
To be used only for testing purposes.
type XDSClient ¶
type XDSClient interface {
// WatchResource uses xDS to discover the resource associated with the
// provided resource name. The resource type implementation determines how
// xDS responses are are deserialized and validated, as received from the
// xDS management server. Upon receipt of a response from the management
// server, an appropriate callback on the watcher is invoked.
//
// Most callers will not have a need to use this API directly. They will
// instead use a resource-type-specific wrapper API provided by the relevant
// resource type implementation.
//
//
// During a race (e.g. an xDS response is received while the user is calling
// cancel()), there's a small window where the callback can be called after
// the watcher is canceled. Callers need to handle this case.
WatchResource(rType xdsresource.Type, resourceName string, watcher xdsresource.ResourceWatcher) (cancel func())
// WatchResourceV2 matches the API of the external xdsclient interface.
// Once all users of xdsclient have been moved to this watch API, we can
// remove the WatchResource API above, and rename this to WatchResource.
WatchResourceV2(typeURL, resourceName string, watcher xdsclient.ResourceWatcher) (cancel func())
ReportLoad(*bootstrap.ServerConfig) (*lrsclient.LoadStore, func(context.Context))
BootstrapConfig() *bootstrap.Config
}
XDSClient is a full fledged gRPC client which queries a set of discovery APIs (collectively termed as xDS) on a remote management server, to discover various dynamic resources.
func FromResolverState ¶
FromResolverState returns the Client from state, or nil if not present.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package internal contains functionality internal to the xdsclient package.
|
Package internal contains functionality internal to the xdsclient package. |
|
Package xdslbregistry provides a registry of converters that convert proto from load balancing configuration, defined by the xDS API spec, to JSON load balancing configuration.
|
Package xdslbregistry provides a registry of converters that convert proto from load balancing configuration, defined by the xDS API spec, to JSON load balancing configuration. |
|
converter
Package converter provides converters to convert proto load balancing configuration, defined by the xDS API spec, to JSON load balancing configuration.
|
Package converter provides converters to convert proto load balancing configuration, defined by the xDS API spec, to JSON load balancing configuration. |
|
Package xdsresource implements the xDS data model layer.
|
Package xdsresource implements the xDS data model layer. |
|
version
Package version defines constants to distinguish between supported xDS API versions.
|
Package version defines constants to distinguish between supported xDS API versions. |