Improve gitbook language and add test section

docs/book/README.md

@@ -1,3 +1,7 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
 # Introduction
 
 ## Who is this for

docs/book/SUMMARY.md

@@ -13,12 +13,14 @@
 
 * Development Workflow
   * [Project Creation and Structure](basics/project_creation_and_structure.md)
+  * [Running Tests](basics/running_tests.md)
 * Resource Fundamentals
   * [What is a Resource](basics/what_is_a_resource.md)
   * [Simple Resource Example](basics/simple_resource.md)
 * Controller Fundamentals
   * [What is a Contoller](basics/what_is_a_controller.md)
   * [Simple Controller Example](basics/simple_controller.md)
+  * [Controller Watch Functions](basics/controller_watches.md)
 * Controller-Manager Fundamentals
   * [What is the Controller-Manager](basics/what_is_the_controller_manager.md)
   * [Simple Controller-Manager](basics/simple_controller_manager.md)

docs/book/basics/controller_watches.md

@@ -0,0 +1,141 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
+# Controller Watch Functions
+
+This chapter describes how to use the controller package functions to configure Controllers to watch
+Resources.
+
+[Link to reference documentation](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller)
+
+{% method %}
+## Watching Controller Resource
+
+Controllers may watch Resources and trigger Reconcile calls with the key of the
+object from the watch event. 
+
+This example configures a controller to watch for Pod events, and call Reconcile with
+the Pod key.
+
+If Pod *default/foo* is created, updated or deleted, then Reconcile will be called with
+*namespace: default, name: foo*
+
+{% sample lang="go" %}
+```go
+if err := c.Watch(&v1.Pod{}); err != nil {
+    log.Fatalf("%v", err)
+}
+```
+{% endmethod %}
+
+
+{% method %}
+## Watching Created Resources
+
+Controllers may watch Resources of types they create and trigger Reconcile calls with the key of
+the Owner of the object.
+
+This example configures a Controller to watch for Pod events, and call Reconcile with
+the Owner ReplicaSet key.  This is done by looking up the object referred to by the Owner reference
+from the watch event object.
+
+- Define a function to lookup the Owner from the key
+- Call `WatchControllerOf` with the Owned object and the function to lookup the owner
+
+If Pod *default/foo-pod* was created by ReplicaSet *default/foo-rs*, and the Pod is
+(re)created, updated or deleted, then Reconcile will be called with *namespace: default, name: foo-rs*
+
+**Note:** This requires adding the following annotations to your Controller struct to ensure the
+correct RBAC rules are in place and informers have been started.
+
+```go
+// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list
+// +kubebuilder:informers:group=core,version=v1,kind=Pod
+```
+
+{% sample lang="go" %}
+```go
+fn := func(k types.ReconcileKey) (interface{}, error) {
+    return informerFactory.
+    	Apps().V1().
+    	ReplicaSets().
+    	Lister().
+    	ReplicaSets(k.Namespace).Get(k.Name)
+}
+if err := c.WatchControllerOf(
+	&corev1.Pod{}, eventhandlers.Path{fn}
+); err != nil {
+    log.Fatalf("%v", err)
+}
+```
+{% endmethod %}
+
+{% method %}
+## Watching Arbitrary Resources
+
+Controllers may watch arbitrary Resources and map them to a key of the Resource managed by the
+controller.  Controllers may even map an event to multiple keys, triggering Reconciles for
+each key.
+
+Example: To respond to cluster scaling events (e.g. the deletion or addition of Nodes),
+a Controller would watch Nodes and map the watch events to keys of objects managed by
+the controller.
+
+This simple example configures a Controller to watch for Pod events, and then reconciles objects with
+names derived from the Pod's name.
+
+If Pod *default/foo* is created, updated or deleted, then Reconcile will be called for
+*namespace: default, name: foo-parent-1* and for *namespace: default, name: foo-parent-2*.
+
+**Note:** This requires adding the following annotations to your Controller struct to ensure the
+correct RBAC rules are in place and informers have been started.
+
+```go
+// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list
+// +kubebuilder:informers:group=core,version=v1,kind=Pod
+```
+
+{% sample lang="go" %}
+```go
+if err := c.WatchTransformationKeysOf(&corev1.Pod{},
+    func(i interface{}) []types.ReconcileKey {
+        p, ok := i.(*corev1.Pod)
+        if !ok {
+            return []types.ReconcileKey{}
+        }
+
+        // Find multiple parents based off the name
+        n := strings.Split(p.Name, "-")[0]
+        return []types.ReconcileKey{
+            {p.Namespace, n + "-mapto-1"},
+            {p.Namespace, n + "-mapto-2"},
+        }
+    },
+); err != nil {
+    log.Fatalf("%v", err)
+
+}
+```
+{% endmethod %}
+
+
+{% method %}
+## Watching Channels
+
+Controllers may watch channels for events to trigger Reconciles.  This is useful if the Controller
+manages some external state that it is either polled or calls back via a WebHook.
+
+This simple example configures a Controller to read `namespace/name` keys from a channel and
+trigger Reconciles.
+
+If podkeys has *default/foo* inserted, then Reconcile will be called for *namespace: default, name: foo*.
+
+{% sample lang="go" %}
+```go
+podkeys := make(chan string)
+if err := c.WatchChannel(podkeys); err != nil {
+    log.Fatalf("%v", err)
+}
+```
+{% endmethod %}

docs/book/basics/project_creation_and_structure.md

@@ -1,3 +1,7 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
 # Project Creation and Structure {#project-creation-and-structure}
 
 ## Go package Structure
@@ -20,9 +24,8 @@ file.
 For more information on API Group, Version and Kinds, see the *What is a Resource* chapter.
 
 {% panel style="info", title="Generated code" %}
-Kubebuilder generates boilerplate code to add required types and register APIs in this package.
-Boilerplate code is written to `zz_generated.*` files, and should only be written
-by kubebuilder.
+Kubebuilder will generate boilerplate code required for Resources by running
+`kubebuilder generate`.  The generated files are named `zz_generated.*`.
 {% endpanel %}
 
 ##### pkg/controller/...
@@ -45,13 +48,21 @@ In addition to the packages above, a Kubebuilder project has several other direc
 
 ##### hack/...
 
-Kubebuilder puts misc files into the hack directory, such as API installation yaml files
-and samples resource configs.
+Kubebuilder puts miscellaneous files into the hack directory.
+
+- API installation yaml
+- Samples resource configs
+- Headers for generated files: `boilerplate.go.txt`
 
 ##### docs/...
 
 API reference documentation, user defined API samples and API conceptual documentation go here.
 
+{% panel style="success", title="Providing boilerplate headers" %}
+To prepend boilerplate comments at the top of generated and bootstrapped files,
+add the boilerplate to a `hack/boilerplate.go.txt` file before creating a project.
+{% endpanel %}
+
 {% method %}
 ## Create a new project
 

docs/book/basics/running_tests.md

@@ -0,0 +1,36 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
+# Running tests
+
+Kubebuilder `kubebuilder create resource` will create scaffolding tests for controllers and resources
+along side the controller and resource code.  When run, these tests will start a local control plane
+as part of the integration test.  Developers may talk to the local control plane using the provided
+config.
+
+{% method %}
+## Setup Environment Variables
+
+First export the environment variables so the test harness can locate the control plane binaries.
+The control plane binaries are included with kubebuilder.
+
+{% sample lang="shell" %}
+```bash
+export TEST_ASSET_KUBECTL=/usr/local/kubebuilder/bin/kubectl
+export TEST_ASSET_KUBE_APISERVER=/usr/local/kubebuilder/bin/kube-apiserver
+export TEST_ASSET_ETCD=/usr/local/kubebuilder/bin/etcd
+```
+{% endmethod %}
+
+{% method %}
+## Run the tests
+
+Next run the tests as normal.
+
+{% sample lang="shell" %}
+```bash
+go test ./pkg/...
+```
+{% endmethod %}
+

docs/book/basics/simple_controller.md

@@ -1,3 +1,7 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
 # Simple Controller Example
 
 This chapter walks through a simple Controller implementation.
@@ -48,6 +52,14 @@ ProvideController will be called from `pkg/inject/zz_generated.kubebuilder.go` a
 ResourceVersion of the Deployment have not changed.  This is an optimization to filter
 out Deployment events that don't require a reconcile.
 
+#### Reference
+
+- See the [controller libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller) godocs
+for reference documentation on watches.
+- See the [controller code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller)
+godocs for reference documentation on controller annotations.
+
+
 {% sample lang="go" %}
 ```go
 // +kubebuilder:controller:group=workloads,version=v1alpha1,kind=ContainerSet,resource=containersets

docs/book/basics/simple_controller_manager.md

@@ -1,3 +1,7 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
 ## Simple Main {#simple-world-main}
 
 {% method %}

docs/book/basics/simple_resource.md

@@ -1,3 +1,7 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
 # Simple Resource Example
 
 This chapter walks through the definition of a new Resource call *ContainerSet*.  ContainerSet
@@ -25,6 +29,11 @@ ContainerSet has 4 fields:
 - ObjectMeta contains metadata about the specific object instance - such as the name, namespace,
   labels and annotations.  ObjectMeta contains data common to most objects.
 
+#### Reference
+
+- See the [resource code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/apis)
+godocs for reference documentation on resource annotations.
+
 {% sample lang="go" %}
 ```go
 // +genclient

docs/book/basics/what_is_a_controller.md

@@ -1,3 +1,7 @@
+{% panel style="info", title="Under Development" %}
+This book is being actively developed.
+{% endpanel %}
+
 # What is a Controller
 
 Controllers implement APIs defined by *Resources*.  Controllers are