kvstore

package
v1.5.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2020 License: Apache-2.0 Imports: 36 Imported by: 0

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 fo 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"
)

Variables

View Source 
var (
	// LeaseTTL is the time-to-live of the lease
	LeaseTTL = 15 * time.Minute // 15 minutes

	// LockLeaseTTL is the time-to-live of the lease dedicated for locks
	LockLeaseTTL = 25 * time.Second

	// KeepAliveInterval is the interval in which the lease is being
	// renewed. This must be set to a value lesser than the LeaseTTL
	KeepAliveInterval = 5 * time.Minute

	// RetryInterval is the interval in which retries occur in the case of
	// errors in communication with the KVstore. This should be set to a
	// small value to account for temporary errors while communicating with
	// the KVstore.
	RetryInterval = 1 * time.Minute
)
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 Close added in v1.5.0 

func Close()

Close closes the kvstore client

func ConsulDummyAddress added in v1.5.12 

func ConsulDummyAddress() string

func ConsulDummyConfigFile added in v1.5.12 

func ConsulDummyConfigFile() string

func CreateIfExists added in v1.5.0 

func CreateIfExists(condKey, key string, value []byte, lease bool) error

CreateIfExists creates a key with the value only if key condKey exists

func CreateOnly added in v1.5.0 

func CreateOnly(ctx context.Context, key string, value []byte, lease bool) (bool, error)

CreateOnly atomically creates a key or fails if it already exists

func CreateOnlyIfLocked added in v1.5.5 

func CreateOnlyIfLocked(ctx context.Context, key string, value []byte, lease bool, lock KVLocker) (bool, error)

CreateOnlyIfLocked atomically creates a key if the client is still holding the given lock or fails if it already exists

func Decode added in v1.5.0 

func Decode(in string) ([]byte, error)

Decode decodes a key previously encoded back into the original binary slice

func Delete added in v1.5.0 

func Delete(key string) error

Delete deletes a key

func DeleteIfLocked added in v1.5.5 

func DeleteIfLocked(key string, lock KVLocker) error

DeleteIfLocked deletes a key if the client is still holding the given lock.

func DeletePrefix added in v1.5.0 

func DeletePrefix(prefix string) error

DeletePrefix deletes all keys matching a prefix

func EnableTracing added in v1.5.0 

func EnableTracing()

EnableTracing enables kvstore tracing

func Encode added in v1.5.0 

func Encode(in []byte) string

Encode encodes a binary slice into a character set that the backend supports

func EtcdDummyAddress added in v1.5.0 

func EtcdDummyAddress() string

func Get added in v1.5.0 

func Get(key string) ([]byte, error)

Get returns value of key

func GetIfLocked added in v1.5.5 

func GetIfLocked(key string, lock KVLocker) ([]byte, error)

GetIfLocked returns value of key if the client is still holding the given lock.

func GetPrefix added in v1.5.0 

func GetPrefix(ctx context.Context, prefix string) (k string, v []byte, err error)

GetPrefix returns the first key which matches the prefix and its value.

func GetPrefixIfLocked added in v1.5.5 

func GetPrefixIfLocked(ctx context.Context, prefix string, lock KVLocker) (k string, v []byte, err error)

GetPrefixIfLocked returns the first key which matches the prefix and its value if the client is still holding the given lock.

func Hint added in v1.5.0 

func Hint(err error) error

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

func IsEtcdOperator added in v1.5.0 

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

IsEtcdOperator returns true if the configuration is setting up an etcd-operator and false otherwise.

func Set added in v1.5.0 

func Set(key string, value []byte) error

Set sets the value of a key

func Setup added in v0.10.0 

func Setup(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 added in v0.10.0 

func SetupDummy(dummyBackend string)

SetupDummy sets up kvstore for tests

func Trace added in v1.5.0 

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

Trace is used to trace kvstore debug messages

func Update added in v1.5.0 

func Update(ctx context.Context, key string, value []byte, lease bool) error

Update creates or updates a key value pair

func UpdateIfDifferent added in v1.5.0 

func UpdateIfDifferent(ctx context.Context, key string, value []byte, lease bool) (bool, error)

UpdateIfDifferent updates a key if the value is different

func UpdateIfDifferentIfLocked added in v1.5.5 

func UpdateIfDifferentIfLocked(ctx context.Context, key string, value []byte, lease bool, lock KVLocker) (bool, error)

UpdateIfDifferentIfLocked updates a key if the value is different and if the client is still holding the given lock.

Types

type BackendOperations added in v1.5.0 

type BackendOperations interface {
	// Connected returns a channel which is closed whenever the kvstore client
	// is connected to the kvstore server. (Only implemented for etcd)
	Connected() <-chan struct{}

	// 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)

	// LockPath locks the provided path
	LockPath(ctx context.Context, path string) (KVLocker, error)

	// Get returns value of key
	Get(key string) ([]byte, error)

	// GetIfLocked returns value of key if the client is still holding the given lock.
	GetIfLocked(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(key string, value []byte) error

	// Delete deletes a key
	Delete(key string) error

	// DeleteIfLocked deletes a key if the client is still holding the given lock.
	DeleteIfLocked(key string, lock KVLocker) error

	DeletePrefix(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(condKey, key string, value []byte, lease bool) error

	// ListPrefix returns a list of keys matching the prefix
	ListPrefix(prefix string) (KeyValuePairs, error)

	// ListPrefixIfLocked returns a list of keys matching the prefix only if the client is still holding the given lock.
	ListPrefixIfLocked(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(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(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 added in v0.10.0 

func Client() BackendOperations

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

func NewClient added in v1.5.0 

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

NewClient returns a new kvstore client based on the configuration

type Capabilities added in v1.5.0 

type Capabilities uint32

Capabilities is a bitmask to indicate the capabilities of a backend

func GetCapabilities added in v1.5.0 

func GetCapabilities() Capabilities

GetCapabilities returns the capabilities of the backend

type ConsulLocker added in v1.5.5 

type ConsulLocker struct {
	*consulAPI.Lock
}

func (*ConsulLocker) Comparator added in v1.5.5 

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

type EventChan added in v1.5.0 

type EventChan chan KeyValueEvent

EventChan is a channel to receive events on

type EventType added in v1.5.0 

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 added in v1.5.0 

func (t EventType) String() string

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

type ExtraOptions added in v1.5.0 

type ExtraOptions struct {
	DialOption []grpc.DialOption

	// ClusterSizeDependantInterval defines the function to calculate
	// intervals based on cluster size
	ClusterSizeDependantInterval func(baseInterval time.Duration) time.Duration
}

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

func (*ExtraOptions) StatusCheckInterval added in v1.5.0 

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() 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 added in v1.5.0 

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 added in v1.5.0 

type KeyValuePairs map[string]Value

KeyValuePairs is a map of key=value pairs

func ListPrefix added in v1.5.0 

func ListPrefix(prefix string) (KeyValuePairs, error)

ListPrefix returns the list of keys matching the prefix

func ListPrefixIfLocked added in v1.5.5 

func ListPrefixIfLocked(prefix string, lock KVLocker) (KeyValuePairs, error)

ListPrefixIfLocked returns a list of keys matching the prefix only if the client is still holding the given lock.

type Lock added in v1.5.0 

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

Lock is a lock return by LockPath

func LockPath added in v1.5.0 

func LockPath(ctx context.Context, 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 added in v1.5.5 

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

func (*Lock) Unlock added in v1.5.0 

func (l *Lock) Unlock() error

Unlock unlocks a lock

type Value added in v1.5.2 

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 added in v1.5.0 

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 added in v1.5.0 

func ListAndWatch(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 added in v1.5.0 

func (w *Watcher) Stop()

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

func (*Watcher) String added in v1.5.0 

func (w *Watcher) String() string

String returns the name of the wather

Source Files

View all Source files

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.