diff --git a/Godeps/Godeps.json b/Godeps/Godeps.json index c7773688..c0a55d4b 100644 --- a/Godeps/Godeps.json +++ b/Godeps/Godeps.json @@ -260,7 +260,7 @@ }, { "ImportPath": "k8s.io/api", - "Rev": "077ce48e77da" + "Rev": "3ab596449d6f" }, { "ImportPath": "k8s.io/apimachinery", diff --git a/go.mod b/go.mod index 8b89718b..08a8bda2 100644 --- a/go.mod +++ b/go.mod @@ -26,7 +26,7 @@ require ( golang.org/x/oauth2 v0.0.0-20190402181905-9f3314589c9a golang.org/x/time v0.0.0-20161028155119-f51c12702a4d google.golang.org/appengine v1.5.0 // indirect - k8s.io/api v0.0.0-20190808180749-077ce48e77da + k8s.io/api v0.0.0-20190809220925-3ab596449d6f k8s.io/apimachinery v0.0.0-20190809020650-423f5d784010 k8s.io/klog v0.3.1 k8s.io/utils v0.0.0-20190801114015-581e00157fb1 @@ -40,6 +40,6 @@ replace ( golang.org/x/sys => golang.org/x/sys v0.0.0-20190209173611-3b5209105503 golang.org/x/text => golang.org/x/text v0.3.1-0.20181227161524-e6919f6577db golang.org/x/tools => golang.org/x/tools v0.0.0-20190313210603-aa82965741a9 - k8s.io/api => k8s.io/api v0.0.0-20190808180749-077ce48e77da + k8s.io/api => k8s.io/api v0.0.0-20190809220925-3ab596449d6f k8s.io/apimachinery => k8s.io/apimachinery v0.0.0-20190809020650-423f5d784010 ) diff --git a/go.sum b/go.sum index bade78c8..a7895224 100644 --- a/go.sum +++ b/go.sum @@ -126,7 +126,7 @@ gopkg.in/yaml.v2 v2.2.1 h1:mUhvW9EsL+naU5Q3cakzfE91YhliOondGd6ZrsDBHQE= gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw= gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -k8s.io/api v0.0.0-20190808180749-077ce48e77da/go.mod h1:irWZZ8fkUYB2+fwyvjN9QMt0m5/1PYsJc1eJElzGHeM= +k8s.io/api v0.0.0-20190809220925-3ab596449d6f/go.mod h1:3Iy+myeAORNCLgjd/Xu9ebwN7Vh59Bw0vh9jhoX+V58= k8s.io/apimachinery v0.0.0-20190809020650-423f5d784010/go.mod h1:Waf/xTS2FGRrgXCkO5FP3XxTOWh0qLf2QhL1qFZZ/R8= k8s.io/gengo v0.0.0-20190128074634-0689ccc1d7d6/go.mod h1:ezvh/TsK7cY6rbqRK0oQQ8IAqLxYwwyPxAX1Pzy0ii0= k8s.io/klog v0.0.0-20181102134211-b9b56d5dfc92/go.mod h1:Gq+BEi5rUBO/HRz0bTSXDUcqjScdoY3a9IHpCEIOOfk= diff --git a/tools/cache/shared_informer.go b/tools/cache/shared_informer.go index a293b222..351c85b9 100644 --- a/tools/cache/shared_informer.go +++ b/tools/cache/shared_informer.go @@ -34,34 +34,49 @@ import ( // SharedInformer provides eventually consistent linkage of its // clients to the authoritative state of a given collection of // objects. An object is identified by its API group, kind/resource, -// namespace, and name. One SharedInformer provides linkage to objects -// of a particular API group and kind/resource. The linked object -// collection of a SharedInformer may be further restricted to one -// namespace and/or by label selector and/or field selector. +// namespace, and name; the `ObjectMeta.UID` is not part of an +// object's ID as far as this contract is concerned. One +// SharedInformer provides linkage to objects of a particular API +// group and kind/resource. The linked object collection of a +// SharedInformer may be further restricted to one namespace and/or by +// label selector and/or field selector. // // The authoritative state of an object is what apiservers provide // access to, and an object goes through a strict sequence of states. -// A state is either "absent" or present with a ResourceVersion and -// other appropriate content. +// An object state is either "absent" or present with a +// ResourceVersion and other appropriate content. // -// A SharedInformer maintains a local cache, exposed by GetStore(), of -// the state of each relevant object. This cache is eventually -// consistent with the authoritative state. This means that, unless -// prevented by persistent communication problems, if ever a -// particular object ID X is authoritatively associated with a state S -// then for every SharedInformer I whose collection includes (X, S) -// eventually either (1) I's cache associates X with S or a later -// state of X, (2) I is stopped, or (3) the authoritative state -// service for X terminates. To be formally complete, we say that the -// absent state meets any restriction by label selector or field -// selector. +// A SharedInformer gets object states from apiservers using a +// sequence of LIST and WATCH operations. Through this sequence the +// apiservers provide a sequence of "collection states" to the +// informer, where each collection state defines the state of every +// object of the collection. No promise --- beyond what is implied by +// other remarks here --- is made about how one informer's sequence of +// collection states relates to a different informer's sequence of +// collection states. +// +// A SharedInformer maintains a local cache, exposed by GetStore() and +// by GetIndexer() in the case of an indexed informer, of the state of +// each relevant object. This cache is eventually consistent with the +// authoritative state. This means that, unless prevented by +// persistent communication problems, if ever a particular object ID X +// is authoritatively associated with a state S then for every +// SharedInformer I whose collection includes (X, S) eventually either +// (1) I's cache associates X with S or a later state of X, (2) I is +// stopped, or (3) the authoritative state service for X terminates. +// To be formally complete, we say that the absent state meets any +// restriction by label selector or field selector. +// +// The local cache starts out empty, and gets populated and updated +// during `Run()`. // // As a simple example, if a collection of objects is henceforeth -// unchanging and a SharedInformer is created that links to that -// collection then that SharedInformer's cache eventually holds an -// exact copy of that collection (unless it is stopped too soon, the -// authoritative state service ends, or communication problems between -// the two persistently thwart achievement). +// unchanging, a SharedInformer is created that links to that +// collection, and that SharedInformer is `Run()` then that +// SharedInformer's cache eventually holds an exact copy of that +// collection (unless it is stopped too soon, the authoritative state +// service ends, or communication problems between the two +// persistently thwart achievement). // // As another simple example, if the local cache ever holds a // non-absent state for some object ID and the object is eventually @@ -70,20 +85,39 @@ import ( // too soon, the authoritative state service ends, or communication // problems persistently thwart the desired result). // -// The keys in GetStore() are of the form namespace/name for namespaced +// The keys in the Store are of the form namespace/name for namespaced // objects, and are simply the name for non-namespaced objects. +// Clients can use `MetaNamespaceKeyFunc(obj)` to extract the key for +// a given object, and `SplitMetaNamespaceKey(key)` to split a key +// into its constituent parts. // // A client is identified here by a ResourceEventHandler. For every -// update to the SharedInformer's local cache and for every client, -// eventually either the SharedInformer is stopped or the client is -// notified of the update. These notifications happen after the -// corresponding cache update and, in the case of a -// SharedIndexInformer, after the corresponding index updates. It is -// possible that additional cache and index updates happen before such -// a prescribed notification. For a given SharedInformer and client, -// all notifications are delivered sequentially. For a given -// SharedInformer, client, and object ID, the notifications are -// delivered in order. +// update to the SharedInformer's local cache and for every client +// added before `Run()`, eventually either the SharedInformer is +// stopped or the client is notified of the update. A client added +// after `Run()` starts gets a startup batch of notifications of +// additions of the object existing in the cache at the time that +// client was added; also, for every update to the SharedInformer's +// local cache after that client was added, eventually either the +// SharedInformer is stopped or that client is notified of that +// update. Client notifications happen after the corresponding cache +// update and, in the case of a SharedIndexInformer, after the +// corresponding index updates. It is possible that additional cache +// and index updates happen before such a prescribed notification. +// For a given SharedInformer and client, the notifications are +// delivered sequentially. For a given SharedInformer, client, and +// object ID, the notifications are delivered in order. +// +// A client must process each notification promptly; a SharedInformer +// is not engineered to deal well with a large backlog of +// notifications to deliver. Lengthy processing should be passed off +// to something else, for example through a +// `client-go/util/workqueue`. +// +// Each query to an informer's local cache --- whether a single-object +// lookup, a list operation, or a use of one of its indices --- is +// answered entirely from one of the collection states received by +// that informer. // // A delete notification exposes the last locally known non-absent // state, except that its ResourceVersion is replaced with a