Skip to content

Commit 454ddec

Browse files
dibyomtekton-robot
dibyom
authored and
tekton-robot
committed
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 <[email protected]>
1 parent e7df1fb commit 454ddec

File tree

4 files changed

+166
-145
lines changed

4 files changed

+166
-145
lines changed

‎docs/conditions.md‎

Lines changed: 3 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -67,21 +67,9 @@ is validated against the type field.
6767
Conditions can declare input [`PipelineResources`](resources.md) via the `resources` field to
6868
provide the Condition container step with data or context that is needed to perform the check.
6969

70-
Input resources, like source code (git), are dumped at path
71-
`/workspace/resource_name` within a mounted
72-
[volume](https://kubernetes.io/docs/concepts/storage/volumes/). The condition container can use the `path`
73-
[template](./tasks.md#Templating) key to refer to the local path to the mounted resource.
74-
75-
```yaml
76-
spec:
77-
resources:
78-
- name: workspace
79-
type: git
80-
check:
81-
image: alpine
82-
command: ["/bin/sh"]
83-
args: ['-c', 'test -f $(resources.workspace.path)/README.md']
84-
```
70+
Resources in Conditions work similar to the way they work in `Tasks` i.e. they can be accessed using
71+
[variable substitution](./resources.md#variable-substitution) and the `targetPath` field can be used
72+
to [control where the resource is mounted](./resources.md#controlling-where-resources-are-mounted)
8573

8674
## Examples
8775

‎docs/resources.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ For example:
1717

1818
- [Syntax](#syntax)
1919
- [Resource types](#resource-types)
20+
- [Using Resources](#using-resources)
2021

2122
## Syntax
2223

@@ -41,6 +42,161 @@ following fields:
4142
[kubernetes-overview]:
4243
https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
4344

45+
## Using Resources
46+
47+
Resources can be used in [Tasks](./tasks.md) and [Conditions](./conditions.md#resources).
48+
49+
Input resources, like source code (git) or artifacts, are dumped at path
50+
`/workspace/task_resource_name` within a mounted
51+
[volume](https://kubernetes.io/docs/concepts/storage/volumes/) and is available
52+
to all [`steps`](#steps) of your `Task`. The path that the resources are mounted
53+
at can be [overridden with the `targetPath` field](./resources.md#controlling-where-resources-are-mounted).
54+
Steps can use the `path`[variable substitution](#variable-substitution) key to refer to the local path to the mounted resource.
55+
56+
### Variable substitution
57+
58+
`Task` and `Condition` specs can refer resource params as well as pre-defined variables such as
59+
`path` using the variable substitution syntax below where `<name>` is the Resource Name and `<key>`
60+
is a one of the resource's `params`:
61+
62+
63+
#### In Task Spec:
64+
For an input resource in a `Task` spec:
65+
```shell
66+
$(inputs.resources.<name>.<key>)
67+
```
68+
69+
Or for an output resource:
70+
71+
```shell
72+
$(outputs.resources.<name>.<key>)
73+
```
74+
75+
#### In Condition Spec:
76+
Input resources can be accessed by:
77+
78+
```shell
79+
$(resources.<name>.<key>)
80+
```
81+
82+
#### Accessing local path to resource
83+
84+
The `path` key is pre-defined and refers to the local path to a resource on the mounted volume
85+
```shell
86+
$(inputs.resouces.<name>.path)
87+
```
88+
89+
_The deprecated syntax `${}`, e.g. `${inputs.params.<name>}` will be supported
90+
until [#1170](https://github.com/tektoncd/pipeline/issues/1170)._
91+
92+
### Controlling where resources are mounted
93+
94+
The optional field `targetPath` can be used to initialize a resource in specific
95+
directory. If `targetPath` is set then resource will be initialized under
96+
`/workspace/targetPath`. If `targetPath` is not specified then resource will be
97+
initialized under `/workspace`. Following example demonstrates how git input
98+
repository could be initialized in `$GOPATH` to run tests:
99+
100+
```yaml
101+
apiVersion: tekton.dev/v1alpha1
102+
kind: Task
103+
metadata:
104+
name: task-with-input
105+
namespace: default
106+
spec:
107+
inputs:
108+
resources:
109+
- name: workspace
110+
type: git
111+
targetPath: go/src/github.com/tektoncd/pipeline
112+
steps:
113+
- name: unit-tests
114+
image: golang
115+
command: ["go"]
116+
args:
117+
- "test"
118+
- "./..."
119+
workingDir: "/workspace/go/src/github.com/tektoncd/pipeline"
120+
env:
121+
- name: GOPATH
122+
value: /workspace/go
123+
```
124+
125+
### Overriding where resources are copied from
126+
127+
When specifying input and output `PipelineResources`, you can optionally specify
128+
`paths` for each resource. `paths` will be used by `TaskRun` as the resource's
129+
new source paths i.e., copy the resource from specified list of paths. `TaskRun`
130+
expects the folder and contents to be already present in specified paths.
131+
`paths` feature could be used to provide extra files or altered version of
132+
existing resource before execution of steps.
133+
134+
Output resource includes name and reference to pipeline resource and optionally
135+
`paths`. `paths` will be used by `TaskRun` as the resource's new destination
136+
paths i.e., copy the resource entirely to specified paths. `TaskRun` will be
137+
responsible for creating required directories and copying contents over. `paths`
138+
feature could be used to inspect the results of taskrun after execution of
139+
steps.
140+
141+
`paths` feature for input and output resource is heavily used to pass same
142+
version of resources across tasks in context of pipelinerun.
143+
144+
In the following example, task and taskrun are defined with input resource,
145+
output resource and step which builds war artifact. After execution of
146+
taskrun(`volume-taskrun`), `custom` volume will have entire resource
147+
`java-git-resource` (including the war artifact) copied to the destination path
148+
`/custom/workspace/`.
149+
150+
```yaml
151+
apiVersion: tekton.dev/v1alpha1
152+
kind: Task
153+
metadata:
154+
name: volume-task
155+
namespace: default
156+
spec:
157+
inputs:
158+
resources:
159+
- name: workspace
160+
type: git
161+
outputs:
162+
resources:
163+
- name: workspace
164+
steps:
165+
- name: build-war
166+
image: objectuser/run-java-jar #https://hub.docker.com/r/objectuser/run-java-jar/
167+
command: jar
168+
args: ["-cvf", "projectname.war", "*"]
169+
volumeMounts:
170+
- name: custom-volume
171+
mountPath: /custom
172+
```
173+
174+
```yaml
175+
apiVersion: tekton.dev/v1alpha1
176+
kind: TaskRun
177+
metadata:
178+
name: volume-taskrun
179+
namespace: default
180+
spec:
181+
taskRef:
182+
name: volume-task
183+
inputs:
184+
resources:
185+
- name: workspace
186+
resourceRef:
187+
name: java-git-resource
188+
outputs:
189+
resources:
190+
- name: workspace
191+
paths:
192+
- /custom/workspace/
193+
resourceRef:
194+
name: java-git-resource
195+
volumes:
196+
- name: custom-volume
197+
emptyDir: {}
198+
```
199+
44200
## Resource Types
45201

46202
The following `PipelineResources` are currently supported:

‎docs/taskruns.md‎

Lines changed: 2 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,8 @@ spec:
143143
value: https://github.com/pivotal-nader-ziada/gohelloworld
144144
```
145145

146+
The `paths` field can be used to [override the paths to a resource](./resources.md#overriding-where-resources-are-copied-from)
147+
146148
### Configuring Default Timeout
147149

148150
You can configure the default timeout by changing the value of `default-timeout-minutes`
@@ -221,77 +223,7 @@ spec:
221223
claimName: my-volume-claim
222224
```
223225

224-
### Overriding where resources are copied from
225-
226-
When specifying input and output `PipelineResources`, you can optionally specify
227-
`paths` for each resource. `paths` will be used by `TaskRun` as the resource's
228-
new source paths i.e., copy the resource from specified list of paths. `TaskRun`
229-
expects the folder and contents to be already present in specified paths.
230-
`paths` feature could be used to provide extra files or altered version of
231-
existing resource before execution of steps.
232-
233-
Output resource includes name and reference to pipeline resource and optionally
234-
`paths`. `paths` will be used by `TaskRun` as the resource's new destination
235-
paths i.e., copy the resource entirely to specified paths. `TaskRun` will be
236-
responsible for creating required directories and copying contents over. `paths`
237-
feature could be used to inspect the results of taskrun after execution of
238-
steps.
239-
240-
`paths` feature for input and output resource is heavily used to pass same
241-
version of resources across tasks in context of pipelinerun.
242-
243-
In the following example, task and taskrun are defined with input resource,
244-
output resource and step which builds war artifact. After execution of
245-
taskrun(`volume-taskrun`), `custom` volume will have entire resource
246-
`java-git-resource` (including the war artifact) copied to the destination path
247-
`/custom/workspace/`.
248-
249-
```yaml
250-
apiVersion: tekton.dev/v1alpha1
251-
kind: Task
252-
metadata:
253-
name: volume-task
254-
namespace: default
255-
spec:
256-
inputs:
257-
resources:
258-
- name: workspace
259-
type: git
260-
steps:
261-
- name: build-war
262-
image: objectuser/run-java-jar #https://hub.docker.com/r/objectuser/run-java-jar/
263-
command: jar
264-
args: ["-cvf", "projectname.war", "*"]
265-
volumeMounts:
266-
- name: custom-volume
267-
mountPath: /custom
268-
```
269226

270-
```yaml
271-
apiVersion: tekton.dev/v1alpha1
272-
kind: TaskRun
273-
metadata:
274-
name: volume-taskrun
275-
namespace: default
276-
spec:
277-
taskRef:
278-
name: volume-task
279-
inputs:
280-
resources:
281-
- name: workspace
282-
resourceRef:
283-
name: java-git-resource
284-
outputs:
285-
resources:
286-
- name: workspace
287-
paths:
288-
- /custom/workspace/
289-
resourceRef:
290-
name: java-git-resource
291-
volumes:
292-
- name: custom-volume
293-
emptyDir: {}
294-
```
295227

296228
## Status
297229

‎docs/tasks.md‎

Lines changed: 5 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -222,14 +222,8 @@ spec:
222222
#### Input resources
223223

224224
Use input [`PipelineResources`](resources.md) field to provide your `Task` with
225-
data or context that is needed by your `Task`.
225+
data or context that is needed by your `Task`. See the [using resources docs](./resources.md#using-resources).
226226

227-
Input resources, like source code (git) or artifacts, are dumped at path
228-
`/workspace/task_resource_name` within a mounted
229-
[volume](https://kubernetes.io/docs/concepts/storage/volumes/) and is available
230-
to all [`steps`](#steps) of your `Task`. The path that the resources are mounted
231-
at can be overridden with the `targetPath` value. Steps can use the `path`
232-
[variable substitution](#variable-substitution) key to refer to the local path to the mounted resource.
233227

234228
### Outputs
235229

@@ -289,38 +283,6 @@ steps:
289283
args: ['-c', 'cd /workspace/tar-scratch-space/ && tar -cvf /workspace/customworkspace/rules_docker-master.tar rules_docker-master']
290284
```
291285

292-
### Controlling where resources are mounted
293-
294-
Tasks can opitionally provide `targetPath` to initialize resource in specific
295-
directory. If `targetPath` is set then resource will be initialized under
296-
`/workspace/targetPath`. If `targetPath` is not specified then resource will be
297-
initialized under `/workspace`. Following example demonstrates how git input
298-
repository could be initialized in `$GOPATH` to run tests:
299-
300-
```yaml
301-
apiVersion: tekton.dev/v1alpha1
302-
kind: Task
303-
metadata:
304-
name: task-with-input
305-
namespace: default
306-
spec:
307-
inputs:
308-
resources:
309-
- name: workspace
310-
type: git
311-
targetPath: go/src/github.com/tektoncd/pipeline
312-
steps:
313-
- name: unit-tests
314-
image: golang
315-
command: ["go"]
316-
args:
317-
- "test"
318-
- "./..."
319-
workingDir: "/workspace/go/src/github.com/tektoncd/pipeline"
320-
env:
321-
- name: GOPATH
322-
value: /workspace/go
323-
```
324286

325287
### Volumes
326288

@@ -428,33 +390,16 @@ volumes:
428390
`Tasks` support string replacement using values from all [`inputs`](#inputs) and
429391
[`outputs`](#outputs).
430392

431-
[`PipelineResources`](resources.md) can be referenced in a `Task` spec like
432-
this, where `<name>` is the Resource Name and `<key>` is a one of the resource's
433-
`params`:
434-
435-
```shell
436-
$(inputs.resources.<name>.<key>)
437-
```
438393

439-
Or for an output resource:
440-
441-
```shell
442-
$(outputs.resources.<name>.<key>)
443-
```
444-
445-
The local path to a resource on the mounted volume can be accessed using the
446-
`path` key:
447-
448-
```shell
449-
$(inputs.resouces.<name>.path)
450-
```
451-
452-
To access an input parameter, replace `resources` with `params`.
394+
Input parameters can be referenced in the `Task` spec using the variable substitution syntax below,
395+
where `<name>` is the name of the parameter:
453396

454397
```shell
455398
$(inputs.params.<name>)
456399
```
457400

401+
Param values from resources can also be accessed using [variable substitution](./resources.md#variable-substitution)
402+
458403
_The deprecated syntax `${}`, e.g. `${inputs.params.<name>}` will be supported
459404
until [#1170](https://github.com/tektoncd/pipeline/issues/1170)._
460405

0 commit comments

Comments
 (0)