Emit events for all TaskRun lifecycle events

Emit events for additional TaskRun lifecyle events:
- taskrun started
- taskrun timeout

Fix broken EmitEvents unit tests and extend them to cover
new functionality.

Introduce pre-run and post-run functions that are invoked
asynchronously when the taskrun starts and completes, to emit
events.

These same functions shall be used to trigger any other async
behaviour on start/stop of taskruns.

Add documentation on events.

Fixes tektoncd#2328
Work towards tektoncd#2082

docs/events.md

@@ -0,0 +1,39 @@
+<!--
+---
+linkTitle: "Events"
+weight: 2
+---
+-->
+# Events
+
+Tekton runtime resources, specifically `TaskRuns` and `PipelineRuns`,
+emit events when they are executed, so that users can monitor their lifecycle
+and react to it. Tekton emits [kubernetes events](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#event-v1-core), that can be retrieve from the resource via
+`kubectl describe [resource]`.
+
+No events are emitted for `Conditions` today (https://github.com/tektoncd/pipeline/issues/2461).
+
+## TaskRuns
+
+`TaskRun` events are generated for the following `Reasons`:
+- `Started`: this is triggered the first time the `TaskRun` is picked by the
+  reconciler from its work queue, so it only happens if web-hook validation was
+  successful. Note that this event does not imply that a step started executing,
+  as several conditions must be met first:
+  - task and bound resource validation must be successful
+  - attached conditions must run successfully
+  - the `Pod` associated to the `TaskRun` must be successfully scheduled
+- `Succeeded`: this is triggered once all steps in the `TaskRun` are executed
+  successfully, including post-steps injected by Tekton.
+- `Failed`: this is triggered if the `TaskRun` is completed, but not successfully.
+  Causes of failure may be: one the steps failed, the `TaskRun` was cancelled or
+  the `TaskRun` timed out.
+
+## PipelineRuns
+
+`PipelineRun` events are generated for the following `Reasons`:
+- `Succeeded`: this is triggered once all `Tasks` reachable via the DAG are
+  executed successfully.
+- `Failed`: this is triggered if the `PipelineRun` is completed, but not
+  successfully. Causes of failure may be: one the `Tasks` failed or the
+  `PipelineRun` was cancelled.

docs/pipelineruns.md

@@ -18,6 +18,8 @@ weight: 4
   - [Specifying `LimitRange` values](#specifying-limitrange-values)
   - [Configuring a failure timeout](#configuring-a-failure-timeout)
 - [Cancelling a `PipelineRun`](#cancelling-a-pipelinerun)
+- [Events](events.md#pipelineruns)
+
 
 
 ## Overview

docs/taskruns.md

@@ -22,6 +22,7 @@ weight: 2
   - [Monitoring `Steps`](#monitoring-steps)
   - [Monitoring `Results`](#monitoring-results)
 - [Cancelling a `TaskRun`](#cancelling-a-taskrun)
+- [Events](events.md#taskruns)
 - [Code examples](#code-examples)
   - [Example `TaskRun` with a referenced `Task`](#example-taskrun-with-a-referenced-task)
   - [Example `TaskRun` with an embedded `Task`](#example-taskrun-with-an-embedded-task)

pkg/reconciler/event.go

@@ -17,6 +17,7 @@ package reconciler
 
 import (
 	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/equality"
 	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/client-go/tools/record"
 	"knative.dev/pkg/apis"
@@ -27,20 +28,25 @@ const (
 	EventReasonSucceded = "Succeeded"
 	// EventReasonFailed is the reason set for events about unsuccessful completion of TaskRuns / PipelineRuns
 	EventReasonFailed = "Failed"
+	// EventReasonStarted is the reason set for events about the start of TaskRuns / PipelineRuns
+	EventReasonStarted = "Started"
 )
 
-// EmitEvent emits success or failed event for object
-// if afterCondition is different from beforeCondition
+// EmitEvent emits an event for object if afterCondition is different from beforeCondition
 func EmitEvent(c record.EventRecorder, beforeCondition *apis.Condition, afterCondition *apis.Condition, object runtime.Object) {
-	if beforeCondition != afterCondition && afterCondition != nil {
-		// Create events when the obj result is in.
+	if !equality.Semantic.DeepEqual(beforeCondition, afterCondition) && afterCondition != nil {
+		// If the condition changed, and the target condition is not empty, we send an event
 		switch afterCondition.Status {
 		case corev1.ConditionTrue:
 			c.Event(object, corev1.EventTypeNormal, EventReasonSucceded, afterCondition.Message)
-		case corev1.ConditionUnknown:
-			c.Event(object, corev1.EventTypeNormal, afterCondition.Reason, afterCondition.Message)
 		case corev1.ConditionFalse:
 			c.Event(object, corev1.EventTypeWarning, EventReasonFailed, afterCondition.Message)
+		case corev1.ConditionUnknown:
+			if beforeCondition == nil {
+				// If the condition changed, the status is "unknown", and there was no condition before,
+				// we emit the "Started event". We ignore further updates of the "uknown" status.
+				c.Event(object, corev1.EventTypeNormal, EventReasonStarted, "")
+			}
 		}
 	}
 }

pkg/reconciler/event_test.go

@@ -27,21 +27,24 @@ import (
 
 func TestEmitEvent(t *testing.T) {
 	testcases := []struct {
-		name        string
-		before      *apis.Condition
-		after       *apis.Condition
-		expectEvent bool
+		name          string
+		before        *apis.Condition
+		after         *apis.Condition
+		expectEvent   bool
+		expectedEvent string
 	}{{
-		name: "unknown to true",
+		name: "unknown to true with message",
 		before: &apis.Condition{
 			Type:   apis.ConditionSucceeded,
 			Status: corev1.ConditionUnknown,
 		},
 		after: &apis.Condition{
-			Type:   apis.ConditionSucceeded,
-			Status: corev1.ConditionTrue,
+			Type:    apis.ConditionSucceeded,
+			Status:  corev1.ConditionTrue,
+			Message: "all done",
 		},
-		expectEvent: true,
+		expectEvent:   true,
+		expectedEvent: "Normal Succeeded all done",
 	}, {
 		name: "true to true",
 		before: &apis.Condition{
@@ -52,7 +55,8 @@ func TestEmitEvent(t *testing.T) {
 			Type:   apis.ConditionSucceeded,
 			Status: corev1.ConditionTrue,
 		},
-		expectEvent: false,
+		expectEvent:   false,
+		expectedEvent: "",
 	}, {
 		name: "false to false",
 		before: &apis.Condition{
@@ -63,23 +67,72 @@ func TestEmitEvent(t *testing.T) {
 			Type:   apis.ConditionSucceeded,
 			Status: corev1.ConditionFalse,
 		},
-		expectEvent: false,
+		expectEvent:   false,
+		expectedEvent: "",
+	}, {
+		name: "unknown to unknown",
+		before: &apis.Condition{
+			Type:   apis.ConditionSucceeded,
+			Status: corev1.ConditionUnknown,
+			Reason: "foo",
+		},
+		after: &apis.Condition{
+			Type:   apis.ConditionSucceeded,
+			Status: corev1.ConditionUnknown,
+			Reason: "bar",
+		},
+		expectEvent:   false,
+		expectedEvent: "",
 	}, {
 		name:  "true to nil",
 		after: nil,
 		before: &apis.Condition{
 			Type:   apis.ConditionSucceeded,
 			Status: corev1.ConditionTrue,
 		},
-		expectEvent: true,
+		expectEvent:   false,
+		expectedEvent: "",
 	}, {
 		name:   "nil to true",
 		before: nil,
 		after: &apis.Condition{
 			Type:   apis.ConditionSucceeded,
 			Status: corev1.ConditionTrue,
 		},
-		expectEvent: true,
+		expectEvent:   true,
+		expectedEvent: "Normal Succeeded ",
+	}, {
+		name:   "nil to unknown with message",
+		before: nil,
+		after: &apis.Condition{
+			Type:    apis.ConditionSucceeded,
+			Status:  corev1.ConditionUnknown,
+			Message: "just starting",
+		},
+		expectEvent:   true,
+		expectedEvent: "Normal Started ",
+	}, {
+		name: "unknown to false with message",
+		before: &apis.Condition{
+			Type:   apis.ConditionSucceeded,
+			Status: corev1.ConditionUnknown,
+		},
+		after: &apis.Condition{
+			Type:    apis.ConditionSucceeded,
+			Status:  corev1.ConditionFalse,
+			Message: "really bad",
+		},
+		expectEvent:   true,
+		expectedEvent: "Warning Failed really bad",
+	}, {
+		name:   "nil to false",
+		before: nil,
+		after: &apis.Condition{
+			Type:   apis.ConditionSucceeded,
+			Status: corev1.ConditionFalse,
+		},
+		expectEvent:   true,
+		expectedEvent: "Warning Failed ",
 	}}
 
 	for _, ts := range testcases {
@@ -90,12 +143,21 @@ func TestEmitEvent(t *testing.T) {
 
 		select {
 		case event := <-fr.Events:
-			if ts.expectEvent && event == "" {
-				t.Errorf("Expected event but got empty for %s", ts.name)
+			if event == "" {
+				// The fake recorder reported empty, it should not happen
+				t.Fatalf("Expected event but got empty for %s", ts.name)
 			}
-		case <-timer.C:
 			if !ts.expectEvent {
-				t.Errorf("Unexpected event but got for %s", ts.name)
+				// The fake recorder reported an event which we did not expect
+				t.Errorf("Unxpected event \"%s\" but got one for %s", event, ts.name)
+			}
+			if !(event == ts.expectedEvent) {
+				t.Errorf("Expected event \"%s\" but got \"%s\" instead for %s", ts.expectedEvent, event, ts.name)
+			}
+		case <-timer.C:
+			if ts.expectEvent {
+				// The fake recorder did not report, the timer imeout expired
+				t.Errorf("Expected event but got none for %s", ts.name)
 			}
 		}
 	}

pkg/reconciler/taskrun/controller.go

@@ -44,6 +44,7 @@ const (
 	resyncPeriod = 10 * time.Hour
 )
 
+// NewController instantiates a new controller.Impl from knative.dev/pkg/controller
 func NewController(images pipeline.Images) func(context.Context, configmap.Watcher) *controller.Impl {
 	return func(ctx context.Context, cmw configmap.Watcher) *controller.Impl {
 		logger := logging.FromContext(ctx)

pkg/reconciler/taskrun/resources/cloudevent/cloud_event_controller.go

@@ -66,8 +66,7 @@ func cloudEventDeliveryFromTargets(targets []string) []v1alpha1.CloudEventDelive
 }
 
 // SendCloudEvents is used by the TaskRun controller to send cloud events once
-// the TaskRun is complete. `tr` is used to obtain the list of targets but also
-// to construct the body of the
+// the TaskRun is complete. `tr` is used to obtain the list of targets
 func SendCloudEvents(tr *v1alpha1.TaskRun, ceclient CEClient, logger *zap.SugaredLogger) error {
 	logger = logger.With(zap.String("taskrun", tr.Name))