From 454ddec53fbe0ae6bfcf404c95a00610be19ca2a Mon Sep 17 00:00:00 2001 From: Dibyo Mukherjee Date: Fri, 30 Aug 2019 15:37:19 -0400 Subject: [PATCH] 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 --- docs/conditions.md | 18 +----- docs/resources.md | 156 +++++++++++++++++++++++++++++++++++++++++++++ docs/taskruns.md | 72 +-------------------- docs/tasks.md | 65 ++----------------- 4 files changed, 166 insertions(+), 145 deletions(-) diff --git a/docs/conditions.md b/docs/conditions.md index de7c0f7ca6b..7d72d0f5b9e 100644 --- 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 index be4811c114f..387d2fa7d44 100644 --- 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 `` is the Resource Name and `` +is a one of the resource's `params`: + + +#### In Task Spec: +For an input resource in a `Task` spec: +```shell +$(inputs.resources..) +``` + +Or for an output resource: + +```shell +$(outputs.resources..) +``` + +#### In Condition Spec: +Input resources can be accessed by: + +```shell +$(resources..) +``` + +#### 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..path) +``` + +_The deprecated syntax `${}`, e.g. `${inputs.params.}` 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 index fe85147656a..71332985016 100644 --- 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 index 254ccb11569..86ce8a2ae3e 100644 --- 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 `` is the Resource Name and `` is a one of the resource's -`params`: - -```shell -$(inputs.resources..) -``` -Or for an output resource: - -```shell -$(outputs.resources..) -``` - -The local path to a resource on the mounted volume can be accessed using the -`path` key: - -```shell -$(inputs.resouces..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 `` is the name of the parameter: ```shell $(inputs.params.) ``` +Param values from resources can also be accessed using [variable substitution](./resources.md#variable-substitution) + _The deprecated syntax `${}`, e.g. `${inputs.params.}` will be supported until [#1170](https://github.com/tektoncd/pipeline/issues/1170)._