skipper: Index | Files | Directories

package swarm

import ""

Package swarm implements the exchange of information between Skipper instances using a gossip protocol called SWIM. This aims at a solution that can work in a context of multiple readers and writers, with the guarantee of low latency, weakly consistent data, from which derives the decision to use such protocol. As an example the implementation of the filter clusterRatelimit uses the swarm data exchange to have a global state of current requests.

A swarm instance needs to find some of it's peers before joining the cluster. Current implementations to find peers are swarmKubernetes to find skipper instances running in a Kubernetes cluster and swarmFake for testing.

Background information:

The current skipper implementation uses hashicorp's memberlist,, which is an implementation of the swim protocol. You can find a detailed paper at

Quote from a nice overview

The SWIM or the Scalable Weakly-consistent Infection-style process
group Membership protocol is a protocol used for maintaining
membership amongst processes in a distributed system.

While starting, Skipper will find its swarm peers through the Kubernetes API server. It will do that using a label selector query to find Pods of the swarm.


Package Files

doc.go kubernetes.go message.go nodeinfo.go nodeinfoclient.go nodestate.go static.go swarm.go utils.go


const (
    // DefaultNamespace is the default namespace where swarm searches for peer information
    DefaultNamespace = "kube-system"
    // DefaultLabelSelectorKey is the default label key to select Pods for peer information
    DefaultLabelSelectorKey = "application"
    // DefaultLabelSelectorValue is the default label value to select Pods for peer information
    DefaultLabelSelectorValue = "skipper-ingress"
const (
    // DefaultMaxMessageBuffer is the default maximum size of the
    // exchange packets send out to peers.
    DefaultMaxMessageBuffer = 1 << 22
    // DefaultPort is used as default to connect to other
    // known swarm peers.
    DefaultPort = 9990
    // DefaultLeaveTimeout is the default timeout to wait for responses
    // for a leave message send by this instance to other peers.
    DefaultLeaveTimeout = time.Duration(5 * time.Second)


var (
    ErrUnknownSwarm = errors.New("unknown swarm type")

func NewNodeInfoClient Uses

func NewNodeInfoClient(o Options) (nodeInfoClient, func())

func NewNodeInfoClientFake Uses

func NewNodeInfoClientFake(o Options) *nodeInfoClientFake

func NewNodeInfoClientKubernetes Uses

func NewNodeInfoClientKubernetes(o Options) *nodeInfoClientKubernetes

type ClientKubernetes Uses

type ClientKubernetes struct {
    // contains filtered or unexported fields

ClientKubernetes is the client to access kubernetes resources to find the peers to join a swarm.

func NewClientKubernetes Uses

func NewClientKubernetes(kubernetesInCluster bool, kubernetesURL string) (*ClientKubernetes, error)

NewClientKubernetes creates and initializes a Kubernetes client to find peers. A partial copy of the Kubernetes dataclient.

func (*ClientKubernetes) Get Uses

func (c *ClientKubernetes) Get(s string) (*http.Response, error)

Get does the http GET call to kubernetes API to find the initial peers of a swarm.

func (*ClientKubernetes) Stop Uses

func (c *ClientKubernetes) Stop()

type EntryPoint Uses

type EntryPoint interface {
    Nodes() []*NodeInfo

EntryPoint knows its peers of nodes which contains itself

type KubernetesOptions Uses

type KubernetesOptions struct {
    KubernetesInCluster  bool
    KubernetesAPIBaseURL string
    Namespace            string
    LabelSelectorKey     string
    LabelSelectorValue   string

KubernetesOptions are Kubernetes specific swarm options, that are needed to find peers.

type Message Uses

type Message struct {
    Source string
    Value  interface{}

type NodeInfo Uses

type NodeInfo struct {
    Name string
    Addr net.IP
    Port uint16

NodeInfo is a value object tat contains information about swarm cluster nodes, that is required to access member nodes.

func NewFakeNodeInfo Uses

func NewFakeNodeInfo(name string, addr net.IP, port uint16) *NodeInfo

NewFakeNodeInfo used to create a FakeSwarm

func NewStaticNodeInfo Uses

func NewStaticNodeInfo(name, addr string) (*NodeInfo, error)

func (NodeInfo) String Uses

func (ni NodeInfo) String() string

String will only show initial peers when created this peer

type NodeState Uses

type NodeState int

NodeState represents the current state of a cluster node known by this instance.

const (
    Initial NodeState = iota

type Options Uses

type Options struct {

    // MaxMessageBuffer is the maximum size of the exchange
    // packets send out to peers.
    MaxMessageBuffer int

    // LeaveTimeout is the timeout to wait for responses for a
    // leave message send by this instance to other peers.
    LeaveTimeout time.Duration

    // SwarmPort port to listen for incoming swarm packets.
    SwarmPort uint16

    // KubernetesOptions are options required to find your peers in Kubernetes
    KubernetesOptions *KubernetesOptions

    StaticSwarm *StaticSwarm

    // FakeSwarm enable a test swarm
    FakeSwarm bool

    // FakeSwarmLocalNode is the node name of the local node
    // joining a fakeSwarm to have better log output
    FakeSwarmLocalNode string

    // Debug enables swarm debug logs and also enables memberlist logs
    Debug bool
    // contains filtered or unexported fields

Options configure swarm objects.

type Self Uses

type Self interface {
    Node() *NodeInfo

Self can return itself as NodeInfo

type StaticSwarm Uses

type StaticSwarm struct {
    // contains filtered or unexported fields

func NewStaticSwarm Uses

func NewStaticSwarm(self *NodeInfo, all []*NodeInfo) *StaticSwarm

func (*StaticSwarm) GetNodeInfo Uses

func (s *StaticSwarm) GetNodeInfo() ([]*NodeInfo, error)

func (*StaticSwarm) Self Uses

func (s *StaticSwarm) Self() *NodeInfo

type Swarm Uses

type Swarm struct {
    // contains filtered or unexported fields

Swarm is the main type for exchanging low latency, weakly consistent information with other skipper peers.

func Join Uses

func Join(o Options, self *NodeInfo, nodes []*NodeInfo, cleanupF func()) (*Swarm, error)

Join will join given Swarm peers and return an initialiazed Swarm object if successful.

func NewSwarm Uses

func NewSwarm(optr *Options) (*Swarm, error)

NewSwarm creates a Swarm for given Options.

func Start Uses

func Start(o Options) (*Swarm, error)

Start will find Swarm peers based on the chosen swarm type and join the Swarm.

func (*Swarm) Broadcast Uses

func (s *Swarm) Broadcast(m interface{}) error

Broadcast sends a broadcast message with a value to all peers.

func (*Swarm) Leave Uses

func (s *Swarm) Leave()

Leave sends a signal for the local node to leave the Swarm.

func (*Swarm) Local Uses

func (s *Swarm) Local() *NodeInfo

Local is a getter to the local member of a swarm.

func (*Swarm) ShareValue Uses

func (s *Swarm) ShareValue(key string, value interface{}) error

ShareValue sends a broadcast message with a sharedValue to all peers. It implements the ratelimit.Swarmer interface.

func (*Swarm) Values Uses

func (s *Swarm) Values(key string) map[string]interface{}

Values sends a request and wait blocking for a response. It implements the ratelimit.Swarmer interface.



Package swarm imports 19 packages (graph) and is imported by 4 packages. Updated 2019-03-26. Refresh now. Tools for package owners.