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 of the workspace.Used to reference the workspace in steps and bind it at runtime.
Human-readable description of how the workspace is used.
Path where the workspace will be mounted.Defaults to /workspace/<name> if not specified.
Whether the workspace is read-only.If true, the volume is mounted read-only.
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 of the workspace being bound.Must match a workspace declared in the Task or Pipeline.
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:
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
Name of the PVC in the same namespace.
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
Populate workspace from a ConfigMap.workspaces:
- name: config
configMap:
name: my-config
Populate workspace from a Secret.workspaces:
- name: credentials
secret:
secretName: my-secret
Combine multiple volume sources into one.workspaces:
- name: combined
projected:
sources:
- secret:
name: secret1
- configMap:
name: config1
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.
Description of how the workspace is used in the Pipeline.
Whether the workspace is optional.
WorkspacePipelineTaskBinding
Maps a Pipeline workspace to a Task workspace.
Name of the workspace as declared by the Task.
Name of the workspace declared by the Pipeline.If omitted, assumes the names match.
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
- Use descriptive names - Clearly indicate workspace purpose
- Document workspace usage - Explain what data the workspace contains
- Use volumeClaimTemplate for pipelines - Automatically provision storage
- Mark optional workspaces - Allow tasks to run without optional data
- Use subPath for organization - Share volumes across workspaces
- Choose appropriate volume types - Match volume type to data persistence needs
- Set readOnly when appropriate - Prevent accidental modifications
- Clean up PVCs - Remove volumeClaimTemplate PVCs after use