endpoints

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

• Variables
• type Config
• type Endpoint
• type LoadBalancer
  • func New(config *Config) *LoadBalancer
  • func (lb *LoadBalancer) Endpoints() []Endpoint
  • func (lb *LoadBalancer) Next() (Endpoint, error)
  • func (lb *LoadBalancer) Shutdown() error
  • func (lb *LoadBalancer) StartBackgroundSync() error
  • func (lb *LoadBalancer) SyncEndpoints() error
• type SyncError
  • func (e *SyncError) Error() string

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")
)

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 Endpoint

type Endpoint struct {
	Host  string
	Port  string
	Ports map[string]string
}

Endpoint holds a Kubernetes endpoint.

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.

type SyncError

type SyncError struct {
	URL     string // URL used
	Message string // description of the error
	Code    int    // remote status code
}

SyncError records an error during an Kubernetes API call and the HTTP request that caused it.

func (*SyncError) Error

func (e *SyncError) Error() string