Proposal: Optional PVC Auto-Cleanup for Workspaces Mode

[vdemeester]

Proposal: Optional PVC Auto-Cleanup for Workspaces Mode

Problem

Users running PipelineRuns with volumeClaimTemplate in stable workspaces mode accumulate PVCs after completion, causing increased storage costs and manual cleanup burden. Alpha modes (pipelineruns, isolate-pipelinerun) auto-delete PVCs, but there's no stable/production-ready option.

Related: #5776 | Code: pkg/reconciler/pipelinerun/affinity_assistant.go:214 (TODO comment)

Proposed Solution

Add opt-in annotation tekton.dev/auto-cleanup-pvc: "true" to enable PVC cleanup on PipelineRun completion.

Example:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-app
  annotations:
    tekton.dev/auto-cleanup-pvc: "true"
spec:
  workspaces:
    - name: source
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteOnce]
          resources:
            requests:
              storage: 1Gi

Behavior:

• With annotation: PVC deleted on completion
• Without annotation: Current behavior (PVC persists until PipelineRun deleted)
• Fully backward compatible

Implementation

Key insight: Cleanup logic already exists in PurgeFinalizerAndDeletePVCForWorkspace() (used by alpha modes). Just need to call it conditionally.

Changes in pkg/reconciler/pipelinerun/affinity_assistant.go:

// Add constant
const AutoCleanupPVCAnnotation = "tekton.dev/auto-cleanup-pvc"

// Modify cleanup (lines 213-222)
case aa.AffinityAssistantPerWorkspace:
    for _, w := range pr.Spec.Workspaces {
        // ... existing StatefulSet deletion ...

        // NEW: Check annotation
        autoCleanup := pr.Annotations != nil && pr.Annotations[AutoCleanupPVCAnnotation] == "true"
        if w.VolumeClaimTemplate != nil && autoCleanup {
            pvcName := volumeclaim.GeneratePVCNameFromWorkspaceBinding(...)
            c.pvcHandler.PurgeFinalizerAndDeletePVCForWorkspace(ctx, pvcName, pr.Namespace)
        }
    }

Complexity: ~20 lines code + ~150 lines tests + docs

Why Annotation?

• ✅ Backward compatible (opt-in)
• ✅ Per-PipelineRun control
• ✅ Reuses existing cleanup logic
• ✅ Standard Kubernetes pattern

Alternative (cluster-wide flag) could be added later if needed.

Questions

1. Is tekton.dev/auto-cleanup-pvc an acceptable annotation name?
2. Should this also work for persistentVolumeClaim workspaces, or only volumeClaimTemplate?
3. Should we include a cluster-wide feature flag in this PR or defer?

References

• Allow PVC of completed PipelineRun to be deleted #5776
• Alpha implementation: TEP-0135: Refactor Affinity Assistant PVC creation #6741, [TEP-0135] Purge finalizer and delete PVC #6940
• TEP-0135: https://github.com/tektoncd/community/blob/main/teps/0135-coscheduling-pipelinerun-pods.md

---

Happy to implement if approach is approved.

cc @tektoncd/maintainers

[aThorp96]

Is there any reason the PVC would not be deleted if it were created from the PVC Template? If not, or if that seems like it would be the edge case, I wonder if it would be good to plan to eventually transition auto-deletion into the default behavior. WDYT?

[sibelius]

auto deletion is good

[jimmyjones2]

LGTM. The only reason I can think of for keeping a PVC created from the PVC template around is for debugging - which seems like an edge case to me - so in the future making auto deletion the default would make sense. A default at the cluster level would be great which can then be overridden per PLR, but this proposal is enough to satisfy my use case.

For persistentVolumeClaim - as it'd be provisioned outside of tekton, I don't think it makes sense to auto delete. For example it could be a long lived PVC used to share artifacts, caches etc between different PLRs.

[jimmyjones2]

If it's using the existing code it might inherit the bug described in #7618 - if a PipelineRun is deleted before finishing, the PVC is not deleted. It would be great if it could be fixed as well 😄