Added docs for failure details

shipwright-io · Nov 2, 2021 · 07f0af5 · 07f0af5
1 parent b2a1219
commit 07f0af5
Show file tree

Hide file tree

Showing 7 changed files with 30 additions and 11 deletions.
diff --git a/cmd/git/main.go b/cmd/git/main.go
@@ -44,14 +44,14 @@ func (e ExitError) Error() string {
 
 type settings struct {
 	help                   bool
-	skipValidation         bool
-	depth                  uint
 	url                    string
 	revision               string
+	depth                  uint
 	target                 string
 	resultFileCommitSha    string
 	resultFileCommitAuthor string
 	secretPath             string
+	skipValidation         bool
 }
 
 var flagValues settings
@@ -100,7 +100,6 @@ func main() {
 // Execute performs flag parsing, input validation and the Git clone
 func Execute(ctx context.Context) error {
 	flagValues = settings{depth: 1}
-
 	pflag.Parse()
 
 	if flagValues.help {

diff --git a/deploy/crds/shipwright.io_buildruns.yaml b/deploy/crds/shipwright.io_buildruns.yaml
@@ -459,7 +459,7 @@ spec:
                   type: object
                 type: array
               failedAt:
-                description: FailedAt points to the resource where the BuildRun failed
+                description: 'Deprecated: FailedAt points to the resource where the BuildRun failed'
                 properties:
                   container:
                     type: string

diff --git a/docs/buildrun.md b/docs/buildrun.md
@@ -268,10 +268,28 @@ _Note_: We heavily rely on the Tekton TaskRun [Conditions](https://github.com/te
 
 ### Understanding failed BuildRuns
 
-To make it easier for users to understand why did a BuildRun failed, users can infer from the `Status.FailedAt` field, the pod and container where the failure took place.
+[DEPRECATED] To make it easier for users to understand why did a BuildRun failed, users can infer from the `Status.FailedAt` field, the pod and container where the failure took place.
 
 In addition, the `Status.Conditions` will host under the `Message` field a compacted message containing the `kubectl` command to trigger, in order to retrieve the logs.
 
+Lastly, users can check `Status.FailureDetails` to get a humanly-readable error message, reason, the failed pod and container.
+The message and reason are only included if the build strategy provides them.
+
+Example of failed BuildRun:
+
+```yaml 
+# [...]
+status:
+  # [...]
+  failureDetails:
+    location:
+      container: step-source-default
+      pod: baran-build-buildrun-gzmv5-b7wbf-pod-bbpqr
+    message: The source repository does not exist, or you have insufficient permission
+      to access it.
+    reason: git-remote-private
+```
+
 ### Step Results in BuildRun Status
 
 After the successful completion of a `BuildRun`, the `.status` field contains the results (`.status.taskResults`) emitted from the `TaskRun` steps generate by the `BuildRun` controller as part of processing the `BuildRun`. These results contain valuable metadata for users, like the _image digest_ or the _commit sha_ of the source code used for building.

diff --git a/pkg/apis/build/v1alpha1/buildrun_types.go b/pkg/apis/build/v1alpha1/buildrun_types.go
@@ -145,7 +145,7 @@ type BuildRunStatus struct {
 	// +optional
 	BuildSpec *BuildSpec `json:"buildSpec,omitempty"`
 
-	// FailedAt points to the resource where the BuildRun failed
+	// Deprecated: FailedAt points to the resource where the BuildRun failed
 	// +optional
 	FailedAt *FailedAt `json:"failedAt,omitempty"`
 

diff --git a/pkg/reconciler/buildrun/resources/conditions.go b/pkg/reconciler/buildrun/resources/conditions.go
@@ -81,9 +81,11 @@ func UpdateBuildRunUsingTaskRunCondition(ctx context.Context, client client.Clie
 				return err
 			}
 
+			//lint:ignore SA1019 we want to give users some time to adopt to failureDetails
 			buildRun.Status.FailedAt = &buildv1alpha1.FailedAt{Pod: pod.Name}
 
 			if failedContainer != nil {
+			  //lint:ignore SA1019 we want to give users some time to adopt to failureDetails
 				buildRun.Status.FailedAt.Container = failedContainer.Name
 				message = fmt.Sprintf("buildrun step %s failed in pod %s, for detailed information: kubectl --namespace %s logs %s --container=%s",
 					failedContainer.Name,

diff --git a/pkg/reconciler/buildrun/resources/failureDetails.go b/pkg/reconciler/buildrun/resources/failureDetails.go
@@ -8,6 +8,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+
 	buildv1alpha1 "github.com/shipwright-io/build/pkg/apis/build/v1alpha1"
 	"github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1"
 	v1 "k8s.io/api/core/v1"
@@ -17,6 +18,8 @@ import (
 )
 
 const (
+	resultErrorMessage         = "error-message"
+	resultErrorReason          = "error-reason"
 	prefixedResultErrorReason  = prefixParamsResultsVolumes + "-" + resultErrorReason
 	prefixedResultErrorMessage = prefixParamsResultsVolumes + "-" + resultErrorMessage
 )
@@ -80,8 +83,8 @@ func extractFailedPodAndContainer(ctx context.Context, client client.Client, tas
 }
 
 func extractFailureDetails(ctx context.Context, client client.Client, taskRun *v1beta1.TaskRun) (failure *buildv1alpha1.FailureDetails) {
-	failure = &buildv1alpha1.FailureDetails{ }
-	failure.Location = &buildv1alpha1.FailedAt{ Pod: taskRun.Status.PodName }
+	failure = &buildv1alpha1.FailureDetails{}
+	failure.Location = &buildv1alpha1.FailedAt{Pod: taskRun.Status.PodName}
 
 	if reason, message, hasReasonAndMessage := extractFailureReasonAndMessage(taskRun); hasReasonAndMessage {
 		failure.Reason = reason

diff --git a/pkg/reconciler/buildrun/resources/taskrun.go b/pkg/reconciler/buildrun/resources/taskrun.go
@@ -28,9 +28,6 @@ const (
 	paramSourceRoot    = "source-root"
 	paramSourceContext = "source-context"
 
-	resultErrorMessage = "error-message"
-	resultErrorReason  = "error-reason"
-
 	workspaceSource = "source"
 
 	inputParamBuilder    = "BUILDER_IMAGE"