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

Document that Task Results dont get trimmed #2942

Merged
merged 1 commit into from Jul 15, 2020
Merged

Document that Task Results dont get trimmed #2942

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
23 changes: 18 additions & 5 deletions docs/tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ A `Task` declaration includes the following elements:
- [Resources](#specifying-resources)
- [Steps](#defining-steps)
- [Workspaces](#specifying-workspaces)
- [Results](#storing-execution-results)
- [Results](#emitting-results)

## Configuring a `Task`

Expand All @@ -71,7 +71,7 @@ A `Task` definition supports the following fields:
- [`inputs`](#specifying-resources) - Specifies the resources ingested by the `Task`.
- [`outputs`](#specifying-resources) - Specifies the resources produced by the `Task`.
- [`workspaces`](#specifying-workspaces) - Specifies paths to volumes required by the `Task`.
- [`results`](#emitting-results) - Specifies the file to which the `Tasks` writes its execution results.
- [`results`](#emitting-results) - Specifies the names under which `Tasks` write execution results.
- [`volumes`](#specifying-volumes) - Specifies one or more volumes that will be available available to the `Steps` in the `Task`.
- [`stepTemplate`](#specifying-a-step-template) - Specifies a `Container` step definition to use as the basis for all `Steps` in the `Task`.
- [`sidecars`](#specifying-sidecars) - Specifies `Sidecar` containers to run alongside the `Steps` in the `Task`.
Expand Down Expand Up @@ -387,9 +387,22 @@ and the [`Workspaces` in a `TaskRun`](../examples/v1beta1/taskruns/workspace.yam

### Emitting results
Copy link
Member

@pritidesai pritidesai Jul 14, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

/lgtm

one more section on Consuming Results might be helpful as well, emphasizing that the consumer task ends up having dependency on the emitting results task and executed after the dependencies are executed successfully.

(if not documented anywhere 🙏 and could be separate PR)

Copy link
Author

Choose a reason for hiding this comment

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

There are a couple of places where it looks like we describe how results appear:

  • The TaskRun doc describes a bit about their appearance in the Status section of the resource.
  • The Pipeline doc describes a bit about referencing results between tasks and mentions the task ordering.

I think that Pipeline doc could use a bit of work to make it a tad clearer. I also notice that the link from there to this doc's results section is broken. I'll make a PR for that. Good call, thanks @pritidesai !


Use the `results` field to specify one or more files in which the `Task` stores its execution results. These files are
stored in the `/tekton/results` directory. This directory is created automatically at execution time if at least one file
is specified in the `results` field. To specify a file, provide its `name` and `description`.
A Task is able to emit string results that can be viewed by users and passed to other Tasks in a Pipeline. These
results have a wide variety of potential uses. To highlight just a few examples from the Tekton Catalog: the
[`git-clone` Task](https://github.com/tektoncd/catalog/blob/master/task/git-clone/0.1/git-clone.yaml) emits a
cloned commit SHA as a result, the [`generate-build-id` Task](https://github.com/tektoncd/catalog/blob/master/task/generate-build-id/0.1/generate-build-id.yaml)
emits a randomized ID as a result, and the [`kaniko` Task](https://github.com/tektoncd/catalog/tree/master/task/kaniko/0.1)
emits a container image digest as a result. In each case these results convey information for users to see when
looking at their TaskRuns and can also be used in a Pipeline to pass data along from one Task to the next.

To define a `Task's` results, use the `results` field. Each `results` entry in the `Task's` YAML corresponds to a
file that the `Task` should stores the result in. These files should be created by a `Task` in the
`/tekton/results` directory. The directory itself is created automatically if the `Task` has
a `results` field but it's the responsibility of the `Task` to generate its contents.

It's important to note that Tekton does not perform any processing on the contents of results; they are emitted
verbatim from your Task including any leading or trailing whitespace characters. Make sure to write only the
precise string you want returned from your `Task` into the `/tekton/results/` files that your `Task` creates.

In the example below, the `Task` specifies two files in the `results` field:
`current-date-unix-timestamp` and `current-date-human-readable`.
Expand Down