Skip to content

Commit b8abe73

Browse files
ericzzzzzzzericzzzzzzz
committed
kind/feat: surface artifacts through termination message
1 parent a98770e commit b8abe73

29 files changed

+2691
-3
lines changed

‎docs/artifacts.md

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
<!--
2+
---
3+
linkTitle: "Artifacts"
4+
weight: 201
5+
---
6+
-->
7+
8+
# Artifacts
9+
10+
- [Overview](#overview)
11+
- [Artifact Provenance Data](#passing-artifacts-between-steps)
12+
- [Passing Artifacts between Steps](#passing-artifacts-between-steps)
13+
14+
15+
16+
## Overview
17+
> :seedling: **`Artifacts` is an [alpha](additional-configs.md#alpha-features) feature.**
18+
> The `enable-artifacts` feature flag must be set to `"true"` to read or write artifacts in a step.
19+
20+
Artifacts provide a way to track the origin of data produced and consumed within your Tekton Tasks.
21+
22+
## Artifact Provenance Data
23+
Artifacts fall into two categories:
24+
25+
- Inputs: Artifacts downloaded and used by the Step/Task.
26+
- Outputs: Artifacts created and uploaded by the Step/Task.
27+
Example Structure:
28+
```json
29+
{
30+
"inputs":[
31+
{
32+
"name": "<input-category-name>",
33+
"values": [
34+
{
35+
"uri": "pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
36+
"digest": { "sha256": "b35caccc..." }
37+
}
38+
]
39+
}
40+
],
41+
"outputs": [
42+
{
43+
"name": "<output-category-name>",
44+
"values": [
45+
{
46+
"uri": "pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
47+
"digest": {
48+
"sha256": "df85b9e3...",
49+
"sha1": "95588b8f..."
50+
}
51+
}
52+
]
53+
}
54+
]
55+
}
56+
57+
```
58+
59+
The content is written by the `Step` to a file `$(step.artifacts.path)`:
60+
61+
```yaml
62+
apiVersion: tekton.dev/v1
63+
kind: TaskRun
64+
metadata:
65+
generateName: step-artifacts-
66+
spec:
67+
taskSpec:
68+
description: |
69+
A simple task that populates artifacts to TaskRun stepState
70+
steps:
71+
- name: artifacts-producer
72+
image: bash:latest
73+
script: |
74+
cat > $(step.artifacts.path) << EOF
75+
{
76+
"inputs":[
77+
{
78+
"name":"source",
79+
"values":[
80+
{
81+
"uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
82+
"digest":{
83+
"sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
84+
}
85+
}
86+
]
87+
}
88+
],
89+
"outputs":[
90+
{
91+
"name":"image",
92+
"values":[
93+
{
94+
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
95+
"digest":{
96+
"sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
97+
"sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
98+
}
99+
}
100+
]
101+
}
102+
]
103+
}
104+
EOF
105+
```
106+
107+
It is recommended to use [purl format](https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst) for artifacts uri as shown in the example.
108+
109+
### Passing Artifacts between Steps
110+
You can pass artifacts from one step to the next using:
111+
112+
- Specific Artifact: `$(steps.<step-name>.inputs.<artifact-category-name>)` or `$(steps.<step-name>.outputs.<artifact-category-name>)`
113+
- Default (First) Artifact: `$(steps.<step-name>.inputs)` or `$(steps.<step-name>.outputs)` (if <artifact-category-name> is omitted)
114+
115+
The example below shows how to access the previous' step artifacts from another step in the same task
116+
117+
```yaml
118+
apiVersion: tekton.dev/v1
119+
kind: TaskRun
120+
metadata:
121+
generateName: step-artifacts-
122+
spec:
123+
taskSpec:
124+
description: |
125+
A simple task that populates artifacts to TaskRun stepState
126+
steps:
127+
- name: artifacts-producer
128+
image: bash:latest
129+
script: |
130+
# the script is for creating the output artifacts
131+
cat > $(step.artifacts.path) << EOF
132+
{
133+
"inputs":[
134+
{
135+
"name":"source",
136+
"values":[
137+
{
138+
"uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
139+
"digest":{
140+
"sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
141+
}
142+
}
143+
]
144+
}
145+
],
146+
"outputs":[
147+
{
148+
"name":"image",
149+
"values":[
150+
{
151+
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
152+
"digest":{
153+
"sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
154+
"sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
155+
}
156+
}
157+
]
158+
}
159+
]
160+
}
161+
EOF
162+
- name: artifacts-consumer
163+
image: bash:latest
164+
script: |
165+
echo $(steps.artifacts-producer.outputs)
166+
```
167+
168+
169+
The resolved value of `$(steps.<step-name>.outputs.<artifact-category-name>)` or `$(steps.<step-name>.outputs)` is the values of an artifact. For this example,
170+
`$(steps.artifacts-producer.outputs)` is resolved to
171+
```json
172+
[
173+
{
174+
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
175+
"digest":{
176+
"sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
177+
"sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
178+
}
179+
}
180+
]
181+
```
182+
183+
184+
Upon resolution and execution of the `TaskRun`, the `Status` will look something like:
185+
```yaml
186+
"steps": [
187+
{
188+
"container": "step-artifacts-producer",
189+
"imageID": "docker.io/library/bash@sha256:5353512b79d2963e92a2b97d9cb52df72d32f94661aa825fcfa0aede73304743",
190+
"inputs": [
191+
{
192+
"name": "source",
193+
"values": [
194+
{
195+
"digest": {
196+
"sha256": "b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
197+
},
198+
"uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
199+
}
200+
]
201+
}
202+
],
203+
"name": "artifacts-producer",
204+
"outputs": [
205+
{
206+
"name": "image",
207+
"values": [
208+
{
209+
"digest": {
210+
"sha1": "95588b8f34c31eb7d62c92aaa4e6506639b06ef2",
211+
"sha256": "df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48"
212+
},
213+
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
214+
}
215+
]
216+
}
217+
],
218+
"terminated": {
219+
"containerID": "containerd://010f02d103d1db48531327a1fe09797c87c1d50b6a216892319b3af93e0f56e7",
220+
"exitCode": 0,
221+
"finishedAt": "2024-03-18T17:05:06Z",
222+
"message": "...",
223+
"reason": "Completed",
224+
"startedAt": "2024-03-18T17:05:06Z"
225+
},
226+
"terminationReason": "Completed"
227+
},
228+
{
229+
"container": "step-artifacts-consumer",
230+
"imageID": "docker.io/library/bash@sha256:5353512b79d2963e92a2b97d9cb52df72d32f94661aa825fcfa0aede73304743",
231+
"name": "artifacts-consumer",
232+
"terminated": {
233+
"containerID": "containerd://42428aa7e5a507eba924239f213d185dd4bc0882b6f217a79e6792f7fec3586e",
234+
"exitCode": 0,
235+
"finishedAt": "2024-03-18T17:05:06Z",
236+
"reason": "Completed",
237+
"startedAt": "2024-03-18T17:05:06Z"
238+
},
239+
"terminationReason": "Completed"
240+
}
241+
],
242+
243+
```

‎docs/pipeline-api.md

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1312,7 +1312,7 @@ TaskRunStatus
13121312
<h3 id="tekton.dev/v1.Artifact">Artifact
13131313
</h3>
13141314
<p>
1315-
(<em>Appears on:</em><a href="#tekton.dev/v1.StepState">StepState</a>)
1315+
(<em>Appears on:</em><a href="#tekton.dev/v1.Artifacts">Artifacts</a>, <a href="#tekton.dev/v1.StepState">StepState</a>)
13161316
</p>
13171317
<div>
13181318
<p>TaskRunStepArtifact represents an artifact produced or used by a step within a task run.
@@ -1390,6 +1390,47 @@ string
13901390
</tr>
13911391
</tbody>
13921392
</table>
1393+
<h3 id="tekton.dev/v1.Artifacts">Artifacts
1394+
</h3>
1395+
<div>
1396+
<p>Artifacts represents the collection of input and output artifacts associated with
1397+
a task run or a similar process. Artifacts in this context are units of data or resources
1398+
that the process either consumes as input or produces as output.</p>
1399+
</div>
1400+
<table>
1401+
<thead>
1402+
<tr>
1403+
<th>Field</th>
1404+
<th>Description</th>
1405+
</tr>
1406+
</thead>
1407+
<tbody>
1408+
<tr>
1409+
<td>
1410+
<code>inputs</code><br/>
1411+
<em>
1412+
<a href="#tekton.dev/v1.Artifact">
1413+
[]Artifact
1414+
</a>
1415+
</em>
1416+
</td>
1417+
<td>
1418+
</td>
1419+
</tr>
1420+
<tr>
1421+
<td>
1422+
<code>outputs</code><br/>
1423+
<em>
1424+
<a href="#tekton.dev/v1.Artifact">
1425+
[]Artifact
1426+
</a>
1427+
</em>
1428+
</td>
1429+
<td>
1430+
</td>
1431+
</tr>
1432+
</tbody>
1433+
</table>
13931434
<h3 id="tekton.dev/v1.ChildStatusReference">ChildStatusReference
13941435
</h3>
13951436
<p>
@@ -9614,7 +9655,7 @@ TaskRunStatus
96149655
<h3 id="tekton.dev/v1beta1.Artifact">Artifact
96159656
</h3>
96169657
<p>
9617-
(<em>Appears on:</em><a href="#tekton.dev/v1beta1.StepState">StepState</a>)
9658+
(<em>Appears on:</em><a href="#tekton.dev/v1beta1.Artifacts">Artifacts</a>, <a href="#tekton.dev/v1beta1.StepState">StepState</a>)
96189659
</p>
96199660
<div>
96209661
<p>TaskRunStepArtifact represents an artifact produced or used by a step within a task run.
@@ -9692,6 +9733,47 @@ string
96929733
</tr>
96939734
</tbody>
96949735
</table>
9736+
<h3 id="tekton.dev/v1beta1.Artifacts">Artifacts
9737+
</h3>
9738+
<div>
9739+
<p>Artifacts represents the collection of input and output artifacts associated with
9740+
a task run or a similar process. Artifacts in this context are units of data or resources
9741+
that the process either consumes as input or produces as output.</p>
9742+
</div>
9743+
<table>
9744+
<thead>
9745+
<tr>
9746+
<th>Field</th>
9747+
<th>Description</th>
9748+
</tr>
9749+
</thead>
9750+
<tbody>
9751+
<tr>
9752+
<td>
9753+
<code>inputs</code><br/>
9754+
<em>
9755+
<a href="#tekton.dev/v1beta1.Artifact">
9756+
[]Artifact
9757+
</a>
9758+
</em>
9759+
</td>
9760+
<td>
9761+
</td>
9762+
</tr>
9763+
<tr>
9764+
<td>
9765+
<code>outputs</code><br/>
9766+
<em>
9767+
<a href="#tekton.dev/v1beta1.Artifact">
9768+
[]Artifact
9769+
</a>
9770+
</em>
9771+
</td>
9772+
<td>
9773+
</td>
9774+
</tr>
9775+
</tbody>
9776+
</table>
96959777
<h3 id="tekton.dev/v1beta1.ChildStatusReference">ChildStatusReference
96969778
</h3>
96979779
<p>

0 commit comments

Comments
 (0)