TaskRuns & Pods

A namespaced object (tekton.dev/v1) that asks for one execution of a Task with concrete params and workspaces.

Tasks are templates; a TaskRun is what actually runs. The TaskRun controller reconciles it into exactly one Pod (per attempt) and writes the result back into its status, so the TaskRun is also the record of what happened.

status.conditions[type=Succeeded], whose status is Unknown while the run is in progress and True or False once it has finished.

Every outcome (success, failure, timeout, cancellation) is the same condition with a different status and reason. Tools such as tkn, the Dashboard and the PipelineRun controller only have to read this one field.

A machine-readable reason on the Succeeded condition (Started, Pending, Running, Succeeded, Failed, TaskRunTimeout, TaskRunCancelled, CouldntGetTask, ExceededNodeResources, ExceededResourceQuota…) plus a human message.

The status says whether the run is done. The reason says why: a timeout and a failing test are both False but need different fixes. Some reasons, like ExceededNodeResources, keep the status Unknown because the run is waiting rather than failed.

The name of the Pod created for the current attempt, normally <taskrun>-pod (or -pod-retryN on retries).

It connects the Tekton view to the Kubernetes view: kubectl describe pod, events, node placement and container logs all hang off this name.

Timestamps set when the controller first starts the TaskRun and when it reaches a final status.

The timeout is measured from startTime. Time spent waiting for a node or pulling images counts too, so a cluster that is short on capacity can time out runs that never got to execute.

Containers Tekton adds before the steps: prepare copies the entrypoint binary into a shared volume, place-scripts writes step scripts to /tekton/scripts, and working-dir-initializer creates workingDirs.

They set up the shared /tekton volumes that let ordinary images behave as ordered steps. While they run, the Pod is Pending and the TaskRun reason is Pending.

One entry per step, copied from that container's state: waiting, running, or terminated with exitCode, plus Tekton's terminationReason.

terminationReason (Completed, Error, Continued, Skipped, TimeoutExceeded) shows how a step ended, which the raw exit code can't: a skipped step and a failed step both exit 1.

A small file each step's entrypoint writes on exit (/tekton/termination) that Kubernetes copies into the container status.

This is how step timing and results get from inside the Pod to the controller without any extra network calls. It is also why results must stay small: the message is capped at about 4 KB per container.

The maximum duration of the TaskRun, defaulting to 60 minutes (default-timeout-minutes in config-defaults). 0 disables it.

When it elapses the controller marks the run False/TaskRunTimeout and deletes the Pod, so nothing hangs forever. Builds that legitimately take longer need an explicit timeout.

How many more times to try a failed run: set as retries on a Pipeline task, which the PipelineRun passes to the TaskRun it creates.

Each attempt is a new Pod. Retries hide flaky infrastructure or tests, but they make a real bug cost retries+1 runs before it is reported.

A list holding the full status (conditions, podName, steps) of each earlier failed attempt.

The top-level status only describes the latest attempt. Without retriesStatus you'd lose the evidence of every failure that a later attempt papered over.

Patching spec.status to TaskRunCancelled (what tkn taskrun cancel does) stops the run.

Cancellation is declarative like everything else: you change the spec and the controller acts. It marks the run False/TaskRunCancelled and deletes the Pod, taking its logs with it unless you store them elsewhere.

An alpha TaskRun option that keeps a failed step's container alive instead of ending the run.

You can kubectl exec into the exact environment that failed, then run debug-continue or debug-fail-continue from /tekton/debug/scripts to let the run go on. This beats guessing from logs.

Each step is a container, so its stdout/stderr are that container's logs. tkn taskrun logs -f follows them step by step.

Logs live with the Pod. Once the Pod is gone (after cancel, timeout or cluster cleanup) they are gone too, unless a log store such as Tekton Results keeps them.

The TaskRun Pod goes through the normal kube-scheduler. If no node has room for its resource requests, the run stays Unknown with reason ExceededNodeResources.

Tekton doesn't queue work itself; the cluster is the queue. Pending time counts against the timeout, so capacity problems can surface as timeouts.

A TaskRun (or PipelineRun) field for Pod-level settings: nodeSelector, tolerations, affinity, securityContext, volumes and more.

It lets the same Task run on special nodes (ARM, GPUs, a dedicated CI pool) without changing the Task. A nodeSelector that only matches tainted nodes, without a toleration, leaves the Pod unschedulable.

A reference to a Task by name in the namespace, or through a resolver (git, bundles, hub, cluster).

It lets many runs share one reviewed definition. The spec is resolved when the run starts and copied into status.taskSpec, so editing the Task later doesn't change runs already in flight. A missing Task fails the run with CouldntGetTask.

The whole Task definition embedded directly in the TaskRun.

Good for one-off or generated runs: nothing to install first and nothing to drift. The cost is no reuse, and nothing a reviewer can approve separately from the run.

The Kubernetes ServiceAccount the TaskRun Pod runs as. It decides which credentials and permissions the steps get.

It is the identity of the build. Its Secrets are what Tekton's credential initialization turns into git and docker config. The Auth chapter covers it in detail.