README
¶
Endpoints Load Balancer
Overview
Package endpoints provides an implementation of a client-side load balancer that distributes client request across a collection of Kubernetes endpoints using a basic Round-robin algorithm. The endpoints load balancer does not operate in the data path and only manages a list of backends based on services defined in a Kubernetes cluster.
Use Cases
- Reduce latency by avoiding DNS lookups. Endpoints are returned as IP addresses and one or more ports.
- Reduce latency by avoiding extra hops. Client side load balancing enables direct pod to pod communication.
Drawbacks
- Increased load on the Kubernetes API server. Each client watches for changes and runs a reconciliation loop against the Kubernetes API.
- External dependency. Kubernetes service discovery works out of the box; using this library adds a new dependency.
Example Usage
See the example application for usage details.
Documentation
¶
Overview ¶
Package endpoints provides an implementation of a client-side load balancer that distributes client request across a collection of Kubernetes endpoints using a basic Round-robin algorithm.
The endpoints load balancer does not operate in the data path and only manages a list of backends based on services defined in a Kubernetes cluster.
Load balancers are created using a Config:
config := &endpoints.Config{
Namespace: namespace,
Service: service,
}
lb := endpoints.New(config)
Before an endpoints load balancer can be used endpoints must be synchronized from the Kubernetes API:
err := lb.SyncEndpoints()
Once the initial set of endpoints have been populated clients can call the Next method to get an endpoint:
endpoint, err := lb.Next()
// ...
url := fmt.Sprintf("http://%s:%s", endpoint.Host, endpoint.Port)
resp, err := c.Get(url)
// ...
Endpoints can be synchronized in the background:
err := lb.StartBackgroundSync()
Shutdown terminates a load balancer instance by stopping any background watches and reconciliation loops against the Kubernetes API server:
lb.Shutdown()
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( DefaultAPIAddr = "127.0.0.1:8001" DefaultNamespace = "default" )
var ( // ErrNoEndpoints is returned by LoadBalancer.Next calls when a named service // has no backends. ErrNoEndpoints = errors.New("endpoints: no endpoints available") // ErrMissingServiceName is returned by SyncEndpoints and StartBackgoundSync // when attempting to synchronize endpoints with a config that contains a // missing or blank service name. ErrMissingServiceName = errors.New("endpoints: missing service name") )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// APIAddr specifies the Kubernetes API "IP:port" address to use
// when synchronizing enpoints. If empty, DefaultAPIAddr is used.
APIAddr string
// The http.Client used to perform requests to the Kubernetes API.
// If nil, http.DefaultClient is used. Using the http.DefaultClient
// will require the use of kubectl running in proxy mode:
//
// $ kubectl proxy
// Starting to serve on 127.0.0.1:8001
//
// For more advanced communication schemes clients must provide an
// http.Client with a custom transport to handle any authentication
// requirements or custom behavior.
Client *http.Client
// ErrorLog specifies an optional logger for errors that occur when
// attempting to sync endpoints. If nil, logging goes to os.Stderr via
// the log package's standard logger.
ErrorLog *log.Logger
// The Kubernetes namespace to search for services.
// If empty, DefaultNamespace is used.
Namespace string
// RetryDelay is the amount of time to wait between API calls after an error
// occurs. If empty, DefaultRetryDelay is used.
RetryDelay time.Duration
// The Kubernetes service to monitor.
Service string
// SyncInterval is the amount of time between request to reconcile the list
// of endpoint backends from Kubernetes.
SyncInterval time.Duration
}
A Config structure is used to configure a LoadBalancer.
type LoadBalancer ¶
type LoadBalancer struct {
// contains filtered or unexported fields
}
LoadBalancer represents a Kubernetes endpoints round-robin load balancer.
func New ¶
func New(config *Config) *LoadBalancer
New configures and returns a new *LoadBalancer. The LoadBalancer endpoints list is populated by the Sync and StartBackgroundSync methods.
func (*LoadBalancer) Endpoints ¶
func (lb *LoadBalancer) Endpoints() []Endpoint
Endpoints returns a copy of the current set of endpoints.
func (*LoadBalancer) Next ¶
func (lb *LoadBalancer) Next() (Endpoint, error)
Next returns the next Kubernetes endpoint.
func (*LoadBalancer) Shutdown ¶
func (lb *LoadBalancer) Shutdown() error
Shutdown shuts down the loadbalancer. Shutdown works by stopping any watches and reconciliation loops against the Kubernetes API server.
func (*LoadBalancer) StartBackgroundSync ¶
func (lb *LoadBalancer) StartBackgroundSync() error
StartBackgroundSync starts a watch loop that synchronizes the list of endpoints asynchronously.
func (*LoadBalancer) SyncEndpoints ¶
func (lb *LoadBalancer) SyncEndpoints() error
SyncEndpoints syncs the endpoints for the configured Kubernetes service.
Source Files
Directories