Document odd kubectl get output for pods w/ sidecars

With the current sidecar implementation `kubectl get pods` will
show pods with successful sidecars as Completed but pods with
errored sidecars as Error.

It looks like the kubectl get pods printer code is just using
the status of the last container in the container list as the
source of the "Reason" that it prints for a pod ending. Seems
a bit janky but ¯\_(ツ)_/¯

I'm documenting the behaviour rather than looking to fix it since
there's are existing proposals to improve the sidecar
implementation and this appears to simple be a UI/UX issue. The
status of the TaskRun that generated the pod has the correct
end status regardless of the output from `kubectl get pods`.

docs/developers/README.md

@@ -182,10 +182,17 @@ with updated container image. The nop container image exits immediately
 The container is considered `Terminated` by Kubernetes and the TaskRun's Pod
 stops.
 
-There is a known issue with this implementation of sidecar support. When the
-`nop` image does provide the sidecar's command, the sidecar will continue to
+There are known issues with the existing implementation of sidecars:
+
+- When the `nop` image does provide the sidecar's command, the sidecar will continue to
 run even after `nop` has been swapped into the sidecar container's image
 field. See https://github.com/tektoncd/pipeline/issues/1347 for the issue
 tracking this bug. Until this issue is resolved the best way to avoid it is to
 avoid overriding the `nop` image when deploying the tekton controller, or
 ensuring that the overridden `nop` image contains as few commands as possible.
+
+- `kubectl get pods` will show a Completed pod when a sidecar exits successfully
+but an Error when the sidecar exits with an error. This is only apparent when
+using `kubectl` to get the pods of a TaskRun, not when describing the Pod
+using `kubectl describe pod ...` nor when looking at the TaskRun, but can be quite
+confusing.

docs/taskruns.md

@@ -590,12 +590,21 @@ order to terminate the sidecars they will be restarted with a new
 Pod will include the sidecar container with a Retry Count of 1 and
 with a different container image than you might be expecting.
 
-Note: The configured "nop" image must not provide the command that the
+Note: There are some known issues with the existing implementation of sidecars:
+
+- The configured "nop" image must not provide the command that the
 sidecar is expected to run. If it does provide the command then it will
 not exit. This will result in the sidecar running forever and the Task
 eventually timing out. https://github.com/tektoncd/pipeline/issues/1347
 is the issue where this bug is being tracked.
 
+- `kubectl get pods` will show a TaskRun's Pod as "Completed" if a sidecar
+exits successfully and "Error" if the sidecar exits with an error, regardless
+of how the step containers inside that pod exited. This issue only manifests
+with the `get pods` command. The Pod description will instead show a Status of
+Failed and the individual container statuses will correctly reflect how and why
+they exited.
+
 ---
 
 Except as otherwise noted, the content of this page is licensed under the