client-go系列之4---Indexer

1. 写在前面

个人主页: https://gzh.readthedocs.io

关注容器技术、关注Kubernetes。

问题或建议，请公众号（double12gzh）留言。

在本系列教程的第一篇中，我们已经对如下这张图作了简单介绍。这张图非常重要，理解这张图对我们正确理解client-go及Controller非常有帮助(出处)。

client-go中对其实现的代码位于tools/cache，如下图：

除了上图中展示的Indexer的定义比较重要外，我们还需要关注Indexer比较重要的数据结构：

[root@xxxx-wsl /ACode/client-go] cat tools/cache/index.go| grep -B 1 -A 1 type

// IndexFunc knows how to compute the set of indexed values for an object.
type IndexFunc func(obj interface{}) ([]string, error)

--
// Index maps the indexed value to a set of keys in the store that match on that value
type Index map[string]sets.String

// Indexers maps a name to a IndexFunc
type Indexers map[string]IndexFunc

// Indices maps a name to an Index
type Indices map[string]Index

IndexFunc: 从接收的资源对象中，根据一系列的key来获取相应的值。
Index: 建立key与被索引值的对应关系并存储到Store中，即它里面的数据都是Key/Value的形式。
Indexers: 存储的是索引器的名字与索引器的实现函数。
Indices: 存储缓存数据，形式Key/Value，其中Key为缓存器的字，Value为缓存数据。

2. Custom Controller中的组件

如图中所示，Custom Controller是位于下半部分的内容。从图中可以很容易的看到，一个Custom Controller主要包含以下内容：

Indexer Reference
Informer Reference
Resource Event Handler
WorkQueue
ProcessItem

2.1 Indexer

2.1.1 简单介绍

它是一个知道如何使用CRD对象的 Indexer 实例的引用(reference)。当我们写自定义控制器(Custom Controller)代码时，将使用这个reference去做对象检索。

Indexer是client-go中实现的一个本地存储，它可以建立索引并存储Resource的对象。Reflector通过Delta FIFO Queue将资源对象存储到Indexer中。

需要注意的是，Indexer中的数据与etcd中的数据是完全一致的，这样client-go需要数据时，无须每次都从api-server获取，从而减少了请求过多造成对api-server的压力。

一句话总结：Indexer是用于存储+快速查找资源，即它的目的就是为了能够进行快速查找。

Indexer是如何实现“存储+快速查找资源”的呢？我们来看一下下面这张图，通过这张图方便我们理解一下Indexer的存储结构：

说明：图中的Indexers与Indices虽然都指向了相同的IndexFunc，这并不是说二者的数据是相同的，而是说二者使用的IndexFunc是相同的。

根据上面这个图，我们可以简单的规纳出与之对应的数据结构：

// 包含的所有索引器/分类以及对应的实现
Indexers: {  
    "namespace": NamespaceIndexFunc,
    "nodeName": NodeNameIndexFunc,
}

// 包含的所有索引分类中所有的索引数据
Indices: {
    //namespace 这个索引分类下的所有索引数据
    "namespace": {  
         // Index 就是一个索引键下所有的对象键列表
        "default": ["pod-1", "pod-2"], 
        // Index
        "kube-system": ["pod-3"]   
    },

    //nodeName 这个索引分类下的所有索引数据(对象键列表)
    "nodeName": {
         // Index
        "node1": ["pod-1"],
         // Index
        "node2": ["pod-2", "pod-3"]
    }
}

Indexers和Indices都是按照IndexFunc(名字)分组，每个IndexFunc输出多个IndexKey，产生相同IndexKey的多个对象存储在一个集合中。

IndexKey主要是用于快速查找ObjectKey; 而ObjectKey是对象存储时唯一命名的key(这个key方便在存储中快速找到相应的对象)。

2.1.2 代码位置

$GOPATH/pkg/mod/k8s.io/client-go@v0.19.0/tools/cache/index.go

2.1.3 类图展示

从下图我们可以很容易的看到Indexer与cache、Store及ThreadSafeStore之间的调用关系。

上图如果长时间无法显示，请参考这里

Store: 是一个通用对象存储和处理接口。

26 // Store is a generic object storage and processing interface.  A
27 // Store holds a map from string keys to accumulators, and has
28 // operations to add, update, and delete a given object to/from the
29 // accumulator currently associated with a given key.  A Store also
30 // knows how to extract the key from a given object, so many operations
31 // are given only the object.
32 //
33 // In the simplest Store implementations each accumulator is simply
34 // the last given object, or empty after Delete, and thus the Store's
35 // behavior is simple storage.
36 //
37 // Reflector knows how to watch a server and update a Store.  This
38 // package provides a variety of implementations of Store.
39 type Store interface {
40
41     // Add adds the given object to the accumulator associated with the given object's key
42     Add(obj interface{}) error
43
44     // Update updates the given object in the accumulator associated with the given object's key
45     Update(obj interface{}) error
46
47     // Delete deletes the given object from the accumulator associated with the given object's key
48     Delete(obj interface{}) error
49
50     // List returns a list of all the currently non-empty accumulators
51     List() []interface{}
52
53     // ListKeys returns a list of all the keys currently associated with non-empty accumulators
54     ListKeys() []string
55
56     // Get returns the accumulator associated with the given object's key
57     Get(obj interface{}) (item interface{}, exists bool, err error)
58
59     // GetByKey returns the accumulator associated with the given key
60     GetByKey(key string) (item interface{}, exists bool, err error)
61
62     // Replace will delete the contents of the store, using instead the
63     // given list. Store takes ownership of the list, you should not reference
64     // it after calling this function.
65     Replace([]interface{}, string) error
66
67     // Resync is meaningless in the terms appearing here but has
68     // meaning in some implementations that have non-trivial
69     // additional behavior (e.g., DeltaFIFO).
70     Resync() error
71 }

Indexer: 扩展了多个索引的 Store，并限制每个累加器只保存当前对象（删除后为空）。
ThreadSafeStore: 与Indexer类似，是一个允许对存储后端进行并发索引访问的接口

cache: 根据 ThreadSafeStore 和关联的 KeyFunc 实现的 Indexer。所有的对象都缓存在内存中，这不是一个外部可以调用的对象，在包的外部不能直接调用cache。它的定义也比较简单，如下：

131 // 代码位置：client-go/tools/cache/store.go
132 // `*cache` implements Indexer in terms of a ThreadSafeStore and an
133 // associated KeyFunc.
134 type cache struct {
135     // cacheStorage bears the burden of thread safety for the cache
136     cacheStorage ThreadSafeStore
137     // keyFunc is used to make the key for objects stored in and retrieved from items, and
138     // should be deterministic.
139     keyFunc KeyFunc
140 }

我们可以使用NewStore或NewIndexer来实例化一个Store或Indexer。

threadSafeMap : 是 ThreadSafeStore的实现，它实现了并发安全的存储(它是一个内存中的存储)，具备CRUD等操作。它其中包含了三个比较重要的属性，见代码：
```
61 // 代码位置：client-go/tools/cache/thread_safe_store.go
62 // threadSafeMap implements ThreadSafeStore
63 type threadSafeMap struct {
64     lock  sync.RWMutex
65     items map[string]interface{} //用于保存数据
66
67     // indexers maps a name to an IndexFunc
68     indexers Indexers
69     // indices maps a name to an Index
70     indices Indices
71 }
```
对于threadSafeMap中各种索引的关系，我们可以用下图来表示：

threadSafeMap其实只会做两件事情：存储，索引。存储即存储runtime.object到items这个Map中；索引即为items这个Map建立三层索引：indices的Map类型的索引(如：namespace, nodeName等)；index Map的类型索引(如： namespace1, namespace2, ...); runtime.object的索引。

如果我们需要向threadSafeMap中添加一个对象，只需要调用下以代码即可：
```
72 // 代码位置：client-go/tools/cache/thread_safe_store.go
73 func (c *threadSafeMap) Add(key string, obj interface{}) {
74     c.lock.Lock()
75     defer c.lock.Unlock()
76     oldObject := c.items[key]
77     c.items[key] = obj
78     c.updateIndices(oldObject, obj, key)
79 }
```
如果想了解更多的细节，请查看updateIndices()

另外，从图中我们也可以看出，Indexer实际上是对threadSafeMap的封装，它继承了后者的所有方法，同时也实现了IndexFunc。

2.2 Indexer索引器实现

在kubernetes中使用的比较多的索引函数是MetaNamespaceIndexFunc()（代码位置: client-go/tools/cache/index.go）。

Indexer索引的实现是通过index.ByIndex来完成的，index.ByIndex的代码如下：

178 // 代码位置：client-go/tools/cache/thread_safe_store.go
179 // ByIndex returns a list of the items whose indexed values in the given index include the given indexed value
180 func (c *threadSafeMap) ByIndex(indexName, indexedValue string) ([]interface{}, error) {
181     c.lock.RLock()
182     defer c.lock.RUnlock()
183
184     indexFunc := c.indexers[indexName]  // 关键代码。获取索引器函数。
185     if indexFunc == nil {
186         return nil, fmt.Errorf("Index with name %s does not exist", indexName)
187     }
188
189     index := c.indices[indexName]   // 关键代码。获取缓存器函数。
190
191     set := index[indexedValue]    // 关键代码。Index中的数据以Set类型存储在缓存中。
192     list := make([]interface{}, 0, set.Len())
193     for key := range set {
194         list = append(list, c.items[key])
195     }
196
197     return list, nil
198 }

上述方法接收两个参数:

indexName: 索引器的名字
indexedValue: 需要索引的key

此方法的基本思路如下：

根据索引器名字查找指定的索引器函数(c.indexers[indexName])
根据索引器名字查找相应的缓存器函数(c.indices[indexName])
根据索引key(即：indexedValue)从缓存中进行数据查询，并返回查询结果