diff --git a/staging/src/k8s.io/sample-controller/README.md b/staging/src/k8s.io/sample-controller/README.md index 7d2ab57757..207aebd810 100644 --- a/staging/src/k8s.io/sample-controller/README.md +++ b/staging/src/k8s.io/sample-controller/README.md @@ -23,6 +23,13 @@ Changes should not be made to these files manually, and when creating your own controller based off of this implementation you should not copy these files and instead run the `update-codegen` script to generate your own. +## Details + +The sample controller uses [client-go library](https://github.com/kubernetes/client-go/tree/master/tools/cache) extensively. +The details of interaction points of the sample controller with various mechanisms from this library are +explained [here](docs/controller-client-go.md). + + ## Purpose This is an example of how to build a kube-like controller with a single type. diff --git a/staging/src/k8s.io/sample-controller/docs/controller-client-go.md b/staging/src/k8s.io/sample-controller/docs/controller-client-go.md new file mode 100644 index 0000000000..93d24d7259 --- /dev/null +++ b/staging/src/k8s.io/sample-controller/docs/controller-client-go.md @@ -0,0 +1,64 @@ +# client-go under the hood + +The [client-go](https://github.com/kubernetes/client-go/) library contains various mechanisms that you can use when +developing your custom controllers. These mechanisms are defined in the +[tools/cache folder](https://github.com/kubernetes/client-go/tree/master/tools/cache) of the library. + +Here is a pictorial representation showing how the various components in +the client-go library work and their interaction points with the custom +controller code that you will write. + +
+ +
+ +## client-go components + +* Reflector: A reflector, which is defined in [type *Reflector* inside package *cache*](https://github.com/kubernetes/client-go/blob/master/tools/cache/reflector.go), +watches the Kubernetes API for the specified resource type (kind). +The function in which this is done is *ListAndWatch*. +The watch could be for an in-built resource or it could be for a custom resource. +When the reflector receives notification about existence of new +resource instance through the watch API, it gets the newly created object +using the corresponding listing API and puts it in the Delta Fifo queue +inside the *watchHandler* function. + + +* Informer: An informer defined in the [base controller inside package *cache*](https://github.com/kubernetes/client-go/blob/master/tools/cache/controller.go) pops objects from the Delta Fifo queue. +The function in which this is done is *processLoop*. The job of this base controller +is to save the object for later retrieval, and to invoke our controller passing it the object. + +* Indexer: An indexer provides indexing functionality over objects. +It is defined in [type *Indexer* inside package *cache*](https://github.com/kubernetes/client-go/blob/master/tools/cache/index.go). A typical indexing use-case is to create an index based on object labels. Indexer can +maintain indexes based on several indexing functions. +Indexer uses a thread-safe data store to store objects and their keys. +There is a default function named *MetaNamespaceKeyFunc* defined in [type Store inside package cache](https://github.com/kubernetes/client-go/blob/master/tools/cache/store.go) +that generates an object’s key as `