clients

Documentation

Overview

Package clients provides implementations of the xDS and LRS clients, enabling applications to communicate with xDS management servers and report load.

xDS Client

The xDS client allows applications to:

• Create client instances with in-memory configurations.
• Register watches for named resources.
• Receive resources via the ADS (Aggregated Discovery Service) stream.

This enables applications to dynamically discover and configure resources such as listeners, routes, clusters, and endpoints from an xDS management server.

LRS Client

The LRS (Load Reporting Service) client allows applications to report load data to an LRS server via the LRS stream. This data can be used for monitoring, traffic management, and other purposes.

Experimental

NOTICE: This package is EXPERIMENTAL and may be changed or removed in a later release.

See [README](https://github.com/grpc/grpc-go/tree/master/xds/clients/README.md).

Index

• type Authority
• type Locality
• type Node
• type ServerConfig
  • func (sc *ServerConfig) String() string
• type Stream
• type Transport
• type TransportBuilder

Types

type Authority

type Authority struct {
	// XDSServers contains the list of server configurations for this authority.
	XDSServers []ServerConfig

	// Extensions can be populated with arbitrary data to be passed to the xDS
	// Client's user specific implementations. This field can be used to
	// provide additional configuration or context specific to the user's
	// needs.
	//
	// The xDS and LRS clients do not interpret the contents of this field. It
	// is the responsibility of the user's implementations to handle and
	// interpret these extensions.
	Extensions any
}

Authority contains configuration for an xDS control plane authority.

type Locality

type Locality struct {
	// Region is the region of the xDS client application.
	Region string
	// Zone is the area within a region.
	Zone string
	// SubZone is the further subdivision within a zone.
	SubZone string
}

Locality represents the location of the xDS client application.

type Node

type Node struct {
	// ID is a string identifier of the application.
	ID string
	// Cluster is the name of the cluster the application belongs to.
	Cluster string
	// Locality is the location of the application including region, zone,
	// sub-zone.
	Locality Locality
	// Metadata provides additional context about the application by associating
	// arbitrary key-value pairs with it.
	Metadata any
	// UserAgentName is the user agent name of application.
	UserAgentName string
	// UserAgentVersion is the user agent version of application.
	UserAgentVersion string
	// contains filtered or unexported fields
}

Node represents the identity of the xDS client, allowing management servers to identify the source of xDS requests.

type ServerConfig

type ServerConfig struct {
	// ServerURI is the target URI of the xDS management server.
	ServerURI string

	// IgnoreResourceDeletion is a server feature which if set to true,
	// indicates that resource deletion errors can be ignored and cached
	// resource data can be used.
	//
	// This will be removed in the future once we implement gRFC A88
	// and two new fields FailOnDataErrors and
	// ResourceTimerIsTransientError will be introduced.
	IgnoreResourceDeletion bool

	// Extensions can be populated with arbitrary data to be passed to the
	// [TransportBuilder] and/or xDS Client's ResourceType implementations.
	// This field can be used to provide additional configuration or context
	// specific to the user's needs.
	//
	// The xDS and LRS clients do not interpret the contents of this field.
	// It is the responsibility of the user's custom [TransportBuilder] and/or
	// ResourceType implementations to handle and interpret these extensions.
	//
	// For example, a custom [TransportBuilder] might use this field to
	// configure a specific security credentials.
	//
	// Note: For custom types used in Extensions, ensure an Equal(any) bool
	// method is implemented for equality checks on ServerConfig.
	Extensions any
}

ServerConfig holds settings for connecting to an xDS management server.

func (*ServerConfig) String

func (sc *ServerConfig) String() string

String returns a string representation of the ServerConfig.

WARNING: This method is primarily intended for logging and testing purposes. The output returned by this method is not guaranteed to be stable and may change at any time. Do not rely on it for production use.

type Stream

type Stream interface {
	// Send sends the provided message on the stream.
	Send([]byte) error

	// Recv blocks until the next message is received on the stream.
	Recv() ([]byte, error)
}

Stream provides methods to send and receive messages on a stream. Messages are represented as a byte slice ([]byte).

type Transport

type Transport interface {
	// NewStream creates a new streaming call to the xDS server for the
	// specified RPC method name. The returned Stream interface can be used
	// to send and receive messages on the stream.
	NewStream(context.Context, string) (Stream, error)

	// Close closes the Transport.
	Close() error
}

Transport provides the functionality to communicate with an xDS server using streaming calls.

type TransportBuilder

type TransportBuilder interface {
	// Build creates a new [Transport] instance to the xDS server based on the
	// provided ServerConfig.
	Build(ServerConfig ServerConfig) (Transport, error)
}

TransportBuilder provides the functionality to create a communication channel to an xDS management server.