From b33e444b16d25648c58fc3727e01f099d75f5541 Mon Sep 17 00:00:00 2001 From: Jonas Pettersson Date: Wed, 8 Jul 2020 15:18:12 +0200 Subject: [PATCH] Add extended documentation about PersistentVolumes within a PipelineRun There are many things to think about when using PersistentVolumes within a PipelineRun. We have introduced the Affinity Assistant to avoid them. This documentation intend to better describe those problems and configurations so that an end-user can do better choice, e.g. when disabling the Affinity Assistant. /kind documentation --- docs/workspaces.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/workspaces.md b/docs/workspaces.md index 4ebf7c4c301..b722a003879 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -21,6 +21,7 @@ weight: 5 - [Specifying `VolumeSources` in `Workspaces`](#specifying-volumesources-in-workspaces) - [Using `PersistentVolumeClaims` as `VolumeSource`](#using-persistentvolumeclaims-as-volumesource) - [Using other types of `VolumeSources`](#using-other-types-of-volumesources) +- [Using Persistent Volumes within a `PipelineRun`](#using-persistent-volumes-within-a-pipelinerun) - [More examples](#more-examples) ## Overview @@ -364,6 +365,46 @@ workspaces: If you need support for a `VolumeSource` type not listed above, [open an issue](https://github.com/tektoncd/pipeline/issues) or a [pull request](https://github.com/tektoncd/pipeline/blob/master/CONTRIBUTING.md). +## Using Persistent Volumes within a `PipelineRun` + +When using a workspace with a [`PersistentVolumeClaim` as `VolumeSource`](#using-persistentvolumeclaims-as-volumesource), +a Kubernetes [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) is used within the `PipelineRun`. +There are some details that are good to know when using Persistent Volumes within a `PipelineRun`. + +### Storage Class + +`PersistentVolumeClaims` specify a [Storage Class](https://kubernetes.io/docs/concepts/storage/storage-classes/) for the underlying Persistent Volume. Storage Classes have specific +characteristics. If a StorageClassName is not specified for your `PersistentVolumeClaim`, the cluster defined _default_ +Storage Class is used. For _regional_ clusters - clusters that typically consist of Nodes located in multiple Availability +Zones - it is important to know whether your Storage Class is available to all Nodes. Default Storage Classes are typically +only available to Nodes within *one* Availability Zone. There is usually an option to use a _regional_ Storage Class, +but they have trade-offs, e.g. you need to pay for multiple volumes since they are replicated and your volume may have +substantially higher latency. + +When using a workspace backed by a `PersistentVolumeClaim` (typically only available within a Data Center) and the `TaskRun` +pods can be scheduled to any Availability Zone in a regional cluster, some techniques must be used to avoid deadlock in the `Pipeline`. + +Tekton provides an Affinity Assistant that schedules all TaskRun Pods sharing a `PersistentVolumeClaim` to the same +Node. This avoids deadlocks that can happen when two Pods requiring the same Volume are scheduled to different Availability Zones. +A volume typically only lives within a single Availability Zone. + +### Access Modes + +A `PersistentVolumeClaim` specifies an [Access Mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). +Available Access Modes are `ReadWriteOnce`, `ReadWriteMany` and `ReadOnlyMany`. What Access Mode you can use depend on +the storage solution that you are using. + +* `ReadWriteOnce` is the most commonly available Access Mode. A volume with this Access Mode can only be mounted on one + Node at a time. This can be problematic for a `Pipeline` that has parallel `Tasks` that access the volume concurrently. + The Affinity Assistant helps with this problem by scheduling all `Tasks` that use the same `PersistentVolumeClaim` to + the same Node. + +* `ReadOnlyMany` is read-only and is less common in a CI/CD-pipeline. These volumes often need to be "prepared" with data + in some way before use. Dynamically provided volumes can usually not be used in read-only mode. + +* `ReadWriteMany` is the least commonly available Access Mode. If you use this access mode and these volumes are available + to all Nodes within your cluster, you may want to disable the Affinity Assistant. + ## More examples See the following in-depth examples of configuring `Workspaces`: