Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

kind/feat: Surface artifacts through termination message #7714

Merged
merged 1 commit into from
Apr 11, 2024
Merged

kind/feat: Surface artifacts through termination message #7714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
243 changes: 243 additions & 0 deletions docs/artifacts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,243 @@
<!--
---
linkTitle: "Artifacts"
weight: 201
---
-->

# Artifacts

- [Overview](#overview)
- [Artifact Provenance Data](#passing-artifacts-between-steps)
- [Passing Artifacts between Steps](#passing-artifacts-between-steps)



## Overview
> :seedling: **`Artifacts` is an [alpha](additional-configs.md#alpha-features) feature.**
> The `enable-artifacts` feature flag must be set to `"true"` to read or write artifacts in a step.

Artifacts provide a way to track the origin of data produced and consumed within your Tekton Tasks.

## Artifact Provenance Data
Artifacts fall into two categories:

- Inputs: Artifacts downloaded and used by the Step/Task.
- Outputs: Artifacts created and uploaded by the Step/Task.
Example Structure:
```json
{
"inputs":[
{
"name": "<input-category-name>",
"values": [
{
"uri": "pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
"digest": { "sha256": "b35caccc..." }
}
]
}
],
"outputs": [
{
"name": "<output-category-name>",
"values": [
{
"uri": "pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
"digest": {
"sha256": "df85b9e3...",
"sha1": "95588b8f..."
}
}
]
}
]
}

```
ericzzzzzzz marked this conversation as resolved.
Show resolved Hide resolved

The content is written by the `Step` to a file `$(step.artifacts.path)`:

```yaml
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
generateName: step-artifacts-
spec:
taskSpec:
description: |
A simple task that populates artifacts to TaskRun stepState
steps:
- name: artifacts-producer
image: bash:latest
script: |
cat > $(step.artifacts.path) << EOF
ericzzzzzzz marked this conversation as resolved.
Show resolved Hide resolved
{
"inputs":[
{
"name":"source",
"values":[
{
"uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
"digest":{
"sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
}
}
]
}
],
"outputs":[
{
"name":"image",
"values":[
{
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
"digest":{
"sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
"sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
}
}
]
}
]
}
EOF
```

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.

### Passing Artifacts between Steps
You can pass artifacts from one step to the next using:

- Specific Artifact: `$(steps.<step-name>.inputs.<artifact-category-name>)` or `$(steps.<step-name>.outputs.<artifact-category-name>)`
- Default (First) Artifact: `$(steps.<step-name>.inputs)` or `$(steps.<step-name>.outputs)` (if <artifact-category-name> is omitted)

The example below shows how to access the previous' step artifacts from another step in the same task

```yaml
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
generateName: step-artifacts-
spec:
taskSpec:
description: |
A simple task that populates artifacts to TaskRun stepState
steps:
- name: artifacts-producer
image: bash:latest
script: |
# the script is for creating the output artifacts
cat > $(step.artifacts.path) << EOF
{
"inputs":[
{
"name":"source",
"values":[
{
"uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
"digest":{
"sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
}
}
]
}
],
"outputs":[
{
"name":"image",
"values":[
{
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
"digest":{
"sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
"sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
}
}
]
}
]
}
EOF
- name: artifacts-consumer
image: bash:latest
script: |
echo $(steps.artifacts-producer.outputs)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear what this will output exactly, perhaps we should include the task output?

```


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,
`$(steps.artifacts-producer.outputs)` is resolved to
```json
[
{
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
"digest":{
"sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
"sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
}
}
]
```


Upon resolution and execution of the `TaskRun`, the `Status` will look something like:
```yaml
"steps": [
{
"container": "step-artifacts-producer",
"imageID": "docker.io/library/bash@sha256:5353512b79d2963e92a2b97d9cb52df72d32f94661aa825fcfa0aede73304743",
"inputs": [
{
"name": "source",
"values": [
{
"digest": {
"sha256": "b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
},
"uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
}
]
}
],
"name": "artifacts-producer",
"outputs": [
{
"name": "image",
"values": [
{
"digest": {
"sha1": "95588b8f34c31eb7d62c92aaa4e6506639b06ef2",
"sha256": "df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48"
},
"uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
}
]
}
],
"terminated": {
"containerID": "containerd://010f02d103d1db48531327a1fe09797c87c1d50b6a216892319b3af93e0f56e7",
"exitCode": 0,
"finishedAt": "2024-03-18T17:05:06Z",
"message": "...",
"reason": "Completed",
"startedAt": "2024-03-18T17:05:06Z"
},
"terminationReason": "Completed"
},
{
"container": "step-artifacts-consumer",
"imageID": "docker.io/library/bash@sha256:5353512b79d2963e92a2b97d9cb52df72d32f94661aa825fcfa0aede73304743",
"name": "artifacts-consumer",
"terminated": {
"containerID": "containerd://42428aa7e5a507eba924239f213d185dd4bc0882b6f217a79e6792f7fec3586e",
"exitCode": 0,
"finishedAt": "2024-03-18T17:05:06Z",
"reason": "Completed",
"startedAt": "2024-03-18T17:05:06Z"
},
"terminationReason": "Completed"
}
],

```
86 changes: 84 additions & 2 deletions docs/pipeline-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1312,7 +1312,7 @@ TaskRunStatus
<h3 id="tekton.dev/v1.Artifact">Artifact
</h3>
<p>
(<em>Appears on:</em><a href="#tekton.dev/v1.StepState">StepState</a>)
(<em>Appears on:</em><a href="#tekton.dev/v1.Artifacts">Artifacts</a>, <a href="#tekton.dev/v1.StepState">StepState</a>)
</p>
<div>
<p>TaskRunStepArtifact represents an artifact produced or used by a step within a task run.
Expand Down Expand Up @@ -1390,6 +1390,47 @@ string
</tr>
</tbody>
</table>
<h3 id="tekton.dev/v1.Artifacts">Artifacts
</h3>
<div>
<p>Artifacts represents the collection of input and output artifacts associated with
a task run or a similar process. Artifacts in this context are units of data or resources
that the process either consumes as input or produces as output.</p>
</div>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>inputs</code><br/>
<em>
<a href="#tekton.dev/v1.Artifact">
[]Artifact
</a>
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>outputs</code><br/>
<em>
<a href="#tekton.dev/v1.Artifact">
[]Artifact
</a>
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
<h3 id="tekton.dev/v1.ChildStatusReference">ChildStatusReference
</h3>
<p>
Expand Down Expand Up @@ -9640,7 +9681,7 @@ TaskRunStatus
<h3 id="tekton.dev/v1beta1.Artifact">Artifact
</h3>
<p>
(<em>Appears on:</em><a href="#tekton.dev/v1beta1.StepState">StepState</a>)
(<em>Appears on:</em><a href="#tekton.dev/v1beta1.Artifacts">Artifacts</a>, <a href="#tekton.dev/v1beta1.StepState">StepState</a>)
</p>
<div>
<p>TaskRunStepArtifact represents an artifact produced or used by a step within a task run.
Expand Down Expand Up @@ -9718,6 +9759,47 @@ string
</tr>
</tbody>
</table>
<h3 id="tekton.dev/v1beta1.Artifacts">Artifacts
</h3>
<div>
<p>Artifacts represents the collection of input and output artifacts associated with
a task run or a similar process. Artifacts in this context are units of data or resources
that the process either consumes as input or produces as output.</p>
</div>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>inputs</code><br/>
<em>
<a href="#tekton.dev/v1beta1.Artifact">
[]Artifact
</a>
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>outputs</code><br/>
<em>
<a href="#tekton.dev/v1beta1.Artifact">
[]Artifact
</a>
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
<h3 id="tekton.dev/v1beta1.ChildStatusReference">ChildStatusReference
</h3>
<p>
Expand Down
Loading