Improved KEP-0017 design (#854)

**What this PR does / why we need it:**

This is a minor change to KEP-0017 by moving the `pipe` section to the `tasks` instead of it being at the level of an individual `resource`. This aligns much better with our goal to encapsulate different types of tasks in the future.

Related: #774

keps/0017-pipe-tasks.md

@@ -45,25 +45,34 @@ Allowing to pipe all kind of files (>1Mb) between tasks requires a general-purpo
 
 This section describes how pipe tasks and files they produce are configured in the operator. Here is a task definition that produces a file that will be stored as a Secret, referenced by `{{.Pipes.Certificate}}` key:
 ```yaml
-steps:
-    - name: bootstrap
-    tasks:
-        - gencert
-            - pipe:
-                - file: /usr/share/MyKey.key
-                  kind: Secret # ConfigMap
-                  key: {{.Pipes.Certificate}}
-``` 
-The key `{{.Pipes.Certificate}}` value will be generated by KUDO to avoid collisions and to make sure that it is not used before the file is generated. In the above example we would generate a secret name like `instance-myapp.deploy.bootstrap.gencert.pipes.certificate-#hash` to capture instance name along with plan/phase/step/task of the secret origin and the hash of its content. KUDO would use this hash to avoid recreating secrets for unchanged files on a plan rerun. We would also use labels ensuring that the secret is cleaned up when the corresponding Instance is removed.
-
-The corresponding `gencert` task can only have one resource definition:
-```yaml
 tasks:
   gencert:
     resources:
       - gencert.yaml
+    pipe:
+       file: /usr/share/MyKey.key
+       kind: Secret # ConfigMap
+       key: {{.Pipes.Certificate}}
+``` 
+
+The key `{{.Pipes.Certificate}}` value will be generated by KUDO to avoid collisions and to make sure that it is not used before the file is generated. In the above example we would generate a secret name like `instance-myapp.deploy.bootstrap.gencert.pipes.certificate-#hash` to capture instance name along with plan/phase/step/task of the secret origin and the hash of its content. KUDO would use this hash to avoid recreating secrets for unchanged files on a plan rerun. We would also use labels ensuring that the secret is cleaned up when the corresponding Instance is removed. Note that pipe tasks can only have one resource in the `resources` list.
+
+The corresponding `gencert` task can be used as usual in e.g.:
+```yaml
+plans:
+  deploy:
+    strategy: serial
+    phases:
+     - name: bootstrap
+       strategy: serial
+       steps:
+        - name: gencert
+          tasks:
+           - gencert
 ```
 
+Note that piped files has to be generated before they can be used. In the example above, `bootstrap` phase has a strategy `serial` so that certificate generated in the `gencert` step can be used in subsequent steps. Or stated differently resources can not reference piped files generated within the same step or within a parallel series of steps. 
+
 For the pipe task resources, we only allow a [ContainerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#container-v1-core) to be specified. Reasons for that are explained below in the implementation details. The ContainerSpec has to define a shared volume where the files are stored.
 
 ```yaml
@@ -107,7 +116,7 @@ spec:
 ### Implementation Details/Notes/Constraints
 
 There are several ways to implement pipe tasks, each one having its challenges and complexities. The approach below allows us not to worry about Pod container life-cycle as well as keep the storing logic in the KUDO controller:
-- Provided ContainerSpec is injected into a Pod as an [InitContainer](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/). This is the simplest way to wait for container completion. This is also the reason why pipe task resource definition is a ContainerSpec and not a complete Pod specification.
+- Provided ContainerSpec is injected into a Pod as an [InitContainer](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/). This is the simplest way to wait for container completion. This is also the reason why pipe task resource definition is a ContainerSpec and not a complete Pod specification. Pod init container can not have Lifecycle actions, Readiness probes, or Liveness probes fields defined. 
 - The main container is a `busybox` image, running the `sleep infinity` command, which purpose is to wait for KUDO to extract and store the files.
 - Pod status `READY: 1/1, STATUS: Running` means that the init container has run successfully. As this point KUDO can copy out referenced files using `kubectl cp` and store them as specified.
 - Once files are stored, KUDO can delete the Pod and proceed to the next task.