From a7a6044a8510465c3a35aa1e5aa5c357d8c964c7 Mon Sep 17 00:00:00 2001
From: Christie Wilson <bobcatfish@gmail.com>
Date: Thu, 30 May 2019 11:27:25 -0700
Subject: [PATCH] =?UTF-8?q?Add=20docs=20on=20how=20to=20access=20Run=20log?=
 =?UTF-8?q?s=20=F0=9F=97=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As @cmoulliard pointed out, it's not obvious how to get to the logs for
a PipelineRun or a TaskRun. If you know how the underlying kubernetes
resources work you can figure it out but it can be hard to know where to
start. Plus, folks may not realize that we are working on better ways of
accessing logs.

And once we work on #107 we can build up these docs with more detail
about how to upload logs too.

Fixes #898
---
 DEVELOPMENT.md       |  5 ++++-
 docs/README.md       |  2 ++
 docs/logs.md         | 32 ++++++++++++++++++++++++++++++++
 docs/pipelineruns.md |  1 +
 docs/taskruns.md     |  1 +
 docs/tutorial.md     |  1 +
 6 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 docs/logs.md

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 58c29e00c6d..5ebdc53b062 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -14,7 +14,7 @@
 1. [Set up a docker repository you can push to](https://github.com/knative/serving/blob/master/docs/setting-up-a-docker-registry.md)
 
 Then you can [iterate](#iterating) (including
-[runing the controllers with `ko`](#install-pipeline)).
+[running the controllers with `ko`](#install-pipeline)).
 
 ### Ramp up
 
@@ -271,6 +271,9 @@ To look at the webhook logs, run:
 kubectl -n tekton-pipelines logs $(kubectl -n tekton-pipelines get pods -l app=tekton-pipelines-webhook -o name)
 ```
 
+To look at the logs for individual `TaskRuns` or `PipelineRuns`, see
+[docs on accessing logs](docs/logs.md).
+
 ## Adding new types
 
 If you need to add a new CRD type, you will need to add:
diff --git a/docs/README.md b/docs/README.md
index 1aeec1d8cab..e209fd30433 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,6 +34,7 @@ High level details of this design:
 - [How do I control auth?](auth.md)
 - [How do I run a Pipeline?](pipelineruns.md)
 - [How do I run a Task on its own?](taskruns.md)
+- [How do I get logs?](logs.md)
 
 ## Learn more
 
@@ -49,6 +50,7 @@ components:
 Additional reference topics not related to a specific component:
 
 - [Labels](labels.md)
+- [Logs](logs.md)
 
 ## Try it out
 
diff --git a/docs/logs.md b/docs/logs.md
new file mode 100644
index 00000000000..2f6538be45f
--- /dev/null
+++ b/docs/logs.md
@@ -0,0 +1,32 @@
+# Logs
+
+Logs for [`PipelineRuns`](pipelineruns.md) and [`TaskRuns`](taskruns.md) are
+associated with the underlying pod.
+
+_In [#107](https://github.com/tektoncd/pipeline/issues/107)
+we will add a solution to persist logs outside of your kubernetes cluster._
+
+To access these logs currently you have a few options:
+
+* [You can get the logs from the pod](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#interacting-with-running-pods)
+  e.g. using `kubectl`:
+
+  ```bash
+  # Get the name of the pod from the instance of the TaskRun
+  kubectl get taskruns -o yaml | grep podName
+
+  # Or get the pod name from the PipelineRun
+  kubectl get pipelineruns -o yaml | grep podName
+
+  # Use kubectl to access the logs for all containers in the pod
+  kubectl logs $POD_NAME --all-containers
+
+  # Or get the logs from a specific container in the pod
+  kubectl logs $POD_NAME -c $CONTAINER_NAME
+  kubectl logs $POD_NAME -c step-run-kubectl
+  ```
+
+* You can use [the `tkn` cli tool](https://github.com/tektoncd/cli) to access logs
+* You can use [the dashboard web interface](https://github.com/tektoncd/dashboard) to access logs
+* You can setup an external service to consume and display logs, for example
+  [Elasticsearch, Beats and Kibana](https://github.com/mgreau/tekton-pipelines-elastic-tutorials)
\ No newline at end of file
diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md
index 04ccecaeac2..99e6a63faed 100644
--- a/docs/pipelineruns.md
+++ b/docs/pipelineruns.md
@@ -16,6 +16,7 @@ Creation of a `PipelineRun` will trigger the creation of
   - [Service account](#service-account)
 - [Cancelling a PipelineRun](#cancelling-a-pipelinerun)
 - [Examples](#examples)
+- [Logs](logs.md)
 
 ## Syntax
 
diff --git a/docs/taskruns.md b/docs/taskruns.md
index 1504b69b29b..92b45d758b6 100644
--- a/docs/taskruns.md
+++ b/docs/taskruns.md
@@ -19,6 +19,7 @@ A `TaskRun` runs until all `steps` have completed or until a failure occurs.
   - [Service Account](#service-account)
 - [Cancelling a TaskRun](#cancelling-a-taskrun)
 - [Examples](#examples)
+- [Logs](logs.md)
 
 ---
 
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 4ff23c54971..db70bebd1e3 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -583,6 +583,7 @@ Tekton Pipelines is known to work with:
 
 - Logs can remain in-memory only as opposed to sent to a service such as
   [Stackdriver](https://cloud.google.com/logging/).
+- See [docs on getting logs from Runs](logs.md)
 
 Elasticsearch, Beats and Kibana can be deployed locally as a means to view logs:
 an example is provided at