etcd

Documentation

Overview

Package etcd provides a connection to an etcd member.

There is a backoff adapter that adds retries to the standard etcd v3 go client.

An example usage of this package:

// create a dialer function
func myDialer(ctx context.Context, addr string) (net.Conn, error) {
	...
}

// An example helper in client code
func getBackoffClient(endpoint string, dialer GRPCDial, cfg *tls.Config, timeout time.Duration) (*etcd.Client, error) {
	etcdClient, _ := etcd.NewEtcdClient(endpoint, dialer, cfg)
	adapter, _ := etcd.NewEtcdBackoffAdapter(etcdClient, WithTimeout(timeout))
	return etcd.NewClientWithEtcd(adapter)
}

// usage
func talkToEtcd() {
	client, _, := getBackoffClient("localhost", myDialer, cfg, 1*time.Second)
	client.Status(context.TODO())
}

The adapter is a helper and not necessary. Use the default clientv3 if you do not need retries or stub out etcd for unit tests.

Index

• Variables
• func NewEtcdClient(endpoints []string, dialer GRPCDial, tlsConfig *tls.Config) (*clientv3.Client, error)
• type AlarmType
• type Client
  • func NewClientWithEtcd(ctx context.Context, etcdClient etcd) (*Client, error)
  • func (c *Client) Alarms(ctx context.Context) ([]MemberAlarm, error)
  • func (c *Client) Close() error
  • func (c *Client) Members(ctx context.Context) ([]*Member, error)
  • func (c *Client) MoveLeader(ctx context.Context, newLeaderID uint64) error
  • func (c *Client) RemoveMember(ctx context.Context, id uint64) error
  • func (c *Client) UpdateMemberPeerURLs(ctx context.Context, id uint64, peerURLs []string) ([]*Member, error)
• type EtcdBackoffAdapter
  • func NewEtcdBackoffAdapter(c *clientv3.Client, options ...EtcdBackoffAdapterOption) *EtcdBackoffAdapter
  • func (e *EtcdBackoffAdapter) AlarmList(ctx context.Context) (*clientv3.AlarmResponse, error)
  • func (e *EtcdBackoffAdapter) Close() error
  • func (e *EtcdBackoffAdapter) MemberList(ctx context.Context) (*clientv3.MemberListResponse, error)
  • func (e *EtcdBackoffAdapter) MemberRemove(ctx context.Context, id uint64) (*clientv3.MemberRemoveResponse, error)
  • func (e *EtcdBackoffAdapter) MemberUpdate(ctx context.Context, id uint64, peerURLs []string) (*clientv3.MemberUpdateResponse, error)
  • func (e *EtcdBackoffAdapter) MoveLeader(ctx context.Context, id uint64) (*clientv3.MoveLeaderResponse, error)
• type EtcdBackoffAdapterOption
  • func WithBackoff(backoff wait.Backoff) EtcdBackoffAdapterOption
  • func WithTimeout(timeout time.Duration) EtcdBackoffAdapterOption
• type GRPCDial
• type Member
• type MemberAlarm

Variables

var Log = klogr.New()

Log is the global logger used. Global var can be swapped out if necessary.

Functions

func NewEtcdClient

func NewEtcdClient(endpoints []string, dialer GRPCDial, tlsConfig *tls.Config) (*clientv3.Client, error)

NewEtcdClient creates a new etcd client with a custom dialer and is configuration with optional functions.

Types

type AlarmType

type AlarmType int32

const (
	// AlarmOK denotes that the cluster member is OK.
	AlarmOk AlarmType = iota

	// AlarmNoSpace denotes that the cluster member has run out of disk space.
	AlarmNoSpace

	// AlarmCorrupt denotes that the cluster member has corrupted data.
	AlarmCorrupt
)

type Client

type Client struct {
	EtcdClient etcd
	Endpoint   string
	LeaderID   uint64
}

Client wraps an etcd client formatting its output to something more consumable.

func NewClientWithEtcd

func NewClientWithEtcd(ctx context.Context, etcdClient etcd) (*Client, error)

NewClientWithEtcd configures our response formatter (Client) with an etcd client and endpoint.

func (*Client) Alarms

func (c *Client) Alarms(ctx context.Context) ([]MemberAlarm, error)

Alarms retrieves all alarms on a cluster.

func (*Client) Close

func (c *Client) Close() error

Close closes the etcd client.

func (*Client) Members

func (c *Client) Members(ctx context.Context) ([]*Member, error)

Members retrieves a list of etcd members.

func (*Client) MoveLeader

func (c *Client) MoveLeader(ctx context.Context, newLeaderID uint64) error

MoveLeader moves the leader to the provided member ID.

func (*Client) RemoveMember

func (c *Client) RemoveMember(ctx context.Context, id uint64) error

RemoveMember removes a given member.

func (*Client) UpdateMemberPeerURLs

func (c *Client) UpdateMemberPeerURLs(ctx context.Context, id uint64, peerURLs []string) ([]*Member, error)

UpdateMemberPeerList updates the list of peer URLs

type EtcdBackoffAdapter

type EtcdBackoffAdapter struct {
	EtcdClient    *clientv3.Client
	BackoffParams wait.Backoff
	Timeout       time.Duration
}

EtcdBackoffAdapter wraps EtcdClient calls in a wait.ExponentialBackoff.

func NewEtcdBackoffAdapter

func NewEtcdBackoffAdapter(c *clientv3.Client, options ...EtcdBackoffAdapterOption) *EtcdBackoffAdapter

NewEtcdBackoffAdapter will wrap an etcd client with default backoff retries. Options allow a client to set various timeout parameters.

func (*EtcdBackoffAdapter) AlarmList

func (e *EtcdBackoffAdapter) AlarmList(ctx context.Context) (*clientv3.AlarmResponse, error)

AlarmList calls AlarmList on the etcd client with a backoff retry.

func (*EtcdBackoffAdapter) Close

func (e *EtcdBackoffAdapter) Close() error

Close calls close on the etcd client

func (*EtcdBackoffAdapter) MemberList

func (e *EtcdBackoffAdapter) MemberList(ctx context.Context) (*clientv3.MemberListResponse, error)

MemberList calls MemberList on the etcd client with a backoff retry.

func (*EtcdBackoffAdapter) MemberRemove

func (e *EtcdBackoffAdapter) MemberRemove(ctx context.Context, id uint64) (*clientv3.MemberRemoveResponse, error)

MemberRemove calls MemberRemove on the etcd client with a backoff retry.

func (*EtcdBackoffAdapter) MemberUpdate

func (e *EtcdBackoffAdapter) MemberUpdate(ctx context.Context, id uint64, peerURLs []string) (*clientv3.MemberUpdateResponse, error)

MemberUpdate calls MemberUpdate on the etcd client with a backoff retry.

func (*EtcdBackoffAdapter) MoveLeader

func (e *EtcdBackoffAdapter) MoveLeader(ctx context.Context, id uint64) (*clientv3.MoveLeaderResponse, error)

MoveLeader calls MoveLeader on the etcd client with a backoff retry.

type EtcdBackoffAdapterOption

type EtcdBackoffAdapterOption func(*EtcdBackoffAdapter)

EtcdBackoffAdapterOption defines the option type for the EtcdBackoffAdapter

func WithBackoff

func WithBackoff(backoff wait.Backoff) EtcdBackoffAdapterOption

WithBackoff configures the backoff period of etcd calls the adapter makes.

func WithTimeout

func WithTimeout(timeout time.Duration) EtcdBackoffAdapterOption

WithTimeout will configure the backoff adapter's timeout for any etcd calls it makes.

type GRPCDial

type GRPCDial func(ctx context.Context, addr string) (net.Conn, error)

GRPCDial is a function that creates a connection to a given endpoint.

type Member

type Member struct {
	// ClusterID is the ID of the cluster to which this member belongs
	ClusterID uint64

	// ID is the ID of this cluster member
	ID uint64

	// Name is the human-readable name of the member. If the member is not started, the name will be an empty string.
	Name string

	// PeerURLs is the list of URLs the member exposes to the cluster for communication.
	PeerURLs []string

	// ClientURLs is the list of URLs the member exposes to clients for communication. If the member is not started, clientURLs will be empty.
	ClientURLs []string

	// IsLearner indicates if the member is raft learner.
	IsLearner bool

	// Alarms is the list of alarms for a member.
	Alarms []AlarmType
}

Member struct defines an etcd member; it is used to avoid spreading github.com/coreos/etcd dependencies.

type MemberAlarm

type MemberAlarm struct {
	// MemberID is the ID of the member associated with the raised alarm.
	MemberID uint64

	// Type is the type of alarm which has been raised.
	Type AlarmType
}

MemberAlarm represents an alarm type association with a cluster member.