Workspace Types

Reference for Tekton workspace types and usage

Workspaces allow Tasks to share data with each other and declare the volumes they need at runtime.

WorkspaceDeclaration

Declares a workspace required by a Task.

name · string · required

Name of the workspace.

Used to reference the workspace in steps and bind it at runtime.

description · string

Human-readable description of how the workspace is used.

mountPath · string

Path where the workspace will be mounted.

Defaults to /workspace/<name> if not specified.

readOnly · boolean · default: false

Whether the workspace is read-only.

If true, the volume is mounted read-only.

optional · boolean · default: false

Whether the workspace is optional.

If true, the Task can run without this workspace being provided.

WorkspaceBinding

Binds a declared workspace to an actual volume at runtime (in TaskRuns/PipelineRuns).

name · string · required

Name of the workspace being bound.

Must match a workspace declared in the Task or Pipeline.

subPath · string

Subdirectory on the volume to use for this binding.

Useful when multiple workspaces share the same volume.

Volume Sources

One of the following volume sources must be specified:

emptyDir · EmptyDirVolumeSource

Temporary directory that shares the Task’s lifetime.

Data is lost when the Task completes.

workspaces:
  - name: scratch
    emptyDir: {}

persistentVolumeClaim · PersistentVolumeClaimVolumeSource

Reference to an existing PersistentVolumeClaim.

workspaces:
  - name: source
    persistentVolumeClaim:
      claimName: my-pvc

Show PersistentVolumeClaimVolumeSource fields

claimName · string · required

Name of the PVC in the same namespace.

volumeClaimTemplate · PersistentVolumeClaim

Template for creating a PVC for each run.

The PVC is automatically created and deleted.

workspaces:
  - name: source
    volumeClaimTemplate:
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 1Gi

configMap · ConfigMapVolumeSource

Populate workspace from a ConfigMap.

workspaces:
  - name: config
    configMap:
      name: my-config

secret · SecretVolumeSource

Populate workspace from a Secret.

workspaces:
  - name: credentials
    secret:
      secretName: my-secret

projected · ProjectedVolumeSource

Combine multiple volume sources into one.

workspaces:
  - name: combined
    projected:
      sources:
        - secret:
            name: secret1
        - configMap:
            name: config1

csi · CSIVolumeSource

Use a CSI (Container Storage Interface) driver.

workspaces:
  - name: csi-volume
    csi:
      driver: secrets-store.csi.k8s.io
      readOnly: true

PipelineWorkspaceDeclaration

Declares a workspace required by a Pipeline.

name · string · required

Name of the workspace.

description · string

Description of how the workspace is used in the Pipeline.

optional · boolean · default: false

Whether the workspace is optional.

WorkspacePipelineTaskBinding

Maps a Pipeline workspace to a Task workspace.

name · string · required

Name of the workspace as declared by the Task.

workspace · string

Name of the workspace declared by the Pipeline.

If omitted, assumes the names match.

subPath · string

Subdirectory within the Pipeline workspace.

Using Workspaces in Steps

Access workspace paths in steps:

steps:
  - name: write-file
    image: bash
    script: |
      echo "Hello" > $(workspaces.source.path)/file.txt
  - name: read-file
    image: bash
    script: |
      cat $(workspaces.source.path)/file.txt

Workspace Isolation

Steps can request exclusive access to workspaces:

steps:
  - name: exclusive-step
    image: bash
    workspaces:
      - name: source
    script: |
      # This step has exclusive access to 'source'
      # Other steps cannot access it simultaneously

Examples

Task with Workspace

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: task-with-workspace
spec:
  workspaces:
    - name: source
      description: The source code to build
      mountPath: /workspace/source
    - name: cache
      description: Build cache
      optional: true
  steps:
    - name: build
      image: golang
      workingDir: $(workspaces.source.path)
      script: |
        go build ./...

TaskRun with emptyDir

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: taskrun-emptydir
spec:
  taskRef:
    name: task-with-workspace
  workspaces:
    - name: source
      emptyDir: {}

TaskRun with PVC

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: taskrun-pvc
spec:
  taskRef:
    name: task-with-workspace
  workspaces:
    - name: source
      persistentVolumeClaim:
        claimName: source-pvc

Pipeline Sharing Workspace

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: build-and-test
spec:
  workspaces:
    - name: shared-data
      description: Workspace shared between tasks
  tasks:
    - name: fetch-source
      taskRef:
        name: git-clone
      workspaces:
        - name: output
          workspace: shared-data
    - name: build
      taskRef:
        name: build-task
      workspaces:
        - name: source
          workspace: shared-data
      runAfter:
        - fetch-source
    - name: test
      taskRef:
        name: test-task
      workspaces:
        - name: source
          workspace: shared-data
      runAfter:
        - build

PipelineRun with VolumeClaimTemplate

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipelinerun-with-pvc
spec:
  pipelineRef:
    name: build-and-test
  workspaces:
    - name: shared-data
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 5Gi
          storageClassName: fast-ssd

Using SubPath

workspaces:
  - name: cache
    persistentVolumeClaim:
      claimName: shared-cache
    subPath: project-a/build-cache

ConfigMap Workspace

workspaces:
  - name: config
    configMap:
      name: app-config
      items:
        - key: config.yaml
          path: config.yaml

Secret Workspace

workspaces:
  - name: ssh-creds
    secret:
      secretName: git-ssh-key
      items:
        - key: ssh-privatekey
          path: id_rsa
          mode: 0600

Best Practices

1. Use descriptive names - Clearly indicate workspace purpose
2. Document workspace usage - Explain what data the workspace contains
3. Use volumeClaimTemplate for pipelines - Automatically provision storage
4. Mark optional workspaces - Allow tasks to run without optional data
5. Use subPath for organization - Share volumes across workspaces
6. Choose appropriate volume types - Match volume type to data persistence needs
7. Set readOnly when appropriate - Prevent accidental modifications
8. Clean up PVCs - Remove volumeClaimTemplate PVCs after use