update

Author: Zhang Jun

client-go/3.listwatch-reflector.md

@@ -2,66 +2,18 @@
 
 Reflector 是 Kubernetes 的事件反射器，它 List 和 Watch etcd 中的资源对象变化，将其更新到内部的 DeltaFIFO 中。
 
-在介绍 Relfector 前，先介绍 Reflector 使用的 ListerWatcher 接口；
-
-func NewIndexerInformer(
-	lw ListerWatcher,
-	objType runtime.Object,
-	resyncPeriod time.Duration,
-	h ResourceEventHandler,
-	indexers Indexers,
-) (Indexer, Controller) 
-
--> 创建 controller
-// Config contains all the settings for a Controller.
-type Config struct {
-	...
-	// Something that can list and watch your objects.
-	ListerWatcher
-	...
-}
-
--> 创建 Reflector（c.config.ListerWatcher 是传给 NewIndexerInformer(）的 lw）：
-func (c *controller) Run(stopCh <-chan struct{}) {
-	...
-	r := NewReflector(
-		c.config.ListerWatcher,
-		c.config.ObjectType,
-		c.config.Queue,
-		c.config.FullResyncPeriod,
-	)
-	...
-	c.reflector = r
-	...
-}
+在介绍 Relfector 前，先介绍 Reflector 使用的 ListerWatcher 接口。
 
--> ListAndWatch
-func (r *Reflector) ListAndWatch(stopCh <-chan struct{}) error {
-	options := metav1.ListOptions{ResourceVersion: "0"}
-	list, err := r.listerWatcher.List(options)
-	...
-	for {
-		options = metav1.ListOptions{
-			ResourceVersion: resourceVersion,
-			TimeoutSeconds: &timeoutSeconds,
-		}
-		...
-		w, err := r.listerWatcher.Watch(options)
-		...
-		if err := r.watchHandler(w, &resourceVersion, resyncerrc, stopCh); err != nil {
-			...
-		}
-	}
-}
+## ListWatcher 接口
 
-## ListAndWatch
+ListWatcher 接口定义了 List 和 Watch 特定资源类型的方法。
 
-// ListerWatcher is any object that knows how to perform an initial list and start a watch on a resource.
+``` go
+// 来源于 k8s.io/client-go/tools/cache/listwatch.go
 type ListerWatcher interface {
-	// List should return a list type object; the Items field will be extracted, and the
-	// ResourceVersion field will be used to start the watch in the right place.
+	// List() 返回对象列表；从这些对象中提取 ResourceVersion，用户后续的 Watch() 方法参数；
 	List(options metav1.ListOptions) (runtime.Object, error)
-	// Watch should begin a watch at the specified version.
+	// Watch() 方法从指定的版本(options 中指定)开始 Watch。
 	Watch(options metav1.ListOptions) (watch.Interface, error)
 }
 
@@ -71,32 +23,35 @@ type ListFunc func(options metav1.ListOptions) (runtime.Object, error)
 // WatchFunc knows how to watch resources
 type WatchFunc func(options metav1.ListOptions) (watch.Interface, error)
 
-// ListWatch knows how to list and watch a set of apiserver resources.  It satisfies the ListerWatcher interface.
-// It is a convenience function for users of NewReflector, etc.
-// ListFunc and WatchFunc must not be nil
+// Getter interface knows how to access Get method from RESTClient.
+type Getter interface {
+	Get() *restclient.Request
+}
+```
+
+## 实现 ListWatcher 接口的类型 ListWatch
+
+ListWatch 类型实现了 `ListWatcher` 接口，被 `NewReflector()` 函数和各 K8S 内置资源对象的 `NewFilteredXXXInformer()` 函数(见后文)使用。
+``` go
+// 来源于 k8s.io/client-go/tools/cache/listwatch.go
 type ListWatch struct {
 	ListFunc  ListFunc
 	WatchFunc WatchFunc
-	// DisableChunking requests no chunking for this list watcher.
 	DisableChunking bool
 }
+```
 
-// Getter interface knows how to access Get method from RESTClient.
-type Getter interface {
-	Get() *restclient.Request
-}
+函数 `NewListWatchFromClient()` 和 `NewFilteredListWatchFromClient()` 返回 ListWatch 对象，传入的 Getter 参数是 K8S 特定资源类型的 Client：
 
-// NewListWatchFromClient creates a new ListWatch from the specified client, resource, namespace and field selector.
+``` go
+// 来源于 k8s.io/client-go/tools/cache/listwatch.go
 func NewListWatchFromClient(c Getter, resource string, namespace string, fieldSelector fields.Selector) *ListWatch {
 	optionsModifier := func(options *metav1.ListOptions) {
 		options.FieldSelector = fieldSelector.String()
 	}
 	return NewFilteredListWatchFromClient(c, resource, namespace, optionsModifier)
 }
 
-// NewFilteredListWatchFromClient creates a new ListWatch from the specified client, resource, namespace, and option modifier.
-// Option modifier is a function takes a ListOptions and modifies the consumed ListOptions. Provide customized modifier function
-// to apply modification to ListOptions with a field selector, a label selector, or any other desired options.
 func NewFilteredListWatchFromClient(c Getter, resource string, namespace string, optionsModifier func(options *metav1.ListOptions)) *ListWatch {
 	listFunc := func(options metav1.ListOptions) (runtime.Object, error) {
 		optionsModifier(&options)
@@ -118,21 +73,61 @@ func NewFilteredListWatchFromClient(c Getter, resource string, namespace string,
 	}
 	return &ListWatch{ListFunc: listFunc, WatchFunc: watchFunc}
 }
+```
+
+### List() 方法
+
+List() 方法调用 K8S Client 从 apiserver 获取一批特定类型对象列表：
 
+``` go
+// 来源于 k8s.io/client-go/tools/cache/listwatch.go
 // List a set of apiserver resources
 func (lw *ListWatch) List(options metav1.ListOptions) (runtime.Object, error) {
 	if !lw.DisableChunking {
 		return pager.New(pager.SimplePageFunc(lw.ListFunc)).List(context.TODO(), options)
 	}
 	return lw.ListFunc(options)
 }
+```
 
+### Watch() 方法
+
+``` go
+// 来源于 k8s.io/client-go/tools/cache/listwatch.go
 // Watch a set of apiserver resources
 func (lw *ListWatch) Watch(options metav1.ListOptions) (watch.Interface, error) {
 	return lw.WatchFunc(options)
 }
+```
+
+## 使用 ListWatch 的 K8S 资源对象
+
+``` go
+// 来源于 k8s.io/client-go/informers/extensions/v1beta1/deployment.go
+func NewFilteredDeploymentInformer(client kubernetes.Interface, namespace string, resyncPeriod time.Duration, indexers cache.Indexers, tweakListOptions internalinterfaces.TweakListOptionsFunc) cache.SharedIndexInformer {
+	return cache.NewSharedIndexInformer(
+		&cache.ListWatch{
+			ListFunc: func(options v1.ListOptions) (runtime.Object, error) {
+				if tweakListOptions != nil {
+					tweakListOptions(&options)
+				}
+				return client.ExtensionsV1beta1().Deployments(namespace).List(options)
+			},
+			WatchFunc: func(options v1.ListOptions) (watch.Interface, error) {
+				if tweakListOptions != nil {
+					tweakListOptions(&options)
+				}
+				return client.ExtensionsV1beta1().Deployments(namespace).Watch(options)
+			},
+		},
+		&extensionsv1beta1.Deployment{},
+		resyncPeriod,
+		indexers,
+	)
+}
+```
 
-## 
+##
 
 ``` go
 func (r *Reflector) Run(stopCh <-chan struct{}) {