cluster

Documentation

Overview

Package cluster enables an agent-wide cluster mechanism which subsystems can use to determine ownership of some key.

Index

• Variables
• type Clusterer
  • func New(log log.Logger, reg prometheus.Registerer, clusterEnabled bool, ...) (*Clusterer, error)
  • func (c *Clusterer) Start(ctx context.Context) error
  • func (c *Clusterer) Stop() error
• type GossipConfig
  • func (c *GossipConfig) ApplyDefaults(defaultPort int) error
• type GossipNode
  • func NewGossipNode(l log.Logger, reg prometheus.Registerer, cli *http.Client, c *GossipConfig) (*GossipNode, error)
  • func (n *GossipNode) ChangeState(ctx context.Context, to peer.State) error
  • func (n *GossipNode) CurrentState() peer.State
  • func (n *GossipNode) Handler() (string, http.Handler)
  • func (n *GossipNode) Lookup(key shard.Key, numOwners int, op shard.Op) ([]peer.Peer, error)
  • func (n *GossipNode) Observe(o ckit.Observer)
  • func (n *GossipNode) Peers() []peer.Peer
  • func (n *GossipNode) Start() (err error)
  • func (n *GossipNode) Stop() error
• type Node
  • func NewLocalNode(selfAddr string) Node

Variables

var DefaultGossipConfig = GossipConfig{
	AdvertiseInterfaces: advertise.DefaultInterfaces,
}

DefaultGossipConfig holds default GossipConfig options.

Types

type Clusterer

type Clusterer struct {
	Node Node
}

Clusterer implements the behavior required for operating Flow controllers in a distributed fashion.

func New

func New(log log.Logger, reg prometheus.Registerer, clusterEnabled bool, listenAddr, advertiseAddr, joinAddr string) (*Clusterer, error)

New creates a Clusterer.

func (*Clusterer) Start

func (c *Clusterer) Start(ctx context.Context) error

Start starts the node. For the localNode implementation, this is a no-op. For the gossipNode implementation, Start will attempt to connect to the configured list of peers; if this fails it will fall back to bootstrapping a new cluster of its own.

func (*Clusterer) Stop

func (c *Clusterer) Stop() error

Stop stops the Clusterer.

type GossipConfig

type GossipConfig struct {
	// Name of the node within the cluster. Must be unique cluster-wide.
	NodeName string

	// host:port address to advertise to peers to connect to. When unset, the
	// first discovered IP from AdvertiseInterfaces will be used to find.
	AdvertiseAddr string

	// Slice of interface names to infer an advertise IP from. Must be set if
	// AdvertiseAddr is unset.
	AdvertiseInterfaces flagext.StringSlice

	// List of one or more host:port peer addresses to connect to. Mutually
	// exclusive with DiscoverPeers.
	//
	// If an agent connects to no peers, it will form a one-node cluster until a
	// peer connects to it explicitly.
	JoinPeers flagext.StringSlice

	// Discover peers to connect to using go-discover. Mutually exclusive with
	// JoinPeers.
	DiscoverPeers string
}

GossipConfig controls clustering of Agents through gRPC-based gossip. GossipConfig cannot be changed at runtime.

func (*GossipConfig) ApplyDefaults

func (c *GossipConfig) ApplyDefaults(defaultPort int) error

ApplyDefaults mutates c with default settings applied. defaultPort is added as the default port for addresses that do not have port numbers assigned.

An error will be returned if the configuration is invalid or if an error occurred while applying defaults.

type GossipNode

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

GossipNode is a Node which uses gRPC and gossip to discover peers.

func NewGossipNode

func NewGossipNode(l log.Logger, reg prometheus.Registerer, cli *http.Client, c *GossipConfig) (*GossipNode, error)

NewGossipNode creates an unstarted GossipNode. The GossipNode will use the passed http.Client to create a new HTTP/2-compatible Transport that can communicate with other nodes over HTTP/2. GossipConfig is expected to be valid and have already had ApplyDefaults called on it.

GossipNode operations are unavailable until the node is started.

func (*GossipNode) ChangeState

func (n *GossipNode) ChangeState(ctx context.Context, to peer.State) error

ChangeState changes the state of n. ChangeState will block until the state change has been received by another node; cancel the context to stop waiting. ChangeState will fail if the current state cannot move to the target state.

Nodes must be a StateParticipant to receive writes.

func (*GossipNode) CurrentState

func (n *GossipNode) CurrentState() peer.State

CurrentState returns the current state of the node. Note that other nodes may have an older view of the state while a state change propagates throughout the cluster.

func (*GossipNode) Handler

func (n *GossipNode) Handler() (string, http.Handler)

Handler returns the base route and HTTP handlers to register for this node.

func (*GossipNode) Lookup

func (n *GossipNode) Lookup(key shard.Key, numOwners int, op shard.Op) ([]peer.Peer, error)

Lookup implements Node and returns numOwners Peers that are responsible for key. Only peers in StateParticipant are considered during a lookup; if no peers are in StateParticipant, the Lookup will fail.

func (*GossipNode) Observe

func (n *GossipNode) Observe(o ckit.Observer)

Observe registers o to be informed when the cluster changes, including peers appearing, disappearing, or changing state.

Calls will have to filter events if they are only interested in a subset of changes.

func (*GossipNode) Peers

func (n *GossipNode) Peers() []peer.Peer

Peers returns the current set of Peers.

func (*GossipNode) Start

func (n *GossipNode) Start() (err error)

Start starts the node. Start will connect to peers if configured to do so.

Start must only be called after the gRPC server is running, otherwise Start will block forever.

func (*GossipNode) Stop

func (n *GossipNode) Stop() error

Stop leaves the cluster and terminates n. n cannot be re-used after stopping.

It is advisable to ChangeState to StateTerminating and StateGone before stopping so the local node has an opportunity to move work to other nodes.

type Node

type Node interface {
	// Lookup determines the set of replicationFactor owners for a given key.
	// peer.Peer.Self can be used to determine if the local node is the owner,
	// allowing for short-circuiting logic to connect directly to the local node
	// instead of using the network.
	//
	// Callers can use github.com/grafana/ckit/shard.StringKey or
	// shard.NewKeyBuilder to create a key.
	Lookup(key shard.Key, replicationFactor int, op shard.Op) ([]peer.Peer, error)

	// Observe registers an Observer to receive notifications when the set of
	// Peers for a Node changes.
	Observe(ckit.Observer)

	// Peers returns the current set of peers for a Node.
	Peers() []peer.Peer

	Handler() (string, http.Handler)
}

Node is a read-only view of a cluster node.

func NewLocalNode

func NewLocalNode(selfAddr string) Node

NewLocalNode returns a Node which forms a single-node cluster and never connects to other nodes.

selfAddr is the address for a Node to use to connect to itself over gRPC.