Organize (#112)

* organizing main readme

* organizing main readme

* 2nd round of changes

* edit service account and rbac page

README.md

@@ -4,18 +4,15 @@ Experimental project to bring Kubeflow Pipelines and Tekton together. The work i
 ## Tekton
 The Tekton Pipelines project provides Kubernetes-style resources for declaring CI/CD-style pipelines. Tekton introduces several new CRDs including Task, Pipeline, TaskRun, and PipelineRun. A PipelineRun represents a single running instance of a Pipeline and is responsible for creating a Pod for each of its Tasks and as many containers within each Pod as it has Steps.  Some tasks here will invariably require contributions back to Tekton. Please follow the community guidelines in [Tekton repo](https://github.com/tektoncd/pipeline).
 
-## Development
+## Development: Kubeflow Pipeline DSL to Tekton Compiler
 
-The current work is being split in four areas, namely Compiler, API (with corresponding backend), SDK (functionalities beyond the compilation, like uploading and launching a pipeline etc.) and UI. To get more details about what these different areas entail, please dive into the [design doc](http://bit.ly/kfp-tekton). Currently we are progressing with first one in the list, namely Compiler to compile from KFP DSL to Tekton Yaml. We would love to have teams pick up other major areas like API/UI etc. and/or contribute to make the Tekton Compiler functions and feature complete.
+The work will be split in three phases. While the details of the phases are listed in the [design doc](http://bit.ly/kfp-tekton), the current effort in this repository is focussed on creating a Kubeflow Pipeline compiler for Tekton, which can take KFP DSL, and compile it to Tekton yaml. We will update the details as we move into other phases, in concurrence with design decisions.
 
-To get started with contributing to KFP Tekton Compiler, please [follow these instructions](sdk/README.md), as well as look at [open issues on the repo](https://github.com/kubeflow/kfp-tekton/issues)
+![kfp-tekton](images/kfp-tekton-phase-one.png)
 
-## KFP and Tekton: Deliverables
-Please note that all these deliverables are work in progress, and at an early stage of exploration and execution. We are using Kubeflow Pipelines  v0.2.2 and Tekton v0.11.0 for these experiments currently.
+To get started with contributing to KFP Tekton Compiler, please [follow these instructions](sdk/README.md), as well as look at [open issues on the repo](https://github.com/kubeflow/kfp-tekton/issues)
 
-1. [KFP, Argo and Tekton Comparision](https://docs.google.com/spreadsheets/d/1LFUy86MhVrU2cRhXNsDU-OBzB4BlkT9C0ASD3hoXqpo/edit#gid=979402121)
-2. [Equivalent Argo and Tekton Yaml for Flip Coin Sample from Kubeflow Pipeline](/samples/kfp-tekton)
-3. [KFP Compiler for Tekton](sdk/README.md)
+We are using Kubeflow Pipelines v0.2.2 and Tekton v0.11.0 for the project currently. You may also be interested in [KFP, Argo and Tekton Features Comparision](https://docs.google.com/spreadsheets/d/1LFUy86MhVrU2cRhXNsDU-OBzB4BlkT9C0ASD3hoXqpo/edit#gid=979402121) which the team has compiled, and it goes in fine-grained details.
 
 ## CD Foundation
 

sdk/README.md

@@ -4,7 +4,7 @@ There is an [SDK](https://www.kubeflow.org/docs/pipelines/sdk/sdk-overview/)
 for `Kubeflow Pipeline` for end users to define end to end machine learning and data pipelines.
 The output of the KFP SDK compiler is YAML for [Argo](https://github.com/argoproj/argo).
 
-Here we update the `Compiler` of the KFP SDK to generate `Tekton` YAML for a basic pipeline with parallel and sequential steps. Please go through these steps to ensure you are setup properly to use the compiler.
+We are updating the `Compiler` of the KFP SDK to generate `Tekton` YAML. Please go through these steps to ensure you are setup properly to use the updated compiler.
 
 ## Development Prerequisites
 
@@ -20,13 +20,11 @@ Here we update the `Compiler` of the KFP SDK to generate `Tekton` YAML for a bas
  - Tekton: [`0.11.0`](https://github.com/tektoncd/pipeline/releases/tag/v0.11.0-rc1)
  - Tekton CLI: [`0.8.0`](https://github.com/tektoncd/cli/releases/tag/v0.8.0)
 
-In order to use parameter passing from task outputs into condition parameters Tekton must be built from master. 
+In order to utilize the latest features and functions team has been driving in Tekton, we suggest that Tekton must be built from [master](https://github.com/tektoncd/pipeline/blob/master/DEVELOPMENT.md#install-pipeline). 
 
 ## Tested Pipelines
-- [Execution Order](https://github.com/kubeflow/pipelines/blob/master/samples/core/execution_order/execution_order.py)
-- [Parallel Join](https://github.com/kubeflow/pipelines/blob/master/samples/core/parallel_join/parallel_join.py)
-- [Watson ML](https://github.com/kubeflow/pipelines/blob/master/samples/contrib/ibm-samples/watson/watson_train_serve_pipeline.py)
-    - Watson ML pipeline requires the default service account to have list, write, and delete secrets permission. Additionally, please follow the [instructions here to address the requirements and setup your Watson environments](https://github.com/kubeflow/pipelines/tree/master/samples/contrib/ibm-samples/watson) before executing the pipeline.
+
+We are running the tests over approximately 80+ Pipelines spread across different Kubeflow Pipelines repository, specifically pipelines in KFP compiler test data, KFP core samples and 3rd-party contributed pipelines folders. 
 
 ## Steps
 
@@ -104,7 +102,7 @@ To compile Kubeflow Pipelines as Tekton pipelineRun, simply add the `--generate-
 
 Prerequisite: Install [Kubeflow Pipeline](https://www.kubeflow.org/docs/pipelines/installation/).
 
-By default, artifacts are disabled because it's depended on Kubeflow Pipeline's minio setup. When artifacts are enabled, all the output parameters are also treated as artifacts and persist to the default object storage. Enabling artifacts also allow files to be downloaded or stored as artifact inputs/outputs. Since artifacts are depending on the Kubeflow Pipeline's setup by default, the generated Tekton pipeline must be deployed to the same namespace as Kubeflow Pipeline.
+By default, artifacts are disabled because it's dependent on Kubeflow Pipeline's minio setup. When artifacts are enabled, all the output parameters are also treated as artifacts and persist to the default object storage. Enabling artifacts also allow files to be downloaded or stored as artifact inputs/outputs. Since artifacts are depending on the Kubeflow Pipeline's setup by default, the generated Tekton pipeline must be deployed to the same namespace as Kubeflow Pipeline.
 
 To compile Kubeflow Pipelines as Tekton pipelineRun, simply add the `--enable-artifacts` as part of your `dsl-compile-tekton` commands. Then, run the pipeline on the same namespace as Kubeflow pipeline using the `-n` flag. e.g.
 ```shell
@@ -130,4 +128,4 @@ Waiting for logs to be available...
 ## Troubleshooting
 - Please be aware that defined Affinity, Node Selector, and Tolerations are applied to all the tasks in the same pipeline because there's only one podTemplate allowed in each pipeline.
 
-- When you encounter permission issues related to ServiceAccount, refer to [sa-and-rbac](sa-and-rbac.md)
+- When you encounter permission issues related to ServiceAccount, refer to [Servince Account and RBAC doc](sa-and-rbac.md)

sdk/sa-and-rbac.md

@@ -1,7 +1,6 @@
 # Permission issues
 
-When running some kfp-tekton on your cluster, you may encounter permission issues when the tekton pipeline pod try to create
-resource. For example to run [resourceop_basic](https://github.com/kubeflow/kfp-tekton/blob/master/sdk/python/tests/compiler/testdata/resourceop_basic.py), you may encounter this error:
+When running some kfp-tekton pipelines on your cluster, you may encounter permission issues when the Tekton pipeline pods try to create a resource. For example to run [resourceop_basic](https://github.com/kubeflow/kfp-tekton/blob/master/sdk/python/tests/compiler/testdata/resourceop_basic.py), you may encounter this error:
 
 ```bash
 tkn pipeline start resourceop-basic --showlog
@@ -15,11 +14,12 @@ Waiting for logs to be available...
 failed to get logs for task test-step : container step-test-step has failed  : [{"key":"StartedAt","value":"2020-04-15T22:32:50Z","resourceRef":{}}]
 ```
 
-In the above case, `tekton-pipelines` is using `default` ServiceAccount which doesn't have [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) setup, or the `RBAC` doesn't have enough permission for the pod to create resouce.
+In the above case, `tekton-pipelines` is using `default` ServiceAccount which doesn't have [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) setup, or the `RBAC` doesn't have enough permission for the pod to create resource.
 
 There are two ways to solve this. We list the details here.
 
-## setup RBAC with default serviceAccount 
+## Setup RBAC with default serviceAccount 
+
 Create a ClusterRoleBinding with `cluster-admin` to the default service account. In this case, the default service account is `default` and we are deploying it to the `tekton-pipelines` namespace.
 
 Create `RBAC` permission as below:
@@ -45,7 +45,7 @@ After seeing this message:
 ```bash
 clusterrolebinding.rbac.authorization.k8s.io/default-admin created
 ```
-Re-run the tekton pipeline
+Re-run the Tekton pipeline
 
 ```bash
 tkn pipeline start resourceop-basic --showlog
@@ -61,11 +61,9 @@ Waiting for logs to be available...
 [test-step : test-step] time="2020-04-16T04:44:35Z" level=info msg="Saved output parameter: {}, value: map[apiVersion:batch/v1 kind:Job metadata:map[creationTimestamp:2020-04-16T04:44:31Z generateName:resourceop-basic-job- labels:map[controller-uid:a7e443db-361d-4e71-925c-fd8664017359 job-name:resourceop-basic-job-q9lw5] name:resourceop-basic-job-q9lw5 namespace:tekton-pipelines resourceVersion:9922678 selfLink:/apis/batch/v1/namespaces/tekton-pipelines/jobs/resourceop-basic-job-q9lw5 uid:a7e443db-361d-4e71-925c-fd8664017359] spec:map[backoffLimit:4 completions:1 parallelism:1 selector:map[matchLabels:map[controller-uid:a7e443db-361d-4e71-925c-fd8664017359]] template:map[metadata:map[creationTimestamp:<nil> labels:map[controller-uid:a7e443db-361d-4e71-925c-fd8664017359 job-name:resourceop-basic-job-q9lw5] name:resource-basic] spec:map[containers:[map[command:[/usr/bin/env] image:k8s.gcr.io/busybox imagePullPolicy:Always name:sample-container resources:map[] terminationMessagePath:/dev/termination-log terminationMessagePolicy:File]] dnsPolicy:ClusterFirst restartPolicy:Never schedulerName:default-scheduler securityContext:map[] terminationGracePeriodSeconds:30]]] status:map[active:1 startTime:2020-04-16T04:44:31Z]]"
 ```
 
-## setup RBAC with customized serviceAccount
-
-If you want to use customized ServiceAccount, you can bind your customized ServiceAccount with RBAC.
+## Setup RBAC with customized ServiceAccount
 
-For example, if you have a ServiceAccount name: `test-sa-rbac` in the `tekton-pipelines` namespace, create `RBAC` permission as below for that ServiceAccount:
+If you want to use customized ServiceAccount, you can bind it with RBAC. For example, if you have a ServiceAccount name: `test-sa-rbac` in the `tekton-pipelines` namespace, create `RBAC` permission as defined below for that ServiceAccount:
 
 ```bash
 cat <<EOF |kubectl apply -f -
@@ -87,12 +85,15 @@ After you see this message
 ```bash
 clusterrolebinding.rbac.authorization.k8s.io/default-admin configured
 ```
-Using this tekton cli command to run the pipeline with your ServiceAccount
+
+Use this tekton cli command to run the pipeline with your ServiceAccount
 
 ```bash
 tkn pipeline start resourceop-basic -s test-sa-rbac --showlog
 ```
-Here is the output looks like:
+
+Here is how the output looks like:
+
 ```bash
 Pipelinerun started: resourceop-basic-run-xnlls
 Waiting for logs to be available...
@@ -106,4 +107,4 @@ Waiting for logs to be available...
 [test-step : test-step] time="2020-04-16T05:27:25Z" level=info msg="Saved output parameter: {}, value: map[apiVersion:batch/v1 kind:Job metadata:map[creationTimestamp:2020-04-16T05:27:22Z generateName:resourceop-basic-job- labels:map[controller-uid:7e52145e-a9bc-45a3-9516-21105963a3dc job-name:resourceop-basic-job-qwxhs] name:resourceop-basic-job-qwxhs namespace:tekton-pipelines resourceVersion:9933832 selfLink:/apis/batch/v1/namespaces/tekton-pipelines/jobs/resourceop-basic-job-qwxhs uid:7e52145e-a9bc-45a3-9516-21105963a3dc] spec:map[backoffLimit:4 completions:1 parallelism:1 selector:map[matchLabels:map[controller-uid:7e52145e-a9bc-45a3-9516-21105963a3dc]] template:map[metadata:map[creationTimestamp:<nil> labels:map[controller-uid:7e52145e-a9bc-45a3-9516-21105963a3dc job-name:resourceop-basic-job-qwxhs] name:resource-basic] spec:map[containers:[map[command:[/usr/bin/env] image:k8s.gcr.io/busybox imagePullPolicy:Always name:sample-container resources:map[] terminationMessagePath:/dev/termination-log terminationMessagePolicy:File]] dnsPolicy:ClusterFirst restartPolicy:Never schedulerName:default-scheduler securityContext:map[] terminationGracePeriodSeconds:30]]] status:map[active:1 startTime:2020-04-16T05:27:22Z]]"
 ```
 
-For the detail about the tekton cli command, check [tkn pipeline start](https://github.com/tektoncd/cli/blob/master/docs/cmd/tkn_pipeline_start.md)
+For details about the tekton cli command, check [tkn pipeline start](https://github.com/tektoncd/cli/blob/master/docs/cmd/tkn_pipeline_start.md)