consensus

Documentation

Index

• Variables
• func GetEtcdMemberNodeId(member *etcdserverpb.Member) string
• type AddNodeOption
• type Config
• type ExistingNode
• type JoinCluster
• type Service
  • func New(config Config) *Service
  • func (s *Service) Run(ctx context.Context) error
  • func (s *Service) Watch() event.Watcher[*Status]
• type ServiceHandle
  • func TestServiceHandle(t *testing.T, cl *clientv3.Client) ServiceHandle
• type Status
  • func (s *Status) AddNode(ctx context.Context, nodeID string, pk ed25519.PublicKey, ...) (*JoinCluster, error)
  • func (s *Status) ClusterClient() clientv3.Cluster
  • func (s *Status) CuratorClient() (client.Namespaced, error)
  • func (s *Status) KubernetesClient() (client.Namespaced, error)
  • func (s *Status) RemoveNode(ctx context.Context, nodeID string) error
  • func (s *Status) Running() bool

Variables

var FilterRunning = event.Filter(func(st *Status) bool {
	return st.Running()
})

Functions

func GetEtcdMemberNodeId

func GetEtcdMemberNodeId(member *etcdserverpb.Member) string

GetEtcdMemberNodeId returns the node ID of an etcd member. It works even for members which have not started, where member.Name is empty.

Types

type AddNodeOption

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

AddNodeOption can be passed to AddNode to influence the behaviour of the function. Currently this is only used internally by tests.

type Config

type Config struct {
	// Data directory (persistent, encrypted storage) for etcd.
	Data *localstorage.DataEtcdDirectory
	// Ephemeral directory for etcd.
	Ephemeral *localstorage.EphemeralConsensusDirectory

	// JoinCluster is set if this instance is to join an existing cluster for the
	// first time. If not set, it's assumed this instance has ran before and has all
	// the state on disk required to become part of whatever cluster it was before.
	// If that data is not present, a new cluster will be bootstrapped.
	JoinCluster *JoinCluster

	// NodeID is the node ID, which is also used to identify consensus nodes.
	NodeID string

	// NodePrivateKey is the node's main private key which is also used for
	// Metropolis PKI. The same key will be used for consensus nodes, but
	// different certificates will be used.
	NodePrivateKey ed25519.PrivateKey
	// contains filtered or unexported fields
}

Config describes the startup configuration of a consensus instance.

type ExistingNode

type ExistingNode struct {
	Name string
	URL  string
}

ExistingNode is the peer URL and name of an already running consensus instance.

type JoinCluster

type JoinCluster struct {
	CACertificate   *x509.Certificate
	NodeCertificate *x509.Certificate
	// ExistingNodes are an arbitrarily ordered list of other consensus members that
	// the node should attempt to contact.
	ExistingNodes []ExistingNode
	// InitialCRL is a certificate revocation list for this cluster. After the node
	// starts, a CRL on disk will be maintained reflecting the PKI state within etcd.
	InitialCRL *pki.CRL
}

JoinCluster is all the data required for a node to join (for the first time) an already running cluster. This data is available from an already running consensus member by performing AddNode, which is called by the Curator when new etcd nodes are added to the cluster.

type Service

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

Service is the etcd cluster member service. See package-level documentation for more information.

func New

func New(config Config) *Service

func (*Service) Run

func (s *Service) Run(ctx context.Context) error

Run is a Supervisor runnable that starts the etcd member service. It will become healthy once the member joins the cluster successfully.

func (*Service) Watch

func (s *Service) Watch() event.Watcher[*Status]

type ServiceHandle

type ServiceHandle interface {
	// Watch returns a Event Value compatible Watcher for accessing the State of the
	// consensus Service in a safe manner.
	Watch() event.Watcher[*Status]
}

ServiceHandle is implemented by Service and should be the type expected by other code which relies on a Consensus instance. Ie., it's the downstream API for a Consensus Service.

func TestServiceHandle

func TestServiceHandle(t *testing.T, cl *clientv3.Client) ServiceHandle

TestServiceHandle builds a somewhat functioning ServiceHandle from a bare etcd connection, effectively creating a fake Consensus service. This must only be used in test code to perform dependency injection of a etcd client into code which expects a Consensus service instance, eg. for testing the Curator.

The 'somewhat functioning' description above should serve as a hint to the API stability and backwards/forwards compatibility of this function: there is none.

type Status

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

Status of the consensus service. It represents either a running consensus service to which a client can connect and on which management can be performed, or a stopped service.

func (*Status) AddNode

func (s *Status) AddNode(ctx context.Context, nodeID string, pk ed25519.PublicKey, opts ...*AddNodeOption) (*JoinCluster, error)

AddNode creates a new consensus member corresponding to a given node ID if one does not yet exist. The member will at first be marked as a Learner, ensuring it does not take part in quorum until it has finished catching up to the state of the etcd store. As it does, the autopromoter will turn it into a 'full' node and it will start taking part in the quorum and be able to perform all etcd operations.

func (*Status) ClusterClient

func (s *Status) ClusterClient() clientv3.Cluster

ClusterClient returns an etcd management API client, for use by downstream clients that wish to perform maintenance operations on the etcd cluster (eg. list/modify nodes, promote learners, ...).

func (*Status) CuratorClient

func (s *Status) CuratorClient() (client.Namespaced, error)

CuratorClient returns a namespaced etcd client for use by the Curator.

func (*Status) KubernetesClient

func (s *Status) KubernetesClient() (client.Namespaced, error)

KubernetesClient returns a namespaced etcd client for use by Kubernetes.

func (*Status) RemoveNode

func (s *Status) RemoveNode(ctx context.Context, nodeID string) error

RemoveNode removes the etcd member with the given node ID, if it is currently a member. Etcd fails this operation if it is not safe to perform.

func (*Status) Running

func (s *Status) Running() bool

Running returns true if this status represents a running consensus service which can be connected to or managed. These calls are not guaranteed to succeed (as the server might have stopped in the meantime), but the caller can use this value as a hint to whether attempts to access the consensus service should be done.