Better documentation on watching things

Author: pwittrock

README.md

@@ -102,6 +102,10 @@ Subpackages of apis are created when running the following command to create a n
 kubebuilder create resource --group mygroup --version v1beta1 --kind MyKind
 ```
 
+**Note:** While `create resource` automatically runs the code generators for the user, when
+the user changes the resource file or adds `// +kubebuilder` annotations to the controller,
+they will need to run `kubebuilder generate` to rerun the code generators.
+
 ### pkg/controllers
 
 **Users must edit packages under this package**
@@ -119,6 +123,10 @@ kubebuilder create resource --group mygroup --version v1beta1 --kind MyKind
 See documentation and examples of annotations in godoc format here:
 - [gen/controller](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package)
 
+**Note:** While `create resource` automatically runs the code generators for the user, when
+the user changes the resource file or adds `// +kubebuilder` annotations to the controller,
+they will need to run `kubebuilder generate` to rerun the code generators.
+
 ### pkg/inject
 
 *Most users do not need to edit this package.*
@@ -201,20 +209,26 @@ this example:
 
 [GenericController](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller#example-GenericController)
 
-Use the following annotation to start additional informers for any resources you are watching in your controller.
 
-```go
-// +informers:group=apps,version=v1,kind=Deployment
-```
+To Watch additional resources from your controller do the following in your controller.go:
 
-Use the following annotation to generate RBAC rules to allow your controller to read and write resources when
-running in a container in a Kubernetes cluster.
+1. Add a `gc.Watch*` call to the `ProvideController`.  e.g. Call gc.[WatchTransformationKeyOf](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller#example-GenericController-WatchTransformationKeyOf)
+  - This will trigger Reconcile calls for events
+2. Add an [// +informers:](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package) annotation
+   to the `type <Kind>Controller struct` with the type of the resource you are watching
+  - This will make sure the informers that watch for events are started
+3. Add an [// +rbac:](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package)
+  annotation to the `type <Kind>Controller struct` with the type of the resource you are watching
+  - This will make sure the RBAC rules that allow the controller to watch events in a cluster are generated
+
+Example:
 
 ```go
-// +rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list
+// +kubebuilder:informers:group=core,version=v1,kind=Pod
+type FooController struct{}
 ```
 
-
 ### Watching resources
 
 Controllers watch resources to trigger reconcile functions.  It is common for controllers to reconcile a single resource

cmd/kubebuilder/create/resource/controller.go

@@ -90,8 +90,18 @@ func ProvideController(arguments args.InjectArgs) (*controller.GenericController
         return gc, err
     }
 
-    // INSERT ADDITIONAL WATCHES HERE BY CALLING gc.Watch.*() FUNCTIONS
-    // NOTE: Informers for Kubernetes resources *MUST* be registered in the pkg/inject package so that they are started.
+	// IMPORTANT:
+	// To watch additional resource types - such as those created by your controller - add gc.Watch* function calls here
+	// Watch function calls will transform each object event into a {{.Kind}} Key to be reconciled by the controller.
+	//
+	// **********
+	// For any new Watched types, you MUST add the appropriate // +kubebuilder:informer and // +kubebuilder:rbac
+	// annotations to the {{.Kind}}Controller and run "kubebuilder generate.
+	// This will generate the code to start the informers and create the RBAC rules needed for running in a cluster.
+	// See:
+	// https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller#example-package
+	// **********
+
     return gc, nil
 }
 `

cmd/kubebuilder/create/resource/resource.go

@@ -62,11 +62,13 @@ import (
 // {{.Kind}}Spec defines the desired state of {{.Kind}}
 type {{.Kind}}Spec struct {
     // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
+	// Important: Run "kubebuilder generate" to regenerate code after modifying this file
 }
 
 // {{.Kind}}Status defines the observed state of {{.Kind}}
 type {{.Kind}}Status struct {
     // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
+	// Important: Run "kubebuilder generate" to regenerate code after modifying this file
 }
 
 // +genclient