Merge pull request #457 from pwittrock/book

docs for using client-go gen

Author: k8s-ci-robot

docs/book/SUMMARY.md

@@ -40,6 +40,8 @@
 * Webhooks
   * [What is a Webhook](beyond_basics/what_is_a_webhook.md)
   * [Webhook Example](beyond_basics/sample_webhook.md)
+* Client-Go
+  * [Generated Informers](beyond_basics/using_client_go_informers.md)
 * Deployment Workflow
   * [Deploying the manager in Cluster](beyond_basics/deploying_controller.md)
 

docs/book/beyond_basics/controller_watches.md

@@ -6,7 +6,7 @@ Resources.
 [Link to reference documentation](https://godoc.org/sigs.k8s.io/controller-runtime)
 
 {% method %}
-## Watching Controller Resource
+## Watching the Controller Resource
 
 Controllers may watch Resources and trigger Reconcile calls with the key of the
 object from the watch event. 

docs/book/beyond_basics/using_client_go_informers.md

@@ -0,0 +1,71 @@
+
+# Using Generated Informers
+
+This chapter describes how to use the client-go generated Informers with controller-runtime Watches.
+
+[Link to reference documentation](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/source#Informer)
+
+**Note:** The `source.Informers` and `source.Kind` sources create different caches.  Using both
+`source.Informers` and `source.Kind` sources in the same project will result in duplicate caches.
+This will not impact correctness, but will double the cache memory.
+
+{% method %}
+## Creating client-go generated Informers and Adding them to the Manager
+
+Instantiate the generated InformerFactory and add it to the Manager so it is started automatically.
+
+**Note:** The generated Informer should be used with the generated client.
+
+{% sample lang="go" %}
+```go
+// Create the InformerFactory
+generatedClient := kubernetes.NewForConfigOrDie(mgr.GetConfig())
+generatedInformers := kubeinformers.NewSharedInformerFactory(generatedClient, time.Minute*30)
+
+err := mgr.Add(manager.RunnableFunc(func(s <-chan struct{}) error {
+    generatedInformers.Start(s)
+    return nil
+}))
+if err != nil {
+    glog.Fatalf("error Adding InformerFactory to the Manager: %v", err)
+}
+```
+{% endmethod %}
+
+
+{% method %}
+## Watching Resources using the client-go generated Informer
+
+Controllers may watch Resources using client-go generated Informers though the`source.Informers` struct.
+
+This example configures a Controller to watch for Services events, and to call Reconcile with
+the Service key.
+
+If Service *default/foo* is created, updated or deleted, then Reconcile will be called with
+*namespace: default, name: foo*.
+
+The generated InformerFactory must be manually wired into the Controller creation code.
+
+{% sample lang="go" %}
+```go
+// Setup Watch using the client-go generated Informer
+err := ctrl.Watch(
+    &source.Informer{InformerProvider: generatedInformers.Core().V1().Services()},
+    &handler.EnqueueRequestForObject{},
+)
+if err != nil {
+    glog.Fatalf("error Watching Services: %v", err)
+}
+```
+{% endmethod %}
+
+{% method %}
+## Starting the Manager
+
+The InformerFactory will be started through the Manager.
+
+{% sample lang="go" %}
+```go
+mgr.Start(signals.SetupSignalHandler())
+```
+{% endmethod %}