embed

Documentation

Overview

Package embed provides bindings for embedding an etcd server in a program.

Launch an embedded etcd server using the configuration defaults:

import (
	"log"
	"time"

	"github.com/coreos/etcd/embed"
)

func main() {
	cfg := embed.NewConfig()
	cfg.Dir = "default.etcd"
	e, err := embed.StartEtcd(cfg)
	if err != nil {
		log.Fatal(err)
	}
	defer e.Close()
	select {
	case <-e.Server.ReadyNotify():
		log.Printf("Server is ready!")
	case <-time.After(60 * time.Second):
		e.Server.Stop() // trigger a shutdown
		log.Printf("Server took too long to start!")
	}
	log.Fatal(<-e.Err())
}

Index

• Constants
• Variables
• type Config
  • func ConfigFromFile(path string) (*Config, error)
  • func NewConfig() *Config
  • func (cfg *Config) ClientSelfCert() (err error)
  • func (cfg Config) ElectionTicks() int
  • func (cfg Config) InitialClusterFromName(name string) (ret string)
  • func (cfg Config) IsNewCluster() bool
  • func (cfg *Config) PeerSelfCert() (err error)
  • func (cfg *Config) PeerURLsMapAndToken(which string) (urlsmap types.URLsMap, token string, err error)
  • func (cfg *Config) SetupLogging()
  • func (cfg *Config) UpdateDefaultClusterFromName(defaultInitialCluster string) (string, error)
  • func (cfg *Config) Validate() error
• type Etcd
  • func StartEtcd(inCfg *Config) (e *Etcd, err error)
  • func (e *Etcd) Close()
  • func (e *Etcd) Config() Config
  • func (e *Etcd) Err() <-chan error

Constants

const (
	ClusterStateFlagNew      = "new"
	ClusterStateFlagExisting = "existing"

	DefaultName                  = "default"
	DefaultMaxSnapshots          = 5
	DefaultMaxWALs               = 5
	DefaultMaxTxnOps             = uint(128)
	DefaultMaxRequestBytes       = 1.5 * 1024 * 1024
	DefaultGRPCKeepAliveMinTime  = 5 * time.Second
	DefaultGRPCKeepAliveInterval = 2 * time.Hour
	DefaultGRPCKeepAliveTimeout  = 20 * time.Second

	DefaultListenPeerURLs   = "http://localhost:2380"
	DefaultListenClientURLs = "http://localhost:2379"

	DefaultLogOutput = "default"

	// DefaultStrictReconfigCheck is the default value for "--strict-reconfig-check" flag.
	// It's enabled by default.
	DefaultStrictReconfigCheck = true
	// DefaultEnableV2 is the default value for "--enable-v2" flag.
	// v2 is enabled by default.
	// TODO: disable v2 when deprecated.
	DefaultEnableV2 = true
)

Variables

var (
	ErrConflictBootstrapFlags = fmt.Errorf("multiple discovery or bootstrap flags are set. " +
		"Choose one of \"initial-cluster\", \"discovery\" or \"discovery-srv\"")
	ErrUnsetAdvertiseClientURLsFlag = fmt.Errorf("--advertise-client-urls is required when --listen-client-urls is set explicitly")

	DefaultInitialAdvertisePeerURLs = "http://localhost:2380"
	DefaultAdvertiseClientURLs      = "http://localhost:2379"
)

Types

type Config

type Config struct {
	CorsInfo       *cors.CORSInfo
	LPUrls, LCUrls []url.URL
	Dir            string `json:"data-dir"`
	WalDir         string `json:"wal-dir"`
	MaxSnapFiles   uint   `json:"max-snapshots"`
	MaxWalFiles    uint   `json:"max-wals"`
	Name           string `json:"name"`
	SnapCount      uint64 `json:"snapshot-count"`

	// AutoCompactionMode is either 'periodic' or 'revision'.
	AutoCompactionMode string `json:"auto-compaction-mode"`
	// AutoCompactionRetention is either duration string with time unit
	// (e.g. '5m' for 5-minute), or revision unit (e.g. '5000').
	// If no time unit is provided and compaction mode is 'periodic',
	// the unit defaults to hour. For example, '5' translates into 5-hour.
	AutoCompactionRetention string `json:"auto-compaction-retention"`

	// TickMs is the number of milliseconds between heartbeat ticks.
	// TODO: decouple tickMs and heartbeat tick (current heartbeat tick = 1).
	// make ticks a cluster wide configuration.
	TickMs     uint `json:"heartbeat-interval"`
	ElectionMs uint `json:"election-timeout"`

	// InitialElectionTickAdvance is true, then local member fast-forwards
	// election ticks to speed up "initial" leader election trigger. This
	// benefits the case of larger election ticks. For instance, cross
	// datacenter deployment may require longer election timeout of 10-second.
	// If true, local node does not need wait up to 10-second. Instead,
	// forwards its election ticks to 8-second, and have only 2-second left
	// before leader election.
	//
	// Major assumptions are that:
	//  - cluster has no active leader thus advancing ticks enables faster
	//    leader election, or
	//  - cluster already has an established leader, and rejoining follower
	//    is likely to receive heartbeats from the leader after tick advance
	//    and before election timeout.
	//
	// However, when network from leader to rejoining follower is congested,
	// and the follower does not receive leader heartbeat within left election
	// ticks, disruptive election has to happen thus affecting cluster
	// availabilities.
	//
	// Disabling this would slow down initial bootstrap process for cross
	// datacenter deployments. Make your own tradeoffs by configuring
	// --initial-election-tick-advance at the cost of slow initial bootstrap.
	//
	// If single-node, it advances ticks regardless.
	//
	// See https://github.com/coreos/etcd/issues/9333 for more detail.
	InitialElectionTickAdvance bool `json:"initial-election-tick-advance"`

	QuotaBackendBytes int64 `json:"quota-backend-bytes"`
	MaxTxnOps         uint  `json:"max-txn-ops"`
	MaxRequestBytes   uint  `json:"max-request-bytes"`

	// GRPCKeepAliveMinTime is the minimum interval that a client should
	// wait before pinging server. When client pings "too fast", server
	// sends goaway and closes the connection (errors: too_many_pings,
	// http2.ErrCodeEnhanceYourCalm). When too slow, nothing happens.
	// Server expects client pings only when there is any active streams
	// (PermitWithoutStream is set false).
	GRPCKeepAliveMinTime time.Duration `json:"grpc-keepalive-min-time"`
	// GRPCKeepAliveInterval is the frequency of server-to-client ping
	// to check if a connection is alive. Close a non-responsive connection
	// after an additional duration of Timeout. 0 to disable.
	GRPCKeepAliveInterval time.Duration `json:"grpc-keepalive-interval"`
	// GRPCKeepAliveTimeout is the additional duration of wait
	// before closing a non-responsive connection. 0 to disable.
	GRPCKeepAliveTimeout time.Duration `json:"grpc-keepalive-timeout"`

	APUrls, ACUrls      []url.URL
	ClusterState        string `json:"initial-cluster-state"`
	DNSCluster          string `json:"discovery-srv"`
	Dproxy              string `json:"discovery-proxy"`
	Durl                string `json:"discovery"`
	InitialCluster      string `json:"initial-cluster"`
	InitialClusterToken string `json:"initial-cluster-token"`
	StrictReconfigCheck bool   `json:"strict-reconfig-check"`
	EnableV2            bool   `json:"enable-v2"`

	ClientTLSInfo transport.TLSInfo
	ClientAutoTLS bool
	PeerTLSInfo   transport.TLSInfo
	PeerAutoTLS   bool

	// CipherSuites is a list of supported TLS cipher suites between
	// client/server and peers. If empty, Go auto-populates the list.
	// Note that cipher suites are prioritized in the given order.
	CipherSuites []string `json:"cipher-suites"`

	Debug                 bool   `json:"debug"`
	LogPkgLevels          string `json:"log-package-levels"`
	LogOutput             string `json:"log-output"`
	EnablePprof           bool   `json:"enable-pprof"`
	Metrics               string `json:"metrics"`
	ListenMetricsUrls     []url.URL
	ListenMetricsUrlsJSON string `json:"listen-metrics-urls"`

	// ForceNewCluster starts a new cluster even if previously started; unsafe.
	ForceNewCluster bool `json:"force-new-cluster"`

	// UserHandlers is for registering users handlers and only used for
	// embedding etcd into other applications.
	// The map key is the route path for the handler, and
	// you must ensure it can't be conflicted with etcd's.
	UserHandlers map[string]http.Handler `json:"-"`
	// ServiceRegister is for registering users' gRPC services. A simple usage example:
	//	cfg := embed.NewConfig()
	//	cfg.ServerRegister = func(s *grpc.Server) {
	//		pb.RegisterFooServer(s, &fooServer{})
	//		pb.RegisterBarServer(s, &barServer{})
	//	}
	//	embed.StartEtcd(cfg)
	ServiceRegister func(*grpc.Server) `json:"-"`

	AuthToken string `json:"auth-token"`

	ExperimentalInitialCorruptCheck bool          `json:"experimental-initial-corrupt-check"`
	ExperimentalCorruptCheckTime    time.Duration `json:"experimental-corrupt-check-time"`
	ExperimentalEnableV2V3          string        `json:"experimental-enable-v2v3"`
}

Config holds the arguments for configuring an etcd server.

func ConfigFromFile

func ConfigFromFile(path string) (*Config, error)

func NewConfig

func NewConfig() *Config

NewConfig creates a new Config populated with default values.

func (*Config) ClientSelfCert

func (cfg *Config) ClientSelfCert() (err error)

func (Config) ElectionTicks

func (cfg Config) ElectionTicks() int

func (Config) InitialClusterFromName

func (cfg Config) InitialClusterFromName(name string) (ret string)

func (Config) IsNewCluster

func (cfg Config) IsNewCluster() bool

func (*Config) PeerSelfCert

func (cfg *Config) PeerSelfCert() (err error)

func (*Config) PeerURLsMapAndToken

func (cfg *Config) PeerURLsMapAndToken(which string) (urlsmap types.URLsMap, token string, err error)

PeerURLsMapAndToken sets up an initial peer URLsMap and cluster token for bootstrap or discovery.

func (*Config) SetupLogging

func (cfg *Config) SetupLogging()

SetupLogging initializes etcd logging. Must be called after flag parsing.

func (*Config) UpdateDefaultClusterFromName

func (cfg *Config) UpdateDefaultClusterFromName(defaultInitialCluster string) (string, error)

UpdateDefaultClusterFromName updates cluster advertise URLs with, if available, default host, if advertise URLs are default values(localhost:2379,2380) AND if listen URL is 0.0.0.0. e.g. advertise peer URL localhost:2380 or listen peer URL 0.0.0.0:2380 then the advertise peer host would be updated with machine's default host, while keeping the listen URL's port. User can work around this by explicitly setting URL with 127.0.0.1. It returns the default hostname, if used, and the error, if any, from getting the machine's default host. TODO: check whether fields are set instead of whether fields have default value

func (*Config) Validate

func (cfg *Config) Validate() error

Validate ensures that '*embed.Config' fields are properly configured.

type Etcd

type Etcd struct {
	Peers   []*peerListener
	Clients []net.Listener

	Server *etcdserver.EtcdServer
	// contains filtered or unexported fields
}

Etcd contains a running etcd server and its listeners.

func StartEtcd

func StartEtcd(inCfg *Config) (e *Etcd, err error)

StartEtcd launches the etcd server and HTTP handlers for client/server communication. The returned Etcd.Server is not guaranteed to have joined the cluster. Wait on the Etcd.Server.ReadyNotify() channel to know when it completes and is ready for use.

func (*Etcd) Close

func (e *Etcd) Close()

Close gracefully shuts down all servers/listeners. Client requests will be terminated with request timeout. After timeout, enforce remaning requests be closed immediately.

func (*Etcd) Config

func (e *Etcd) Config() Config

Config returns the current configuration.

func (*Etcd) Err

func (e *Etcd) Err() <-chan error