Address PR comments

Author: pwittrock

example/main.go

@@ -21,6 +21,10 @@ import (
 	"flag"
 	"log"
 
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/errors"
+	_ "k8s.io/client-go/plugin/pkg/client/auth/gcp"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 	"sigs.k8s.io/controller-runtime/pkg/client/config"
 	"sigs.k8s.io/controller-runtime/pkg/controller"
@@ -30,10 +34,6 @@ import (
 	logf "sigs.k8s.io/controller-runtime/pkg/runtime/log"
 	"sigs.k8s.io/controller-runtime/pkg/runtime/signals"
 	"sigs.k8s.io/controller-runtime/pkg/source"
-	appsv1 "k8s.io/api/apps/v1"
-	corev1 "k8s.io/api/core/v1"
-	"k8s.io/apimachinery/pkg/api/errors"
-	_ "k8s.io/client-go/plugin/pkg/client/auth/gcp"
 )
 
 func main() {
@@ -46,22 +46,22 @@ func main() {
 		log.Fatal(err)
 	}
 
-	// Setup a new controller to Reconcile ReplicaSets
+	// Setup a new controller to Reconciler ReplicaSets
 	c, err := controller.New("foo-controller", mrg, controller.Options{
-		Reconcile: &reconcileReplicaSet{client: mrg.GetClient()},
+		Reconciler: &reconcileReplicaSet{client: mrg.GetClient()},
 	})
 	if err != nil {
 		log.Fatal(err)
 	}
 
 	// Watch ReplicaSets and enqueue ReplicaSet object key
-	if err := c.Watch(&source.Kind{Type: &appsv1.ReplicaSet{}}, &handler.Enqueue{}); err != nil {
+	if err := c.Watch(&source.Kind{Type: &appsv1.ReplicaSet{}}, &handler.EnqueueRequestForObject{}); err != nil {
 		log.Fatal(err)
 	}
 
 	// Watch Pods and enqueue owning ReplicaSet key
 	if err := c.Watch(&source.Kind{Type: &corev1.Pod{}},
-		&handler.EnqueueOwner{OwnerType: &appsv1.ReplicaSet{}, IsController: true}); err != nil {
+		&handler.EnqueueRequestForOwner{OwnerType: &appsv1.ReplicaSet{}, IsController: true}); err != nil {
 		log.Fatal(err)
 	}
 
@@ -73,8 +73,8 @@ type reconcileReplicaSet struct {
 	client client.Client
 }
 
-// Implement reconcile.Reconcile so the controller can reconcile objects
-var _ reconcile.Reconcile = &reconcileReplicaSet{}
+// Implement reconcile.Reconciler so the controller can reconcile objects
+var _ reconcile.Reconciler = &reconcileReplicaSet{}
 
 func (r *reconcileReplicaSet) Reconcile(request reconcile.Request) (reconcile.Result, error) {
 	// Fetch the ReplicaSet from the cache

pkg/admission/doc.go

@@ -19,7 +19,7 @@ Package admission provides functions to manage webhooks certificates.
 
 There are 3 typical ways to use this library:
 
-* The sync function can be used as a Reconcile function.
+* The sync function can be used as a Reconciler function.
 
 * Invoking it directly fromt eh webhook server at startup.
 

pkg/controller/controller.go

@@ -33,15 +33,17 @@ type Options struct {
 	// MaxConcurrentReconciles is the maximum number of concurrent Reconciles which can be run. Defaults to 1.
 	MaxConcurrentReconciles int
 
-	// Reconcile reconciles an object
-	Reconcile reconcile.Reconcile
+	// Reconciler reconciles an object
+	Reconciler reconcile.Reconciler
 }
 
-// Controller is a work queue that watches for changes to objects (i.e. Create / Update / Delete events) and
-// then reconciles an object (i.e. make changes to ensure the system state matches what is specified in the object).
+// Controller implements a Kubernetes API.  A Controller manages a work queue fed reconcile.Requests
+// from source.Sources.  Work is performed through the reconcile.Reconciler for each enqueued item.
+// Work typically is reads and writes Kubernetes objects to make the system state match the state specified
+// in the object Spec.
 type Controller interface {
-	// Reconcile is called to Reconcile an object by Namespace/Name
-	reconcile.Reconcile
+	// Reconciler is called to Reconciler an object by Namespace/Name
+	reconcile.Reconciler
 
 	// Watch takes events provided by a Source and uses the EventHandler to enqueue reconcile.Requests in
 	// response to the events.
@@ -57,8 +59,8 @@ type Controller interface {
 // New returns a new Controller registered with the Manager.  The Manager will ensure that shared Caches have
 // been synced before the Controller is Started.
 func New(name string, mrg manager.Manager, options Options) (Controller, error) {
-	if options.Reconcile == nil {
-		return nil, fmt.Errorf("must specify Reconcile")
+	if options.Reconciler == nil {
+		return nil, fmt.Errorf("must specify Reconciler")
 	}
 
 	if len(name) == 0 {
@@ -69,14 +71,14 @@ func New(name string, mrg manager.Manager, options Options) (Controller, error)
 		options.MaxConcurrentReconciles = 1
 	}
 
-	// Inject dependencies into Reconcile
-	if err := mrg.SetFields(options.Reconcile); err != nil {
+	// Inject dependencies into Reconciler
+	if err := mrg.SetFields(options.Reconciler); err != nil {
 		return nil, err
 	}
 
 	// Create controller with dependencies set
 	c := &controller.Controller{
-		Do:       options.Reconcile,
+		Do:       options.Reconciler,
 		Cache:    mrg.GetCache(),
 		Config:   mrg.GetConfig(),
 		Scheme:   mrg.GetScheme(),

pkg/controller/controller_integration_test.go

@@ -56,7 +56,7 @@ var _ = Describe("controller", func() {
 
 			By("Creating the Controller")
 			instance, err := controller.New("foo-controller", cm, controller.Options{
-				Reconcile: reconcile.Func(
+				Reconciler: reconcile.Func(
 					func(request reconcile.Request) (reconcile.Result, error) {
 						reconciled <- request
 						return reconcile.Result{}, nil
@@ -65,12 +65,12 @@ var _ = Describe("controller", func() {
 			Expect(err).NotTo(HaveOccurred())
 
 			By("Watching Resources")
-			err = instance.Watch(&source.Kind{Type: &appsv1.ReplicaSet{}}, &handler.EnqueueOwner{
+			err = instance.Watch(&source.Kind{Type: &appsv1.ReplicaSet{}}, &handler.EnqueueRequestForOwner{
 				OwnerType: &appsv1.Deployment{},
 			})
 			Expect(err).NotTo(HaveOccurred())
 
-			err = instance.Watch(&source.Kind{Type: &appsv1.Deployment{}}, &handler.Enqueue{})
+			err = instance.Watch(&source.Kind{Type: &appsv1.Deployment{}}, &handler.EnqueueRequestForObject{})
 			Expect(err).NotTo(HaveOccurred())
 
 			By("Starting the Manager")

pkg/controller/controller_test.go

@@ -46,29 +46,29 @@ var _ = Describe("controller.Controller", func() {
 		It("should return an error if Name is not Specified", func(done Done) {
 			m, err := manager.New(cfg, manager.Options{})
 			Expect(err).NotTo(HaveOccurred())
-			c, err := controller.New("", m, controller.Options{Reconcile: rec})
+			c, err := controller.New("", m, controller.Options{Reconciler: rec})
 			Expect(c).To(BeNil())
 			Expect(err.Error()).To(ContainSubstring("must specify Name for Controller"))
 
 			close(done)
 		})
 
-		It("should return an error if Reconcile is not Specified", func(done Done) {
+		It("should return an error if Reconciler is not Specified", func(done Done) {
 			m, err := manager.New(cfg, manager.Options{})
 			Expect(err).NotTo(HaveOccurred())
 
 			c, err := controller.New("foo", m, controller.Options{})
 			Expect(c).To(BeNil())
-			Expect(err.Error()).To(ContainSubstring("must specify Reconcile"))
+			Expect(err.Error()).To(ContainSubstring("must specify Reconciler"))
 
 			close(done)
 		})
 
-		It("NewController should return an error if injecting Reconcile fails", func(done Done) {
+		It("NewController should return an error if injecting Reconciler fails", func(done Done) {
 			m, err := manager.New(cfg, manager.Options{})
 			Expect(err).NotTo(HaveOccurred())
 
-			c, err := controller.New("foo", m, controller.Options{Reconcile: &failRec{}})
+			c, err := controller.New("foo", m, controller.Options{Reconciler: &failRec{}})
 			Expect(c).To(BeNil())
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(ContainSubstring("expected error"))
@@ -78,7 +78,7 @@ var _ = Describe("controller.Controller", func() {
 	})
 })
 
-var _ reconcile.Reconcile = &failRec{}
+var _ reconcile.Reconciler = &failRec{}
 var _ inject.Client = &failRec{}
 
 type failRec struct{}

pkg/controller/controllerutil/controllerutil.go

@@ -27,7 +27,7 @@ import (
 
 // SetControllerReference sets owner as a Controller OwnerReference on owned.
 // This is used for garbage collection of the owned object and for
-// reconciling the owner object on changes to owned (with a Watch + EnqueueOwner).
+// reconciling the owner object on changes to owned (with a Watch + EnqueueRequestForOwner).
 func SetControllerReference(owner, object v1.Object, scheme *runtime.Scheme) error {
 	ro, ok := owner.(runtime.Object)
 	if !ok {

pkg/controller/doc.go

@@ -15,12 +15,11 @@ limitations under the License.
 */
 
 /*
-Package controller provides types and functions for building Controllers.
+Package controller provides types and functions for building Controllers.  Controllers implement Kubernetes APIs.
 
 Creation
 
-To create a new Controller, first create a manager.Manager and provide it to New.  The Manager will
-take care of Starting / Stopping the Controller, as well as provide shared Caches and Clients to the
-Sources, EventHandlers, Predicates, and Reconcile.
+To create a new Controller, first create a manager.Manager and pass it to the controller.New function.
+The Controller MUST be started by calling Manager.Start.
 */
 package controller

pkg/controller/example_test.go

@@ -34,7 +34,7 @@ var mrg manager.Manager
 // manager.Manager will be used to Start the Controller, and will provide it a shared Cache and Client.
 func ExampleNew() {
 	_, err := controller.New("pod-controller", mrg, controller.Options{
-		Reconcile: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
+		Reconciler: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
 			// Your business logic to implement the API by creating, updating, deleting objects goes here.
 			return reconcile.Result{}, nil
 		}),
@@ -48,7 +48,7 @@ func ExampleNew() {
 // it with the DefaultControllerManager.
 func ExampleController() {
 	_, err := controller.New("pod-controller", mrg, controller.Options{
-		Reconcile: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
+		Reconciler: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
 			// Your business logic to implement the API by creating, updating, deleting objects goes here.
 			return reconcile.Result{}, nil
 		}),
@@ -62,7 +62,7 @@ func ExampleController() {
 // This example watches Pods and enqueues reconcile.Requests with the changed Pod Name and Namespace.
 func ExampleController_Watch() {
 	c, err := controller.New("pod-controller", mrg, controller.Options{
-		Reconcile: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
+		Reconciler: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
 			// Your business logic to implement the API by creating, updating, deleting objects goes here.
 			return reconcile.Result{}, nil
 		}),
@@ -71,7 +71,7 @@ func ExampleController_Watch() {
 		log.Fatal(err)
 	}
 
-	err = c.Watch(&source.Kind{Type: &v1.Pod{}}, &handler.Enqueue{})
+	err = c.Watch(&source.Kind{Type: &v1.Pod{}}, &handler.EnqueueRequestForObject{})
 	if err != nil {
 		log.Fatal(err)
 	}