Documentation

Overview

    Package kvstore abstracts KVstore access and provides a high level API to atomically manage cluster wide resources

    Index

    Constants

    View Source
    const (
    
    	// ConsulAddrOption is the string representing the key mapping to the value of the
    	// address for Consul.
    	ConsulAddrOption   = "consul.address"
    	ConsulOptionConfig = "consul.tlsconfig"
    )
    View Source
    const (
    	// EtcdBackendName is the backend name for etcd
    	EtcdBackendName = "etcd"
    
    	EtcdAddrOption = "etcd.address"
    
    	EtcdOptionConfig = "etcd.config"
    
    	// EtcdRateLimitOption specifies maximum kv operations per second
    	EtcdRateLimitOption = "etcd.qps"
    )
    View Source
    const (
    	// CapabilityCreateIfExists is true if CreateIfExists is functional
    	CapabilityCreateIfExists Capabilities = 1 << 0
    
    	// CapabilityDeleteOnZeroCount is true if DeleteOnZeroCount is functional
    	CapabilityDeleteOnZeroCount Capabilities = 1 << 1
    
    	// BaseKeyPrefix is the base prefix that should be used for all keys
    	BaseKeyPrefix = "cilium"
    
    	// InitLockPath is the path to the init lock to test quorum
    	InitLockPath = BaseKeyPrefix + "/.initlock"
    
    	// HeartbeatPath is the path to the key at which the operator updates
    	// the heartbeat
    	HeartbeatPath = BaseKeyPrefix + "/.heartbeat"
    
    	// HeartbeatWriteInterval is the interval in which the heartbeat key at
    	// HeartbeatPath is updated
    	HeartbeatWriteInterval = time.Minute
    )
    View Source
    const (
    	// OperationalPath is the base path to store the operational details in the kvstore.
    	OperationalPath = "cilium-net/operational"
    )

    Variables

    View Source
    var (
    	// Debugging can be enabled at compile with:
    	// -ldflags "-X "github.com/cilium/cilium/pkg/kvstore".Debug=true"
    	Debug string
    )
    View Source
    var (
    	// ErrLockLeaseExpired is an error whenever the lease of the lock does not
    	// exist or it was expired.
    	ErrLockLeaseExpired = errors.New("transaction did not succeed: lock lease expired")
    )

    Functions

    func Connected

    func Connected() <-chan struct{}

      Connected returns a channel which is closed when the following conditions are being met at the same time: * The kvstore client is configured * Connectivity to the kvstore has been established * The kvstore has quorum

      The channel will *not* be closed if the kvstore client is closed before connectivity or quorum has been achieved. It will wait until a new kvstore client is configured to again wait for connectivity and quorum.

      func ConsulDummyAddress

      func ConsulDummyAddress() string

      func ConsulDummyConfigFile

      func ConsulDummyConfigFile() string

      func EnableTracing

      func EnableTracing()

        EnableTracing enables kvstore tracing

        func EtcdDummyAddress

        func EtcdDummyAddress() string

        func Hint

        func Hint(err error) error

          Hint tries to improve the error message displayed to te user.

          func IsEtcdOperator

          func IsEtcdOperator(selectedBackend string, opts map[string]string, k8sNamespace string) (string, bool)

            IsEtcdOperator returns the service name if the configuration is setting up an etcd-operator. If the configuration explicitly states it is configured to connect to an etcd operator, e.g. with etcd.operator=true, the returned service name is the first found within the configuration specified.

            func RunLockGC

            func RunLockGC()

              RunLockGC inspects all local kvstore locks to determine whether they have been held longer than the stale lock timeout, and if so, unlocks them forceably.

              func Setup

              func Setup(ctx context.Context, selectedBackend string, opts map[string]string, goOpts *ExtraOptions) error

                Setup sets up the key-value store specified in kvStore and configures it with the options provided in opts

                func SetupDummy

                func SetupDummy(dummyBackend string)

                  SetupDummy sets up kvstore for tests

                  func SplitK8sServiceURL

                  func SplitK8sServiceURL(address string) (string, string, error)

                    SplitK8sServiceURL returns the service name and namespace for the given address. If the given address is not parseable or it is not the format '<protocol>://><name>.<namespace>[optional]', returns an error.

                    func Trace

                    func Trace(format string, err error, fields logrus.Fields, a ...interface{})

                      Trace is used to trace kvstore debug messages

                      Types

                      type BackendOperations

                      type BackendOperations interface {
                      	// Connected returns a channel which is closed whenever the kvstore client
                      	// is connected to the kvstore server.
                      	Connected(ctx context.Context) <-chan error
                      
                      	// Disconnected returns a channel which is closed whenever the kvstore
                      	// client is not connected to the kvstore server. (Only implemented for etcd)
                      	Disconnected() <-chan struct{}
                      
                      	// Status returns the status of the kvstore client including an
                      	// eventual error
                      	Status() (string, error)
                      
                      	// StatusCheckErrors returns a channel which receives status check
                      	// errors
                      	StatusCheckErrors() <-chan error
                      
                      	// LockPath locks the provided path
                      	LockPath(ctx context.Context, path string) (KVLocker, error)
                      
                      	// Get returns value of key
                      	Get(ctx context.Context, key string) ([]byte, error)
                      
                      	// GetIfLocked returns value of key if the client is still holding the given lock.
                      	GetIfLocked(ctx context.Context, key string, lock KVLocker) ([]byte, error)
                      
                      	// GetPrefix returns the first key which matches the prefix and its value
                      	GetPrefix(ctx context.Context, prefix string) (string, []byte, error)
                      
                      	// GetPrefixIfLocked returns the first key which matches the prefix and its value if the client is still holding the given lock.
                      	GetPrefixIfLocked(ctx context.Context, prefix string, lock KVLocker) (string, []byte, error)
                      
                      	// Set sets value of key
                      	Set(ctx context.Context, key string, value []byte) error
                      
                      	// Delete deletes a key
                      	Delete(ctx context.Context, key string) error
                      
                      	// DeleteIfLocked deletes a key if the client is still holding the given lock.
                      	DeleteIfLocked(ctx context.Context, key string, lock KVLocker) error
                      
                      	DeletePrefix(ctx context.Context, path string) error
                      
                      	// Update atomically creates a key or fails if it already exists
                      	Update(ctx context.Context, key string, value []byte, lease bool) error
                      
                      	// UpdateIfLocked atomically creates a key or fails if it already exists if the client is still holding the given lock.
                      	UpdateIfLocked(ctx context.Context, key string, value []byte, lease bool, lock KVLocker) error
                      
                      	// UpdateIfDifferent updates a key if the value is different
                      	UpdateIfDifferent(ctx context.Context, key string, value []byte, lease bool) (bool, error)
                      
                      	// UpdateIfDifferentIfLocked updates a key if the value is different and if the client is still holding the given lock.
                      	UpdateIfDifferentIfLocked(ctx context.Context, key string, value []byte, lease bool, lock KVLocker) (bool, error)
                      
                      	// CreateOnly atomically creates a key or fails if it already exists
                      	CreateOnly(ctx context.Context, key string, value []byte, lease bool) (bool, error)
                      
                      	// CreateOnlyIfLocked atomically creates a key if the client is still holding the given lock or fails if it already exists
                      	CreateOnlyIfLocked(ctx context.Context, key string, value []byte, lease bool, lock KVLocker) (bool, error)
                      
                      	// CreateIfExists creates a key with the value only if key condKey exists
                      	CreateIfExists(ctx context.Context, condKey, key string, value []byte, lease bool) error
                      
                      	// ListPrefix returns a list of keys matching the prefix
                      	ListPrefix(ctx context.Context, prefix string) (KeyValuePairs, error)
                      
                      	// ListPrefixIfLocked returns a list of keys matching the prefix only if the client is still holding the given lock.
                      	ListPrefixIfLocked(ctx context.Context, prefix string, lock KVLocker) (KeyValuePairs, error)
                      
                      	// Watch starts watching for changes in a prefix. If list is true, the
                      	// current keys matching the prefix will be listed and reported as new
                      	// keys first.
                      	Watch(ctx context.Context, w *Watcher)
                      
                      	// Close closes the kvstore client
                      	Close()
                      
                      	// GetCapabilities returns the capabilities of the backend
                      	GetCapabilities() Capabilities
                      
                      	// Encodes a binary slice into a character set that the backend
                      	// supports
                      	Encode(in []byte) string
                      
                      	// Decodes a key previously encoded back into the original binary slice
                      	Decode(in string) ([]byte, error)
                      
                      	// ListAndWatch creates a new watcher which will watch the specified
                      	// prefix for changes. Before doing this, it will list the current keys
                      	// matching the prefix and report them as new keys. Name can be set to
                      	// anything and is used for logging messages. The Events channel is
                      	// created with the specified sizes. Upon every change observed, a
                      	// KeyValueEvent will be sent to the Events channel
                      	ListAndWatch(ctx context.Context, name, prefix string, chanSize int) *Watcher
                      }

                        BackendOperations are the individual kvstore operations that each backend must implement. Direct use of this interface is possible but will bypass the tracing layer.

                        func Client

                        func Client() BackendOperations

                          Client returns the global kvstore client or nil if the client is not configured yet

                          func NewClient

                          func NewClient(ctx context.Context, selectedBackend string, opts map[string]string, options *ExtraOptions) (BackendOperations, chan error)

                            NewClient returns a new kvstore client based on the configuration

                            type Capabilities

                            type Capabilities uint32

                              Capabilities is a bitmask to indicate the capabilities of a backend

                              type ConsulLocker

                              type ConsulLocker struct {
                              	*consulAPI.Lock
                              }

                              func (*ConsulLocker) Comparator

                              func (cl *ConsulLocker) Comparator() interface{}

                              func (*ConsulLocker) Unlock

                              func (cl *ConsulLocker) Unlock(ctx context.Context) error

                              type EventChan

                              type EventChan chan KeyValueEvent

                                EventChan is a channel to receive events on

                                type EventType

                                type EventType int

                                  EventType defines the type of watch event that occurred

                                  const (
                                  	// EventTypeCreate represents a newly created key
                                  	EventTypeCreate EventType = iota
                                  	// EventTypeModify represents a modified key
                                  	EventTypeModify
                                  	// EventTypeDelete represents a deleted key
                                  	EventTypeDelete
                                  	//EventTypeListDone signals that the initial list operation has completed
                                  	EventTypeListDone
                                  )

                                  func (EventType) String

                                  func (t EventType) String() string

                                    String() returns the human readable format of an event type

                                    type ExtraOptions

                                    type ExtraOptions struct {
                                    	DialOption []grpc.DialOption
                                    
                                    	// ClusterSizeDependantInterval defines the function to calculate
                                    	// intervals based on cluster size
                                    	ClusterSizeDependantInterval func(baseInterval time.Duration) time.Duration
                                    
                                    	// NoLockQuorumCheck disables the lock acquisition quorum check
                                    	NoLockQuorumCheck bool
                                    }

                                      ExtraOptions represents any options that can not be represented in a textual format and need to be set programmatically.

                                      func (*ExtraOptions) StatusCheckInterval

                                      func (e *ExtraOptions) StatusCheckInterval(allConnected bool) time.Duration

                                        StatusCheckInterval returns the interval of status checks depending on the cluster size and the current connectivity state

                                        nodes OK Failing 1 20s 3s 4 45s 7s 8 1m05s 11s 32 1m45s 18s 128 2m25s 24s 512 3m07s 32s 2048 3m46s 38s 8192 4m30s 45s

                                        type KVLocker

                                        type KVLocker interface {
                                        	Unlock(ctx context.Context) error
                                        	// Comparator returns an object that should be used by the KVStore to make
                                        	// sure if the lock is still valid for its client or nil if no such
                                        	// verification exists.
                                        	Comparator() interface{}
                                        }

                                        type KeyValueEvent

                                        type KeyValueEvent struct {
                                        	// Typ is the type of event { EventTypeCreate | EventTypeModify | EventTypeDelete | EventTypeListDone }
                                        	Typ EventType
                                        
                                        	// Key is the kvstore key that changed
                                        	Key string
                                        
                                        	// Value is the kvstore value associated with the key
                                        	Value []byte
                                        }

                                          KeyValueEvent is a change event for a Key/Value pair

                                          type KeyValuePairs

                                          type KeyValuePairs map[string]Value

                                            KeyValuePairs is a map of key=value pairs

                                            type Lock

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

                                              Lock is a lock return by LockPath

                                              func LockPath

                                              func LockPath(ctx context.Context, backend BackendOperations, path string) (l *Lock, err error)

                                                LockPath locks the specified path. The key for the lock is not the path provided itself but the path with a suffix of ".lock" appended. The lock returned also contains a patch specific local Mutex which will be held.

                                                It is required to call Unlock() on the returned Lock to unlock

                                                func (*Lock) Comparator

                                                func (l *Lock) Comparator() interface{}

                                                func (*Lock) Unlock

                                                func (l *Lock) Unlock(ctx context.Context) error

                                                  Unlock unlocks a lock

                                                  type Value

                                                  type Value struct {
                                                  	Data        []byte
                                                  	ModRevision uint64
                                                  	LeaseID     int64
                                                  	SessionID   string
                                                  }

                                                    Value is an abstraction of the data stored in the kvstore as well as the mod revision of that data.

                                                    type Watcher

                                                    type Watcher struct {
                                                    	// Events is the channel to which change notifications will be sent to
                                                    	Events EventChan
                                                    	// contains filtered or unexported fields
                                                    }

                                                      Watcher represents a KVstore watcher

                                                      func ListAndWatch

                                                      func ListAndWatch(ctx context.Context, name, prefix string, chanSize int) *Watcher

                                                        ListAndWatch creates a new watcher which will watch the specified prefix for changes. Before doing this, it will list the current keys matching the prefix and report them as new keys. Name can be set to anything and is used for logging messages. The Events channel is created with the specified sizes. Upon every change observed, a KeyValueEvent will be sent to the Events channel

                                                        Returns a watcher structure plus a channel that is closed when the initial list operation has been completed

                                                        func (*Watcher) Stop

                                                        func (w *Watcher) Stop()

                                                          Stop stops a watcher previously created and started with Watch()

                                                          func (*Watcher) String

                                                          func (w *Watcher) String() string

                                                            String returns the name of the wather

                                                            Directories

                                                            Path Synopsis
                                                            Package allocator provides a kvstore based ID allocator
                                                            Package allocator provides a kvstore based ID allocator
                                                            Package store implements a shared store backed by a kvstore or similar with the following properties: * A single type is used to represent all keys * Any number of collaborators can join the store.
                                                            Package store implements a shared store backed by a kvstore or similar with the following properties: * A single type is used to represent all keys * Any number of collaborators can join the store.