leaderelection

README

etcd-leaderelection

A go leader election module that can be used to track leader ownership

Install

go get -u github.com/ahmagdy/leaderelection 

Use case:

This package is intended to be used when there are multiple instances running of a service and only a single instance can be the leader, or a single instance can do a specific job.

Example:

It's mostly intended for services build on top of a framework that supports app lifecycle. e.g. Uber fx.

leaderElection := leaderelection.New(etcdClient, zapLogger, instanceName, watcher)

fx.Invoke(func(lc fx.Lifecycle) {
    lc.Append(fx.Hook{
        OnStart: func(context.Context) error { return leaderElection.Start(ctx) },
        OnStop: func(context.Context) error { return leaderElection.Stop(ctx) },
    })
})

Without lifecycle support:

func run(ctx context.Context, logger *zap.Logger, instanceName string) error {
	etcdClient, err := newETCDClient(etcdSeedHostPorts)
	if err != nil {
		return nil
	}

	watcher := &WatcherService{logger: logger}

	leaderElection, err := leaderelection.New(etcdClient, logger, instanceName, watcher)
	if err != nil {
		return err
	}
	
	if err := leaderElection.Start(ctx); err != nil {
		return fmt.Errorf("failed to start leader election: %w", err)
	}

	defer func() {
		if err := leaderElection.Stop(ctx); err != nil {
			logger.Error("failed to stop leader election", zap.Error(err))
		}
	}()
	
}

Please check /example package for more go examples.

License:

Apache License 2.0

Documentation

Index

• type Election
• type Embedded
  • func (embd *Embedded) CleanDs()
  • func (embd *Embedded) Client() *clientv3.Client
  • func (embd *Embedded) Start(t *testing.T)
  • func (embd *Embedded) Stop()
• type EventsWatcher
• type Service
  • func New(etcdClient *clientv3.Client, logger *zap.Logger, instanceName string, ...) (*Service, error)
  • func (l *Service) Resign(ctx context.Context) error
  • func (l *Service) Start(ctx context.Context) error
  • func (l *Service) Stop(ctx context.Context) error

Types

type Election

type Election interface {
	Campaign(ctx context.Context, val string) error
	Resign(ctx context.Context) (err error)
	Proclaim(ctx context.Context, val string) error
	Leader(ctx context.Context) (*clientv3.GetResponse, error)
	Observe(ctx context.Context) <-chan clientv3.GetResponse
}

type Embedded

type Embedded struct {
	ETCD *embed.Etcd
	// contains filtered or unexported fields
}

Embedded ETCD instance with tmp directory for serialized key&vals and etcd client.

func (*Embedded) CleanDs

func (embd *Embedded) CleanDs()

CleanDs deletes all stored key-value pairs.

func (*Embedded) Client

func (embd *Embedded) Client() *clientv3.Client

Client is a getter for embedded ETCD client.

func (*Embedded) Start

func (embd *Embedded) Start(t *testing.T)

Start starts embedded ETCD. Inspired by https://github.com/ligato/cn-infra/blob/master/db/keyval/etcd/mocks/embeded_etcd.go

func (*Embedded) Stop

func (embd *Embedded) Stop()

Stop stops the embedded ETCD & cleanups the tmp dir.

type EventsWatcher

type EventsWatcher interface {
	OnGainedLeadership()
	OnLostLeadership()
}

type Service

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

func New

func New(etcdClient *clientv3.Client, logger *zap.Logger, instanceName string, leadershipEventsWatcher EventsWatcher) (*Service, error)

func (*Service) Resign

func (l *Service) Resign(ctx context.Context) error

Resign Lets the leader abdicate its leadership

func (*Service) Start

func (l *Service) Start(ctx context.Context) error

Start starts the leader election process. If there is already a leader, it will become a follower and participate in the election process. If there is no leader, it will start the election process.

func (*Service) Stop

func (l *Service) Stop(ctx context.Context) error

Stop stops the leader election process.