Merge pull request #5 from pwittrock/master

Support Predicates

Author: Phillip Wittrock

example/main.go

@@ -78,7 +78,7 @@ type reconcileReplicaSet struct {
 	client client.Interface
 }
 
-// Implement reconcile.reconcile so the controller can reconcile objects
+// Implement reconcile.Reconcile so the controller can reconcile objects
 var _ reconcile.Reconcile = &reconcileReplicaSet{}
 
 func (r *reconcileReplicaSet) Reconcile(request reconcile.Request) (reconcile.Result, error) {

pkg/controller/controller.go

@@ -51,7 +51,7 @@ type Args struct {
 // 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).
 type Controller interface {
-	// Watch takes events provided by a Source and uses the EventHandler to enqueue ReconcileRequests in
+	// Watch takes events provided by a Source and uses the EventHandler to enqueue reconcile.Requests in
 	// response to the events.
 	//
 	// Watch may be provided one or more Predicates to filter events before they are given to the EventHandler.
@@ -125,7 +125,7 @@ func (c *controller) Watch(src source.Source, evthdler eventhandler.EventHandler
 	// TODO(pwittrock): wire in predicates
 
 	log.Info("Starting EventSource", "controller", c.name, "Source", src)
-	return src.Start(evthdler, c.queue)
+	return src.Start(evthdler, c.queue, prct...)
 }
 
 func (c *controller) Start(stop <-chan struct{}) error {
@@ -179,7 +179,8 @@ func (c *controller) processNextWorkItem() bool {
 	}
 
 	if shutdown {
-		// Return false, take a break before starting again.  But Y tho?
+		// Return false, this will cause the controller to back off for a second before trying again.
+		// TODO(community): This was copied from the sample-controller.  Figure out why / if we need this.
 		return false
 	}
 
@@ -209,13 +210,11 @@ func (c *controller) processNextWorkItem() bool {
 		c.queue.AddRateLimited(req)
 		log.Error(nil, "reconcile error", "controller", c.name, "Request", req)
 
-		// TODO(pwittrock): FTO Returning an error here seems to back things off for a second before restarting
-		// the loop through wait.Util.
-		// Return false, take a break. But y tho?
+		// Return false, this will cause the controller to back off for a second before trying again.
+		// TODO(community): This was copied from the sample-controller.  Figure out why / if we need this.
 		return false
 	} else if result.Requeue {
 		c.queue.AddRateLimited(req)
-		// Return true, don't take a break
 		return true
 	}
 

pkg/controller/doc.go

@@ -21,18 +21,18 @@ and are central to building Operators, Workload APIs, Configuration APIs, Autosc
 Controllers
 
 Controllers are work queues that enqueue work in response to source.Source events (e.g. Pod Create, Update, Delete)
-and trigger reconcile.reconcile functions when the work is dequeued.
+and trigger reconcile.Reconcile functions when the work is dequeued.
 
 Unlike http handlers, Controllers DO NOT perform work directly in response to events, but instead enqueue
-ReconcileRequests so the work is performed eventually.
+reconcile.Requests so the work is performed eventually.
 
-* Controllers run reconcile.reconcile functions against objects (provided as name / Namespace).
+* Controllers run reconcile.Reconcile functions against objects (provided as name / Namespace).
 
-* Controllers enqueue reconcile.ReconcileRequests in response events provided by source.Sources.
+* Controllers enqueue reconcile.Requests in response events provided by source.Sources.
 
 reconcile
 
-reconcile.reconcile is a function that may be called at anytime with the name / Namespace of an
+reconcile.Reconcile is a function that may be called at anytime with the name / Namespace of an
 object.  When called, it will ensure that the state of the system matches what is specified in the object at the
 time reconcile is called.
 
@@ -42,9 +42,9 @@ ReplicationController.
 
 * reconcile works on a single object type. - e.g. it will only reconcile ReplicaSets.
 
-* reconcile is triggered by a ReconcileRequest containing the name / Namespace of an object to reconcile.
+* reconcile is triggered by a reconcile.Request containing the name / Namespace of an object to reconcile.
 
-* reconcile does not care about the event contents or event type triggering the ReconcileRequest.
+* reconcile does not care about the event contents or event type triggering the reconcile.Request.
 - e.g. it doesn't matter whether a ReplicaSet was created or updated, reconcile will check that the correct
 Pods exist either way.
 
@@ -70,16 +70,16 @@ from another source (e.g. WebHook callback).
 
 EventHandler
 
-eventhandler.EventHandler transforms and enqueues events from a source.Source into reconcile.ReconcileRequests.
+eventhandler.EventHandler transforms and enqueues events from a source.Source into reconcile.Requests.
 
 Example: a Pod Create event from a Source is provided to the eventhandler.EnqueueHandler, which enqueues a
-ReconcileRequest containing the name / Namespace of the Pod.
+reconcile.Request containing the name / Namespace of the Pod.
 
-* EventHandler takes an event.Event and enqueues ReconcileRequests
+* EventHandler takes an event.Event and enqueues reconcile.Requests
 
-* EventHandlers MAY map an event for an object of one type to a ReconcileRequest for an object of another type.
+* EventHandlers MAY map an event for an object of one type to a reconcile.Request for an object of another type.
 
-* EventHandlers MAY map an event for an object to multiple ReconcileRequests for different objects.
+* EventHandlers MAY map an event for an object to multiple reconcile.Requests for different objects.
 
 * Users SHOULD use the provided EventHandler implementations instead of implementing their own for almost all cases.
 
@@ -100,13 +100,13 @@ Source provides event:
 
 * &source.KindSource{"core", "v1", "Pod"} -> (Pod foo/bar Create Event)
 
-EventHandler enqueues ReconcileRequest:
+EventHandler enqueues Request:
 
-* &eventhandler.Enqueue{} -> (ReconcileRequest{"foo", "bar"})
+* &eventhandler.Enqueue{} -> (reconcile.Request{"foo", "bar"})
 
-Reconcile is called with the ReconcileRequest:
+Reconcile is called with the Request:
 
-* Reconcile(ReconcileRequest{"foo", "bar"})
+* Reconcile(Request{"foo", "bar"})
 
 
 controllerManager
@@ -162,22 +162,22 @@ to Pod or ReplicaSet events.  The Reconcile function simply adds a label to the
 		client client.Interface
 	}
 
-	// Implement reconcile.reconcile so the controller can reconcile objects
+	// Implement reconcile.Reconcile so the controller can reconcile objects
 	var _ reconcile.Reconcile = &ReconcileReplicaSet{}
 
 	// Reconcile writes a "hello": "world" annotation to ReplicaSets that don't have one.
-	func (r *ReconcileReplicaSet) Reconcile(request reconcile.ReconcileRequest) (reconcile.ReconcileResult, error) {
+	func (r *ReconcileReplicaSet) Reconcile(request reconcile.Request) (reconcile.Result, error) {
 		// Fetch the ReplicaSet from the cache
 		rs := &appsv1.ReplicaSet{}
 		err := r.client.Get(context.TODO(), request.NamespacedName, rs)
 		if errors.IsNotFound(err) {
 			log.Printf("Could not find ReplicaSet %v.\n", request)
-			return reconcile.ReconcileResult{}, nil
+			return reconcile.Result{}, nil
 		}
 
 		if err != nil {
 			log.Printf("Could not fetch ReplicaSet %v for %+v\n", err, request)
-			return reconcile.ReconcileResult{}, err
+			return reconcile.Result{}, err
 		}
 
 		// Print the ReplicaSet
@@ -189,18 +189,18 @@ to Pod or ReplicaSet events.  The Reconcile function simply adds a label to the
 			rs.Labels = map[string]string{}
 		}
 		if rs.Labels["hello"] == "world" {
-			return reconcile.ReconcileResult{}, nil
+			return reconcile.Result{}, nil
 		}
 
 		// Update the ReplicaSet
 		rs.Labels["hello"] = "world"
 		err = r.client.Update(context.TODO(), rs)
 		if err != nil {
 			log.Printf("Could not write ReplicaSet %v\n", err)
-			return reconcile.ReconcileResult{}, err
+			return reconcile.Result{}, err
 		}
 
-		return reconcile.ReconcileResult{}, nil
+		return reconcile.Result{}, nil
 	}
 
 Controller Example
@@ -233,13 +233,13 @@ For example, a Deployment controller might use an EnqueueHandler and EnqueueOwne
 
 * Watch for ReplicaSet Events - enqueue the key of the Deployment that created the ReplicaSet (e.g the Owner)
 
-Note: ReconcileRequests are deduplicated when they are enqueued.  Many Pod Events for the same ReplicaSet
+Note: reconcile.Requests are deduplicated when they are enqueued.  Many Pod Events for the same ReplicaSet
 may trigger only 1 reconcile invocation as each Event results in the Handler trying to enqueue
-the same ReconcileRequest for the ReplicaSet.
+the same reconcile.Request for the ReplicaSet.
 
-controller Writing Tips
+Controller Writing Tips
 
-reconcile Runtime Complexity:
+Reconcile Runtime Complexity:
 
 * It is better to write Controllers to perform an O(1) reconcile N times (e.g. on N different objects) instead of
 performing an O(N) reconcile 1 time (e.g. on a single object which manages N other objects).
@@ -250,7 +250,7 @@ Services from a single reconcile.
 
 Event Multiplexing:
 
-* ReconcileRequests for the same name / Namespace are deduplicated when they are enqueued.  This allows
+* reconcile.Requests for the same name / Namespace are deduplicated when they are enqueued.  This allows
 for Controllers to gracefully handle event storms for a single object.  Multiplexing multiple event Sources to
 a single object type takes advantage of this.
 

pkg/controller/eventhandler/doc.go

@@ -15,16 +15,16 @@ limitations under the License.
 */
 
 /*
-Package eventhandler defines EventHandlers that enqueue ReconcileRequests in response to Create, Update, Deletion Events
+Package eventhandler defines EventHandlers that enqueue reconcile.Requests in response to Create, Update, Deletion Events
 observed from Watching Kubernetes APIs.
 
 EventHandlers
 
-EnqueueHandler - Enqueues a ReconcileRequest containing the Name and Namespace of the object in the Event.
+EnqueueHandler - Enqueues a reconcile.equest containing the Name and Namespace of the object in the Event.
 
-EnqueueOwnerHandler - Enqueues a ReconcileRequest containing the Name and Namespace of the Owner of the object in the Event.
+EnqueueOwnerHandler - Enqueues a reconcile.Request containing the Name and Namespace of the Owner of the object in the Event.
 
-EnqueueMappedHander - Enqueues ReconcileRequests resulting from a user provided transformation function run against the
+EnqueueMappedHander - Enqueues Rreconcile.Requests resulting from a user provided transformation function run against the
 object in the Event.
 */
 package eventhandler

pkg/controller/eventhandler/enqueue_mapped.go

@@ -26,10 +26,10 @@ import (
 
 var _ EventHandler = &EnqueueMappedHandler{}
 
-// EnqueueMappedHandler enqueues ReconcileRequests by running a transformation function on each Event.
+// EnqueueMappedHandler enqueues Requests by running a transformation function on each Event.
 //
 // For UpdateEvents which contain both a new and old object, the transformation function is run on both
-// objects and both sets of ReconcileRequests are enqueue.
+// objects and both sets of Requests are enqueue.
 type EnqueueMappedHandler struct {
 	// Mapper transforms the argument into a slice of keys to be reconciled
 	ToRequests Mapper

pkg/controller/eventhandler/enqueue_owner.go

@@ -34,7 +34,7 @@ var _ EventHandler = &EnqueueOwnerHandler{}
 
 var log = logf.KBLog.WithName("eventhandler").WithName("EnqueueOwnerHandler")
 
-// EnqueueOwnerHandler enqueues ReconcileRequests for the Owners of an object.  E.g. an object that created
+// EnqueueOwnerHandler enqueues Requests for the Owners of an object.  E.g. an object that created
 // another object.
 //
 // If a ReplicaSet creates Pods, reconcile the ReplicaSet in response to events on Pods that it created using:

pkg/controller/eventhandler/eventhandler.go

@@ -21,11 +21,11 @@ import (
 	"k8s.io/client-go/util/workqueue"
 )
 
-// EventHandler enqueues ReconcileRequests in response to events (e.g. Pod Create).  EventHandlers map an Event
+// EventHandler enqueues reconcile.Requests in response to events (e.g. Pod Create).  EventHandlers map an Event
 // for one object to trigger Reconciles for either the same object or different objects - e.g. if there is an
 // Event for object with type Foo (using source.KindSource) then reconcile one or more object(s) with type Bar.
 //
-// Identical ReconcileRequests will be batched together through the queuing mechanism before reconcile is called.
+// Identical reconcile.Requests will be batched together through the queuing mechanism before reconcile is called.
 //
 // * Use EnqueueHandler to reconcile the object the event is for
 // - do this for events for the type the Controller Reconciles. (e.g. Deployment for a Deployment Controller)
@@ -59,19 +59,19 @@ var _ EventHandler = Funcs{}
 // Funcs allows specifying a subset of EventHandler functions are fields.
 type Funcs struct {
 	// Create is called in response to an add event.  Defaults to no-op.
-	// RateLimitingInterface is used to enqueue reconcile.ReconcileRequests.
+	// RateLimitingInterface is used to enqueue reconcile.Requests.
 	CreateFunc func(workqueue.RateLimitingInterface, event.CreateEvent)
 
 	// Update is called in response to an update event.  Defaults to no-op.
-	// RateLimitingInterface is used to enqueue reconcile.ReconcileRequests.
+	// RateLimitingInterface is used to enqueue reconcile.Requests.
 	UpdateFunc func(workqueue.RateLimitingInterface, event.UpdateEvent)
 
 	// Delete is called in response to a delete event.  Defaults to no-op.
-	// RateLimitingInterface is used to enqueue reconcile.ReconcileRequests.
+	// RateLimitingInterface is used to enqueue reconcile.Requests.
 	DeleteFunc func(workqueue.RateLimitingInterface, event.DeleteEvent)
 
 	// GenericFunc is called in response to a generic event.  Defaults to no-op.
-	// RateLimitingInterface is used to enqueue reconcile.ReconcileRequests.
+	// RateLimitingInterface is used to enqueue reconcile.Requests.
 	GenericFunc func(workqueue.RateLimitingInterface, event.GenericEvent)
 }
 

pkg/controller/eventhandler/eventhandler_test.go

@@ -524,7 +524,7 @@ var _ = Describe("Eventhandler", func() {
 		})
 
 		Context("with the Controller field set to true", func() {
-			It("should enqueue ReconcileRequests for only the first the Controller if there are "+
+			It("should enqueue reconcile.Requests for only the first the Controller if there are "+
 				"multiple Controller owners.", func() {
 				instance := eventhandler.EnqueueOwnerHandler{
 					OwnerType:    &appsv1.ReplicaSet{},
@@ -571,7 +571,7 @@ var _ = Describe("Eventhandler", func() {
 					NamespacedName: types.NamespacedName{Namespace: pod.GetNamespace(), Name: "foo2-parent"}}))
 			})
 
-			It("should not enqueue ReconcileRequests if there are no Controller owners.", func() {
+			It("should not enqueue reconcile.Requests if there are no Controller owners.", func() {
 				instance := eventhandler.EnqueueOwnerHandler{
 					OwnerType:    &appsv1.ReplicaSet{},
 					IsController: t,
@@ -602,7 +602,7 @@ var _ = Describe("Eventhandler", func() {
 				Expect(q.Len()).To(Equal(0))
 			})
 
-			It("should not enqueue ReconcileRequests if there are no owners.", func() {
+			It("should not enqueue reconcile.Requests if there are no owners.", func() {
 				instance := eventhandler.EnqueueOwnerHandler{
 					OwnerType:    &appsv1.ReplicaSet{},
 					IsController: t,
@@ -618,7 +618,7 @@ var _ = Describe("Eventhandler", func() {
 		})
 
 		Context("with the Controller field set to false", func() {
-			It("should enqueue a ReconcileRequests for all owners.", func() {
+			It("should enqueue a reconcile.Requests for all owners.", func() {
 				instance := eventhandler.EnqueueOwnerHandler{
 					OwnerType: &appsv1.ReplicaSet{},
 				}

pkg/controller/eventhandler/example_test.go

@@ -30,7 +30,7 @@ import (
 
 var c controller.Controller
 
-// This example watches Pods and enqueues ReconcileRequests with the Name and Namespace of the Pod from
+// This example watches Pods and enqueues Requests with the Name and Namespace of the Pod from
 // the Event (i.e. change caused by a Create, Update, Delete).
 func ExampleEnqueueHandler() {
 	// controller is a controller.controller

pkg/controller/example_test.go

@@ -46,7 +46,7 @@ func ExampleController() {
 	}
 }
 
-// This example watches Pods and enqueues ReconcileRequests with the changed Pod Name and Namespace.
+// This example watches Pods and enqueues reconcile.Requests with the changed Pod Name and Namespace.
 func ExampleController_Watch() {
 	cm, err := controller.NewManager(controller.ManagerArgs{Config: config.GetConfigOrDie()})
 	if err != nil {

pkg/controller/reconcile/reconcile.go

@@ -20,7 +20,7 @@ import (
 	"k8s.io/apimachinery/pkg/types"
 )
 
-// Result contains the result of a reconcile.
+// Result contains the result of a Reconcile invocation.
 type Result struct {
 	// Requeue tells the Controller to requeue the reconcile key.  Defaults to false.
 	Requeue bool

pkg/controller/source/example_test.go

@@ -26,7 +26,7 @@ import (
 
 var ctrl controller.Controller
 
-// This example Watches for Pod Events (e.g. Create / Update / Delete) and enqueues a ReconcileRequest
+// This example Watches for Pod Events (e.g. Create / Update / Delete) and enqueues a reconcile.Request
 // with the Name and Namespace of the Pod.
 func ExampleKindSource() {
 	ctrl.Watch(
@@ -35,7 +35,7 @@ func ExampleKindSource() {
 	)
 }
 
-// This example reads GenericEvents from a channel and enqueues a ReconcileRequest containing the Name and Namespace
+// This example reads GenericEvents from a channel and enqueues a reconcile.Request containing the Name and Namespace
 // provided by the event.
 func ExampleChannelSource() {
 	events := make(chan event.GenericEvent)