Add a using resources section in resources.md

The docs for using resources especially around how resource paths work were in a bunch of different places in tasks.md and taskruns.md. This commit consolidates them into resources.md so that both tasks and condition docs can refer to a single place. Signed-off-by: Dibyo Mukherjee <dibyo@google.com>
tektoncd · Sep 4, 2019 · 454ddec · 454ddec
1 parent e7df1fb
commit 454ddec
Show file tree

Hide file tree

Showing 4 changed files with 166 additions and 145 deletions.
diff --git a/docs/conditions.md b/docs/conditions.md
@@ -67,21 +67,9 @@ is validated against the type field.
 Conditions can declare input [`PipelineResources`](resources.md)  via the `resources` field to 
 provide the Condition container step with data or context that is needed to perform the check.
 
-Input resources, like source code (git), are dumped at path
-`/workspace/resource_name` within a mounted
-[volume](https://kubernetes.io/docs/concepts/storage/volumes/). The condition container can use the `path`
-[template](./tasks.md#Templating) key to refer to the local path to the mounted resource.
-
-```yaml
-spec:
-  resources:
-    - name: workspace
-      type: git
-  check:
-    image: alpine
-    command: ["/bin/sh"]
-    args: ['-c', 'test -f $(resources.workspace.path)/README.md']
-```
+Resources in Conditions work similar to the way they work in `Tasks` i.e. they can be accessed using
+[variable substitution](./resources.md#variable-substitution) and the `targetPath` field can be used
+to [control where the resource is mounted](./resources.md#controlling-where-resources-are-mounted)
 
 ## Examples
 

diff --git a/docs/resources.md b/docs/resources.md
@@ -17,6 +17,7 @@ For example:
 
 -   [Syntax](#syntax)
 -   [Resource types](#resource-types)
+-   [Using Resources](#using-resources)
 
 ## Syntax
 
@@ -41,6 +42,161 @@ following fields:
 [kubernetes-overview]:
   https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
 
+## Using Resources
+
+Resources can be used in [Tasks](./tasks.md) and [Conditions](./conditions.md#resources).
+
+Input resources, like source code (git) or artifacts, are dumped at path
+`/workspace/task_resource_name` within a mounted
+[volume](https://kubernetes.io/docs/concepts/storage/volumes/) and is available
+to all [`steps`](#steps) of your `Task`. The path that the resources are mounted
+at can be [overridden with the `targetPath` field](./resources.md#controlling-where-resources-are-mounted). 
+Steps can use the `path`[variable substitution](#variable-substitution) key to refer to the local path to the mounted resource.
+
+### Variable substitution 
+
+`Task` and `Condition` specs can refer resource params as well as pre-defined variables such as 
+`path` using the variable substitution syntax below where `<name>` is the Resource Name and `<key>` 
+is a one of the resource's `params`:
+
+
+#### In Task Spec:
+For an input resource in a `Task` spec:
+```shell
+$(inputs.resources.<name>.<key>)
+```
+
+Or for an output resource:
+
+```shell
+$(outputs.resources.<name>.<key>)
+```
+
+#### In Condition Spec:
+Input resources can be accessed by:
+
+```shell
+$(resources.<name>.<key>)
+```
+
+#### Accessing local path to resource 
+
+The `path` key is pre-defined and refers to the local path to a resource on the mounted volume 
+```shell
+$(inputs.resouces.<name>.path)
+```
+
+_The deprecated syntax `${}`, e.g. `${inputs.params.<name>}` will be supported
+until [#1170](https://github.com/tektoncd/pipeline/issues/1170)._
+
+### Controlling where resources are mounted
+
+The optional field `targetPath` can be used to initialize a resource in specific
+directory. If `targetPath` is set then resource will be initialized under
+`/workspace/targetPath`. If `targetPath` is not specified then resource will be
+initialized under `/workspace`. Following example demonstrates how git input
+repository could be initialized in `$GOPATH` to run tests:
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: Task
+metadata:
+  name: task-with-input
+  namespace: default
+spec:
+  inputs:
+    resources:
+      - name: workspace
+        type: git
+        targetPath: go/src/github.com/tektoncd/pipeline
+  steps:
+    - name: unit-tests
+      image: golang
+      command: ["go"]
+      args:
+        - "test"
+        - "./..."
+      workingDir: "/workspace/go/src/github.com/tektoncd/pipeline"
+      env:
+        - name: GOPATH
+          value: /workspace/go
+```
+
+### Overriding where resources are copied from
+
+When specifying input and output `PipelineResources`, you can optionally specify
+`paths` for each resource. `paths` will be used by `TaskRun` as the resource's
+new source paths i.e., copy the resource from specified list of paths. `TaskRun`
+expects the folder and contents to be already present in specified paths.
+`paths` feature could be used to provide extra files or altered version of
+existing resource before execution of steps.
+
+Output resource includes name and reference to pipeline resource and optionally
+`paths`. `paths` will be used by `TaskRun` as the resource's new destination
+paths i.e., copy the resource entirely to specified paths. `TaskRun` will be
+responsible for creating required directories and copying contents over. `paths`
+feature could be used to inspect the results of taskrun after execution of
+steps.
+
+`paths` feature for input and output resource is heavily used to pass same
+version of resources across tasks in context of pipelinerun.
+
+In the following example, task and taskrun are defined with input resource,
+output resource and step which builds war artifact. After execution of
+taskrun(`volume-taskrun`), `custom` volume will have entire resource
+`java-git-resource` (including the war artifact) copied to the destination path
+`/custom/workspace/`.
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: Task
+metadata:
+  name: volume-task
+  namespace: default
+spec:
+  inputs:
+    resources:
+      - name: workspace
+        type: git
+  outputs:
+    resources:
+      - name: workspace
+  steps:
+    - name: build-war
+      image: objectuser/run-java-jar #https://hub.docker.com/r/objectuser/run-java-jar/
+      command: jar
+      args: ["-cvf", "projectname.war", "*"]
+      volumeMounts:
+        - name: custom-volume
+          mountPath: /custom
+```
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: TaskRun
+metadata:
+  name: volume-taskrun
+  namespace: default
+spec:
+  taskRef:
+    name: volume-task
+  inputs:
+    resources:
+      - name: workspace
+        resourceRef:
+          name: java-git-resource
+  outputs:
+    resources:
+      - name: workspace
+        paths:
+          - /custom/workspace/
+        resourceRef:
+          name: java-git-resource
+  volumes:
+    - name: custom-volume
+      emptyDir: {}
+```
+
 ## Resource Types
 
 The following `PipelineResources` are currently supported:

diff --git a/docs/taskruns.md b/docs/taskruns.md
@@ -143,6 +143,8 @@ spec:
               value: https://github.com/pivotal-nader-ziada/gohelloworld
 ```
 
+The `paths` field can be used to [override the paths to a resource](./resources.md#overriding-where-resources-are-copied-from)
+
 ### Configuring Default Timeout
 
 You can configure the default timeout by changing the value of `default-timeout-minutes`
@@ -221,77 +223,7 @@ spec:
         claimName: my-volume-claim
 ```
 
-### Overriding where resources are copied from
-
-When specifying input and output `PipelineResources`, you can optionally specify
-`paths` for each resource. `paths` will be used by `TaskRun` as the resource's
-new source paths i.e., copy the resource from specified list of paths. `TaskRun`
-expects the folder and contents to be already present in specified paths.
-`paths` feature could be used to provide extra files or altered version of
-existing resource before execution of steps.
-
-Output resource includes name and reference to pipeline resource and optionally
-`paths`. `paths` will be used by `TaskRun` as the resource's new destination
-paths i.e., copy the resource entirely to specified paths. `TaskRun` will be
-responsible for creating required directories and copying contents over. `paths`
-feature could be used to inspect the results of taskrun after execution of
-steps.
-
-`paths` feature for input and output resource is heavily used to pass same
-version of resources across tasks in context of pipelinerun.
-
-In the following example, task and taskrun are defined with input resource,
-output resource and step which builds war artifact. After execution of
-taskrun(`volume-taskrun`), `custom` volume will have entire resource
-`java-git-resource` (including the war artifact) copied to the destination path
-`/custom/workspace/`.
-
-```yaml
-apiVersion: tekton.dev/v1alpha1
-kind: Task
-metadata:
-  name: volume-task
-  namespace: default
-spec:
-  inputs:
-    resources:
-      - name: workspace
-        type: git
-  steps:
-    - name: build-war
-      image: objectuser/run-java-jar #https://hub.docker.com/r/objectuser/run-java-jar/
-      command: jar
-      args: ["-cvf", "projectname.war", "*"]
-      volumeMounts:
-        - name: custom-volume
-          mountPath: /custom
-```
 
-```yaml
-apiVersion: tekton.dev/v1alpha1
-kind: TaskRun
-metadata:
-  name: volume-taskrun
-  namespace: default
-spec:
-  taskRef:
-    name: volume-task
-  inputs:
-    resources:
-      - name: workspace
-        resourceRef:
-          name: java-git-resource
-  outputs:
-    resources:
-      - name: workspace
-        paths:
-          - /custom/workspace/
-        resourceRef:
-          name: java-git-resource
-  volumes:
-    - name: custom-volume
-      emptyDir: {}
-```
 
 ## Status
 

diff --git a/docs/tasks.md b/docs/tasks.md
@@ -222,14 +222,8 @@ spec:
 #### Input resources
 
 Use input [`PipelineResources`](resources.md) field to provide your `Task` with
-data or context that is needed by your `Task`.
+data or context that is needed by your `Task`. See the [using resources docs](./resources.md#using-resources).
 
-Input resources, like source code (git) or artifacts, are dumped at path
-`/workspace/task_resource_name` within a mounted
-[volume](https://kubernetes.io/docs/concepts/storage/volumes/) and is available
-to all [`steps`](#steps) of your `Task`. The path that the resources are mounted
-at can be overridden with the `targetPath` value. Steps can use the `path`
-[variable substitution](#variable-substitution) key to refer to the local path to the mounted resource.
 
 ### Outputs
 
@@ -289,38 +283,6 @@ steps:
    args: ['-c', 'cd /workspace/tar-scratch-space/ && tar -cvf /workspace/customworkspace/rules_docker-master.tar rules_docker-master']
 ```
 
-### Controlling where resources are mounted
-
-Tasks can opitionally provide `targetPath` to initialize resource in specific
-directory. If `targetPath` is set then resource will be initialized under
-`/workspace/targetPath`. If `targetPath` is not specified then resource will be
-initialized under `/workspace`. Following example demonstrates how git input
-repository could be initialized in `$GOPATH` to run tests:
-
-```yaml
-apiVersion: tekton.dev/v1alpha1
-kind: Task
-metadata:
-  name: task-with-input
-  namespace: default
-spec:
-  inputs:
-    resources:
-      - name: workspace
-        type: git
-        targetPath: go/src/github.com/tektoncd/pipeline
-  steps:
-    - name: unit-tests
-      image: golang
-      command: ["go"]
-      args:
-        - "test"
-        - "./..."
-      workingDir: "/workspace/go/src/github.com/tektoncd/pipeline"
-      env:
-        - name: GOPATH
-          value: /workspace/go
-```
 
 ### Volumes
 
@@ -428,33 +390,16 @@ volumes:
 `Tasks` support string replacement using values from all [`inputs`](#inputs) and
 [`outputs`](#outputs).
 
-[`PipelineResources`](resources.md) can be referenced in a `Task` spec like
-this, where `<name>` is the Resource Name and `<key>` is a one of the resource's
-`params`:
-
-```shell
-$(inputs.resources.<name>.<key>)
-```
 
-Or for an output resource:
-
-```shell
-$(outputs.resources.<name>.<key>)
-```
-
-The local path to a resource on the mounted volume can be accessed using the
-`path` key:
-
-```shell
-$(inputs.resouces.<name>.path)
-```
-
-To access an input parameter, replace `resources` with `params`.
+Input parameters can be referenced in the `Task` spec using the variable substitution syntax below, 
+where `<name>` is the name of the parameter:
 
 ```shell
 $(inputs.params.<name>)
 ```
 
+Param values from resources can also be accessed using [variable substitution](./resources.md#variable-substitution)
+
 _The deprecated syntax `${}`, e.g. `${inputs.params.<name>}` will be supported
 until [#1170](https://github.com/tektoncd/pipeline/issues/1170)._