tools

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 11, 2015 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package tools implements types which help work with etcd which depend on the api package. TODO: move this package to an etcd specific utility package.

Index

Constants

View Source 
const (
	EtcdCreate = "create"
	EtcdGet    = "get"
	EtcdSet    = "set"
	EtcdCAS    = "compareAndSwap"
	EtcdDelete = "delete"
)

Etcd watch event actions

View Source 
const (
	EtcdErrorCodeNotFound      = 100
	EtcdErrorCodeTestFailed    = 101
	EtcdErrorCodeNodeExist     = 105
	EtcdErrorCodeValueRequired = 200
)

Variables

View Source 
var (
	EtcdErrorNotFound      = &etcd.EtcdError{ErrorCode: EtcdErrorCodeNotFound}
	EtcdErrorTestFailed    = &etcd.EtcdError{ErrorCode: EtcdErrorCodeTestFailed}
	EtcdErrorNodeExist     = &etcd.EtcdError{ErrorCode: EtcdErrorCodeNodeExist}
	EtcdErrorValueRequired = &etcd.EtcdError{ErrorCode: EtcdErrorCodeValueRequired}
)

Functions

func EtcdHealthCheck added in v0.20.1 

func EtcdHealthCheck(data []byte) error

func Everything 

func Everything(runtime.Object) bool

Everything is a FilterFunc which accepts all objects.

func GetEtcdVersion added in v0.13.1 

func GetEtcdVersion(host string) (string, error)

GetEtcdVersion performs a version check against the provided Etcd server, returning the string response, and error (if any).

func IsEtcdNodeExist 

func IsEtcdNodeExist(err error) bool

IsEtcdNodeExist returns true iff err is an etcd node aleady exist error.

func IsEtcdNotFound 

func IsEtcdNotFound(err error) bool

IsEtcdNotFound returns true iff err is an etcd not found error.

func IsEtcdTestFailed 

func IsEtcdTestFailed(err error) bool

IsEtcdTestFailed returns true iff err is an etcd write conflict.

func IsEtcdWatchStoppedByUser 

func IsEtcdWatchStoppedByUser(err error) bool

IsEtcdWatchStoppedByUser returns true iff err is a client triggered stop.

func ParseWatchResourceVersion added in v0.5.2 

func ParseWatchResourceVersion(resourceVersion, kind string) (uint64, error)

ParseWatchResourceVersion takes a resource version argument and converts it to the etcd version we should pass to helper.Watch(). Because resourceVersion is an opaque value, the default watch behavior for non-zero watch is to watch the next value (if you pass "1", you will see updates from "2" onwards).

Types

type APIObjectVersioner added in v0.13.1 

type APIObjectVersioner struct{}

APIObjectVersioner implements versioning and extracting etcd node information for objects that have an embedded ObjectMeta or ListMeta field.

func (APIObjectVersioner) ObjectResourceVersion added in v0.13.1 

func (a APIObjectVersioner) ObjectResourceVersion(obj runtime.Object) (uint64, error)

ObjectResourceVersion implements EtcdVersioner

func (APIObjectVersioner) UpdateList added in v0.13.1 

func (a APIObjectVersioner) UpdateList(obj runtime.Object, resourceVersion uint64) error

UpdateList implements EtcdVersioner

func (APIObjectVersioner) UpdateObject added in v0.13.1 

func (a APIObjectVersioner) UpdateObject(obj runtime.Object, expiration *time.Time, resourceVersion uint64) error

UpdateObject implements EtcdVersioner

type EtcdClient 

type EtcdClient interface {
	GetCluster() []string
	AddChild(key, data string, ttl uint64) (*etcd.Response, error)
	Get(key string, sort, recursive bool) (*etcd.Response, error)
	Set(key, value string, ttl uint64) (*etcd.Response, error)
	Create(key, value string, ttl uint64) (*etcd.Response, error)
	CompareAndSwap(key, value string, ttl uint64, prevValue string, prevIndex uint64) (*etcd.Response, error)
	Delete(key string, recursive bool) (*etcd.Response, error)
	// I'd like to use directional channels here (e.g. <-chan) but this interface mimics
	// the etcd client interface which doesn't, and it doesn't seem worth it to wrap the api.
	Watch(prefix string, waitIndex uint64, recursive bool, receiver chan *etcd.Response, stop chan bool) (*etcd.Response, error)
}

EtcdClient is an injectable interface for testing.

func NewEtcdClientStartServerIfNecessary added in v0.5.2 

func NewEtcdClientStartServerIfNecessary(server string) (EtcdClient, error)

type EtcdGetSet 

type EtcdGetSet interface {
	GetCluster() []string
	Get(key string, sort, recursive bool) (*etcd.Response, error)
	Set(key, value string, ttl uint64) (*etcd.Response, error)
	Create(key, value string, ttl uint64) (*etcd.Response, error)
	Delete(key string, recursive bool) (*etcd.Response, error)
	CompareAndSwap(key, value string, ttl uint64, prevValue string, prevIndex uint64) (*etcd.Response, error)
	Watch(prefix string, waitIndex uint64, recursive bool, receiver chan *etcd.Response, stop chan bool) (*etcd.Response, error)
}

EtcdGetSet interface exposes only the etcd operations needed by EtcdHelper.

type EtcdHelper 

type EtcdHelper struct {
	Client EtcdGetSet
	Codec  runtime.Codec
	Copier runtime.ObjectCopier
	// optional, no atomic operations can be performed without this interface
	Versioner EtcdVersioner
	// prefix for all etcd keys
	PathPrefix string
	// contains filtered or unexported fields
}

EtcdHelper offers common object marshalling/unmarshalling operations on an etcd client.

func NewEtcdHelper added in v0.13.1 

func NewEtcdHelper(client EtcdGetSet, codec runtime.Codec, prefix string) EtcdHelper

NewEtcdHelper creates a helper that works against objects that use the internal Kubernetes API objects. TODO: Refactor to take a runtiem.ObjectCopier

func (*EtcdHelper) CreateObj 

func (h *EtcdHelper) CreateObj(key string, obj, out runtime.Object, ttl uint64) error

CreateObj adds a new object at a key unless it already exists. 'ttl' is time-to-live in seconds, and 0 means forever. If no error is returned and out is not nil, out will be set to the read value from etcd.

func (*EtcdHelper) Delete 

func (h *EtcdHelper) Delete(key string, recursive bool) error

Delete removes the specified key.

func (*EtcdHelper) DeleteObj added in v0.13.1 

func (h *EtcdHelper) DeleteObj(key string, out runtime.Object) error

DeleteObj removes the specified key and returns the value that existed at that spot.

func (*EtcdHelper) ExtractObj 

func (h *EtcdHelper) ExtractObj(key string, objPtr runtime.Object, ignoreNotFound bool) error

ExtractObj unmarshals json found at key into objPtr. On a not found error, will either return a zero object of the requested type, or an error, depending on ignoreNotFound. Treats empty responses and nil response nodes exactly like a not found error.

func (*EtcdHelper) ExtractObjToList added in v0.18.2 

func (h *EtcdHelper) ExtractObjToList(key string, listObj runtime.Object) error

ExtractObjToList unmarshals json found at key and opaques it into a *List api object (an object that satisfies the runtime.IsList definition).

func (*EtcdHelper) ExtractToList 

func (h *EtcdHelper) ExtractToList(key string, listObj runtime.Object) error

ExtractToList works on a *List api object (an object that satisfies the runtime.IsList definition) and extracts a go object per etcd node into a slice with the resource version.

func (*EtcdHelper) GuaranteedUpdate added in v0.18.2 

func (h *EtcdHelper) GuaranteedUpdate(key string, ptrToType runtime.Object, ignoreNotFound bool, tryUpdate EtcdUpdateFunc) error

GuaranteedUpdate calls "tryUpdate()" to update key "key" that is of type "ptrToType". It keeps calling tryUpdate() and retrying the update until success if there is etcd index conflict. Note that object passed to tryUpdate() may change across invocations of tryUpdate() if other writers are simultaneously updating it, so tryUpdate() needs to take into account the current contents of the object when deciding how the updated object (that it returns) should look.

Example:

h := &util.EtcdHelper{client, encoding, versioning} 

err := h.GuaranteedUpdate("myKey", &MyType{}, true, func(input runtime.Object, res ResponseMeta) (runtime.Object, *uint64, error) {
	// Before each invocation of the user-defined function, "input" is reset to etcd's current contents for "myKey".

	cur := input.(*MyType) // Guaranteed to succeed.

	// Make a *modification*.
	cur.Counter++

	// Return the modified object. Return an error to stop iterating. Return a uint64 to alter
     // the TTL on the object, or nil to keep it the same value.
	return cur, nil, nil
})

func (*EtcdHelper) MigrateKeys added in v0.18.2 

func (h *EtcdHelper) MigrateKeys(oldPathPrefix string) error

Copies the key-value pairs from their old location to a new location based on this helper's etcd prefix. All old keys without the prefix are then deleted.

func (*EtcdHelper) PrefixEtcdKey added in v0.18.2 

func (h *EtcdHelper) PrefixEtcdKey(key string) string

func (*EtcdHelper) SetObj 

func (h *EtcdHelper) SetObj(key string, obj, out runtime.Object, ttl uint64) error

SetObj marshals obj via json, and stores under key. Will do an atomic update if obj's ResourceVersion field is set. 'ttl' is time-to-live in seconds, and 0 means forever. If no error is returned and out is not nil, out will be set to the read value from etcd.

func (*EtcdHelper) Watch 

func (h *EtcdHelper) Watch(key string, resourceVersion uint64, filter FilterFunc) (watch.Interface, error)

Watch begins watching the specified key. Events are decoded into API objects and sent down the returned watch.Interface. Errors will be sent down the channel.

func (*EtcdHelper) WatchAndTransform 

func (h *EtcdHelper) WatchAndTransform(key string, resourceVersion uint64, transform TransformFunc) watch.Interface

WatchAndTransform begins watching the specified key. Events are decoded into API objects and sent down the returned watch.Interface. If the transform function is provided, the value decoded from etcd will be passed to the function prior to being returned.

The transform function can be used to populate data not available to etcd, or to change or wrap the serialized etcd object. 

startTime := time.Now()
helper.WatchAndTransform(key, version, func(input runtime.Object) (runtime.Object, error) {
  value := input.(TimeAwareValue)
  value.Since = startTime
  return value, nil
})

Errors will be sent down the channel.

func (*EtcdHelper) WatchList 

func (h *EtcdHelper) WatchList(key string, resourceVersion uint64, filter FilterFunc) (watch.Interface, error)

WatchList begins watching the specified key's items. Items are decoded into API objects, and any items passing 'filter' are sent down the returned watch.Interface. resourceVersion may be used to specify what version to begin watching (e.g., for reconnecting without missing any updates).

type EtcdResponseWithError 

type EtcdResponseWithError struct {
	R *etcd.Response
	E error
	// if N is non-null, it will be assigned into the map after this response is used for an operation
	N *EtcdResponseWithError
}

type EtcdUpdateFunc 

type EtcdUpdateFunc func(input runtime.Object, res ResponseMeta) (output runtime.Object, ttl *uint64, err error)

Pass an EtcdUpdateFunc to EtcdHelper.GuaranteedUpdate to make an etcd update that is guaranteed to succeed. See the comment for GuaranteedUpdate for more detail.

func SimpleUpdate added in v0.20.1 

func SimpleUpdate(fn SimpleEtcdUpdateFunc) EtcdUpdateFunc

SimpleUpdateFunc converts SimpleEtcdUpdateFunc into EtcdUpdateFunc

type EtcdVersioner added in v0.13.1 

type EtcdVersioner interface {
	// UpdateObject sets etcd storage metadata into an API object. Returns an error if the object
	// cannot be updated correctly. May return nil if the requested object does not need metadata
	// from etcd.
	UpdateObject(obj runtime.Object, expiration *time.Time, resourceVersion uint64) error
	// UpdateList sets the resource version into an API list object. Returns an error if the object
	// cannot be updated correctly. May return nil if the requested object does not need metadata
	// from etcd.
	UpdateList(obj runtime.Object, resourceVersion uint64) error
	// ObjectResourceVersion returns the resource version (for persistence) of the specified object.
	// Should return an error if the specified object does not have a persistable version.
	ObjectResourceVersion(obj runtime.Object) (uint64, error)
}

EtcdVersioner abstracts setting and retrieving fields from the etcd response onto the object or list.

type FakeEtcdClient 

type FakeEtcdClient struct {
	Data        map[string]EtcdResponseWithError
	DeletedKeys []string

	sync.Mutex
	Err    error
	CasErr error

	Ix          int
	TestIndex   bool
	ChangeIndex uint64
	LastSetTTL  uint64
	Machines    []string

	// Will become valid after Watch is called; tester may write to it. Tester may
	// also read from it to verify that it's closed after injecting an error.
	WatchResponse chan *etcd.Response
	WatchIndex    uint64
	// Write to this to prematurely stop a Watch that is running in a goroutine.
	WatchInjectError chan<- error
	WatchStop        chan<- bool
	// If non-nil, will be returned immediately when Watch is called.
	WatchImmediateError error
	// contains filtered or unexported fields
}

func NewFakeEtcdClient 

func NewFakeEtcdClient(t TestLogger) *FakeEtcdClient

func (*FakeEtcdClient) AddChild 

func (f *FakeEtcdClient) AddChild(key, data string, ttl uint64) (*etcd.Response, error)

func (*FakeEtcdClient) CompareAndSwap 

func (f *FakeEtcdClient) CompareAndSwap(key, value string, ttl uint64, prevValue string, prevIndex uint64) (*etcd.Response, error)

func (*FakeEtcdClient) Create 

func (f *FakeEtcdClient) Create(key, value string, ttl uint64) (*etcd.Response, error)

func (*FakeEtcdClient) Delete 

func (f *FakeEtcdClient) Delete(key string, recursive bool) (*etcd.Response, error)

func (*FakeEtcdClient) ExpectNotFoundGet 

func (f *FakeEtcdClient) ExpectNotFoundGet(key string)

func (*FakeEtcdClient) Get 

func (f *FakeEtcdClient) Get(key string, sort, recursive bool) (*etcd.Response, error)

func (*FakeEtcdClient) GetCluster added in v0.5.2 

func (f *FakeEtcdClient) GetCluster() []string

func (*FakeEtcdClient) NewError added in v0.13.1 

func (f *FakeEtcdClient) NewError(code int) *etcd.EtcdError

func (*FakeEtcdClient) Set 

func (f *FakeEtcdClient) Set(key, value string, ttl uint64) (*etcd.Response, error)

func (*FakeEtcdClient) SetError added in v0.13.1 

func (f *FakeEtcdClient) SetError(err error)

func (*FakeEtcdClient) WaitForWatchCompletion 

func (f *FakeEtcdClient) WaitForWatchCompletion()

func (*FakeEtcdClient) Watch 

func (f *FakeEtcdClient) Watch(prefix string, waitIndex uint64, recursive bool, receiver chan *etcd.Response, stop chan bool) (*etcd.Response, error)

type FilterFunc 

type FilterFunc func(obj runtime.Object) bool

FilterFunc is a predicate which takes an API object and returns true iff the object should remain in the set.

type ResponseMeta added in v0.20.1 

type ResponseMeta struct {
	// TTL is the time to live of the node that contained the returned object. It may be
	// zero or negative in some cases (objects may be expired after the requested
	// expiration time due to server lag).
	TTL int64
	// Expiration is the time at which the node that contained the returned object will expire and be deleted.
	// This can be nil if there is no expiration time set for the node.
	Expiration *time.Time
	// The resource version of the node that contained the returned object.
	ResourceVersion uint64
}

ResponseMeta contains information about the etcd metadata that is associated with an object. It abstracts the actual underlying objects to prevent coupling with etcd and to improve testability.

type SimpleEtcdUpdateFunc added in v0.20.1 

type SimpleEtcdUpdateFunc func(runtime.Object) (runtime.Object, error)

type TestLogger 

type TestLogger interface {
	Fatalf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
	Logf(format string, args ...interface{})
}

TestLogger is a type passed to Test functions to support formatted test logs.

type TransformFunc 

type TransformFunc func(runtime.Object) (runtime.Object, error)

TransformFunc attempts to convert an object to another object for use with a watcher.

Source Files

View all Source files

Directories

Path Synopsis

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.