router

Documentation

Overview

Package servers provides a Manager interface for Manager managed metadata.Server objects. The servers package manages servers from a Consul client's perspective (i.e. a list of servers that a client talks with for RPCs). The servers package does not provide any API guarantees and should be called only by `hashicorp/consul`.

Index

• func FloodJoins(logger hclog.Logger, addrFn FloodAddrFn, localDatacenter string, ...)
• func HandleSerfEvents(logger hclog.Logger, router *Router, areaID types.AreaID, ...)
• type FloodAddrFn
• type Manager
  • func New(logger hclog.Logger, shutdownCh chan struct{}, clusterInfo ManagerSerfCluster, ...) (m *Manager)
  • func (m *Manager) AddServer(s *metadata.Server)
  • func (m *Manager) CheckServers(fn func(srv *metadata.Server) bool)
  • func (m *Manager) FindServer() *metadata.Server
  • func (m *Manager) IsOffline() bool
  • func (m *Manager) NotifyFailedServer(s *metadata.Server)
  • func (m *Manager) NumServers() int
  • func (m *Manager) RebalanceServers()
  • func (m *Manager) RemoveServer(s *metadata.Server)
  • func (m *Manager) ResetRebalanceTimer()
  • func (m *Manager) Run()
  • func (m *Manager) UpdateTLS(useTLS bool)
• type ManagerSerfCluster
• type NoOpServerTracker
  • func (NoOpServerTracker) AddServer(*metadata.Server)
  • func (NoOpServerTracker) NewRebalancer(string) func()
  • func (NoOpServerTracker) RemoveServer(*metadata.Server)
• type Pinger
• type Rebalancer
• type Router
  • func NewRouter(logger hclog.Logger, localDatacenter, serverName string, tracker ServerTracker) *Router
  • func (r *Router) AddArea(areaID types.AreaID, cluster RouterSerfCluster, pinger Pinger) error
  • func (r *Router) AddServer(areaID types.AreaID, s *metadata.Server) error
  • func (r *Router) CheckServers(dc string, fn func(srv *metadata.Server) bool)
  • func (r *Router) FailServer(areaID types.AreaID, s *metadata.Server) error
  • func (r *Router) FindLANRoute() (*Manager, *metadata.Server)
  • func (r *Router) FindLANServer() *metadata.Server
  • func (r *Router) FindRoute(datacenter string) (*Manager, *metadata.Server, bool)
  • func (r *Router) GetDatacenterMaps() ([]structs.DatacenterMap, error)
  • func (r *Router) GetDatacenters() []string
  • func (r *Router) GetDatacentersByDistance() ([]string, error)
  • func (r *Router) GetLANManager() *Manager
  • func (r *Router) GetRemoteDatacenters(local string) []string
  • func (r *Router) GetServerMetadataByAddr(dc, addr string) *metadata.Server
  • func (r *Router) HasDatacenter(dc string) bool
  • func (r *Router) RemoveArea(areaID types.AreaID) error
  • func (r *Router) RemoveServer(areaID types.AreaID, s *metadata.Server) error
  • func (r *Router) Shutdown()
  • func (r *Router) TLSEnabled(areaID types.AreaID) (bool, error)
• type RouterSerfCluster
• type ServerTracker

Functions

func FloodJoins

func FloodJoins(logger hclog.Logger, addrFn FloodAddrFn,
	localDatacenter string, srcSerf *serf.Serf, dstSerf *serf.Serf)

FloodJoins attempts to make sure all Consul servers in the src Serf instance are joined in the dst Serf instance. It assumes names in the src area are of the form <node> and those in the dst area are of the form <node>.<dc> as is done for WAN and general network areas in Consul Enterprise.

func HandleSerfEvents

func HandleSerfEvents(logger hclog.Logger, router *Router, areaID types.AreaID, shutdownCh <-chan struct{}, eventCh <-chan serf.Event)

HandleSerfEvents is a long-running goroutine that pushes incoming events from a Serf manager's channel into the given router. This will return when the shutdown channel is closed.

Types

type FloodAddrFn

type FloodAddrFn func(*metadata.Server) (string, error)

FloodAddrPortFn gets the address and port to use for a given server when flood-joining. This will return false if it doesn't have one.

type Manager

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

func New

func New(logger hclog.Logger, shutdownCh chan struct{}, clusterInfo ManagerSerfCluster, connPoolPinger Pinger, serverName string, rb Rebalancer) (m *Manager)

New is the only way to safely create a new Manager struct.

func (*Manager) AddServer

func (m *Manager) AddServer(s *metadata.Server)

AddServer takes out an internal write lock and adds a new server. If the server is not known, appends the server to the list. The new server will begin seeing use after the rebalance timer fires or enough servers fail organically. If the server is already known, merge the new server details.

func (*Manager) CheckServers

func (m *Manager) CheckServers(fn func(srv *metadata.Server) bool)

func (*Manager) FindServer

func (m *Manager) FindServer() *metadata.Server

FindServer takes out an internal "read lock" and searches through the list of servers to find a "healthy" server. If the server is actually unhealthy, we rely on Serf to detect this and remove the node from the server list. If the server at the front of the list has failed or fails during an RPC call, it is rotated to the end of the list. If there are no servers available, return nil.

func (*Manager) IsOffline

func (m *Manager) IsOffline() bool

IsOffline checks to see if all the known servers have failed their ping test during the last rebalance.

func (*Manager) NotifyFailedServer

func (m *Manager) NotifyFailedServer(s *metadata.Server)

NotifyFailedServer marks the passed in server as "failed" by rotating it to the end of the server list.

func (*Manager) NumServers

func (m *Manager) NumServers() int

NumServers takes out an internal "read lock" and returns the number of servers. numServers includes both healthy and unhealthy servers.

func (*Manager) RebalanceServers

func (m *Manager) RebalanceServers()

RebalanceServers shuffles the list of servers on this metadata. The server at the front of the list is selected for the next RPC. RPC calls that fail for a particular server are rotated to the end of the list. This method reshuffles the list periodically in order to redistribute work across all known consul servers (i.e. guarantee that the order of servers in the server list is not positively correlated with the age of a server in the Consul cluster). Periodically shuffling the server list prevents long-lived clients from fixating on long-lived servers.

Unhealthy servers are removed when serf notices the server has been deregistered. Before the newly shuffled server list is saved, the new remote endpoint is tested to ensure its responsive.

func (*Manager) RemoveServer

func (m *Manager) RemoveServer(s *metadata.Server)

RemoveServer takes out an internal write lock and removes a server from the server list.

func (*Manager) ResetRebalanceTimer

func (m *Manager) ResetRebalanceTimer()

ResetRebalanceTimer resets the rebalance timer. This method exists for testing and should not be used directly.

func (*Manager) Run

func (m *Manager) Run()

Run periodically shuffles the list of servers to evenly distribute load. Run exits when shutdownCh is closed.

When a server fails it is moved to the end of the list, and new servers are appended to the end of the list. Run ensures that load is distributed evenly to all servers by randomly shuffling the list.

func (*Manager) UpdateTLS

func (m *Manager) UpdateTLS(useTLS bool)

UpdateTLS updates the TLS setting for the servers in this manager

type ManagerSerfCluster

type ManagerSerfCluster interface {
	NumNodes() int
}

ManagerSerfCluster is an interface wrapper around Serf in order to make this easier to unit test.

type NoOpServerTracker

type NoOpServerTracker struct{}

NoOpServerTracker is a ServerTracker that does nothing. Used when gRPC is not enabled.

func (NoOpServerTracker) AddServer

func (NoOpServerTracker) AddServer(*metadata.Server)

AddServer does nothing

func (NoOpServerTracker) NewRebalancer

func (NoOpServerTracker) NewRebalancer(string) func()

Rebalance does nothing

func (NoOpServerTracker) RemoveServer

func (NoOpServerTracker) RemoveServer(*metadata.Server)

RemoveServer does nothing

type Pinger

type Pinger interface {
	Ping(dc, nodeName string, addr net.Addr) (bool, error)
}

Pinger is an interface wrapping client.ConnPool to prevent a cyclic import dependency.

type Rebalancer

type Rebalancer func()

Rebalancer is called periodically to re-order the servers so that the load on the servers is evenly balanced.

type Router

type Router struct {

	// This top-level lock covers all the internal state.
	sync.RWMutex
	// contains filtered or unexported fields
}

Router keeps track of a set of network areas and their associated Serf membership of Consul servers. It then indexes this by datacenter to provide healthy routes to servers by datacenter.

func NewRouter

func NewRouter(logger hclog.Logger, localDatacenter, serverName string, tracker ServerTracker) *Router

NewRouter returns a new Router with the given configuration.

func (*Router) AddArea

func (r *Router) AddArea(areaID types.AreaID, cluster RouterSerfCluster, pinger Pinger) error

AddArea registers a new network area with the router.

func (*Router) AddServer

func (r *Router) AddServer(areaID types.AreaID, s *metadata.Server) error

AddServer should be called whenever a new server joins an area. This is typically hooked into the Serf event handler area for this area.

func (*Router) CheckServers

func (r *Router) CheckServers(dc string, fn func(srv *metadata.Server) bool)

CheckServers returns thwo things 1. bool to indicate whether any servers were processed 2. error if any propagated from the fn

The fn called should return a bool indicating whether checks should continue and an error If an error is returned then checks will stop immediately

func (*Router) FailServer

func (r *Router) FailServer(areaID types.AreaID, s *metadata.Server) error

FailServer should be called whenever a server is failed in an area. This is typically hooked into the Serf event handler area for this area. We will immediately shift traffic away from this server, but it will remain in the list of servers.

func (*Router) FindLANRoute

func (r *Router) FindLANRoute() (*Manager, *metadata.Server)

FindLANRoute returns a healthy server within the local datacenter. In some cases this may return a best-effort unhealthy server that can be used for a connection attempt. If any problem occurs with the given server, the caller should feed that back to the manager associated with the server, which is also returned, by calling NotifyFailedServer().

func (*Router) FindLANServer

func (r *Router) FindLANServer() *metadata.Server

FindLANServer will look for a server in the local datacenter. This function may return a nil value if no server is available.

func (*Router) FindRoute

func (r *Router) FindRoute(datacenter string) (*Manager, *metadata.Server, bool)

FindRoute returns a healthy server with a route to the given datacenter. The Boolean return parameter will indicate if a server was available. In some cases this may return a best-effort unhealthy server that can be used for a connection attempt. If any problem occurs with the given server, the caller should feed that back to the manager associated with the server, which is also returned, by calling NotifyFailedServer().

func (*Router) GetDatacenterMaps

func (r *Router) GetDatacenterMaps() ([]structs.DatacenterMap, error)

GetDatacenterMaps returns a structure with the raw network coordinates of each known server, organized by datacenter and network area.

func (*Router) GetDatacenters

func (r *Router) GetDatacenters() []string

GetDatacenters returns a list of datacenters known to the router, sorted by name.

func (*Router) GetDatacentersByDistance

func (r *Router) GetDatacentersByDistance() ([]string, error)

GetDatacentersByDistance returns a list of datacenters known to the router, sorted by median RTT from this server to the servers in each datacenter. If there are multiple areas that reach a given datacenter, this will use the lowest RTT for the sort.

func (*Router) GetLANManager

func (r *Router) GetLANManager() *Manager

GetLANManager returns the Manager for the LAN area and the local datacenter

func (*Router) GetRemoteDatacenters

func (r *Router) GetRemoteDatacenters(local string) []string

GetRemoteDatacenters returns a list of remote datacenters known to the router, sorted by name.

func (*Router) GetServerMetadataByAddr

func (r *Router) GetServerMetadataByAddr(dc, addr string) *metadata.Server

GetServerMetadataByAddr returns server metadata by dc and address. If it didn't find anything, nil is returned.

func (*Router) HasDatacenter

func (r *Router) HasDatacenter(dc string) bool

HasDatacenter checks whether dc is defined in WAN

func (*Router) RemoveArea

func (r *Router) RemoveArea(areaID types.AreaID) error

RemoveArea removes an existing network area from the router.

func (*Router) RemoveServer

func (r *Router) RemoveServer(areaID types.AreaID, s *metadata.Server) error

RemoveServer should be called whenever a server is removed from an area. This is typically hooked into the Serf event handler area for this area.

func (*Router) Shutdown

func (r *Router) Shutdown()

Shutdown removes all areas from the router, which stops all their respective managers. No new areas can be added after the router is shut down.

func (*Router) TLSEnabled

func (r *Router) TLSEnabled(areaID types.AreaID) (bool, error)

Returns whether TLS is enabled for the given area ID

type RouterSerfCluster

type RouterSerfCluster interface {
	NumNodes() int
	Members() []serf.Member
	GetCoordinate() (*coordinate.Coordinate, error)
	GetCachedCoordinate(name string) (*coordinate.Coordinate, bool)
}

RouterSerfCluster is an interface wrapper around Serf in order to make this easier to unit test.

type ServerTracker

type ServerTracker interface {
	NewRebalancer(dc string) func()
	AddServer(*metadata.Server)
	RemoveServer(*metadata.Server)
}

ServerTracker is called when Router is notified of a server being added or removed.