Make volumes opt-in

- Make volumes opt-in using container volume mounts.
- Add buildah example

ships/0022-build-strategy-volumes.md

@@ -16,7 +16,7 @@ approvers:
   - "@sbose78"
   - "@SaschaSchwarze0"
 creation-date: 2021-08-18
-last-updated: 2021-10-05
+last-updated: 2021-10-08
 status: implementable
 see-also: []
 replaces: []
@@ -82,12 +82,14 @@ So that I can cache resources like image layers and artifacts for subsequent Bui
 ### Implementation Notes
 
 The `BuildStrategy` API will be enhanced so that volumes can be declared alongside the build strategy steps.
-The volumes will provide fixed mount points that will be used in all steps, along with a default source for the underlying filesystem.
+The volumes will declare a default source for the underlying filesystem.
+Each build step must opt into using the volume as a normal container volume mount.
 Volumes can be marked `optional` indicating that the volume is not needed for a `BuildRun` to execute.
 Volumes can also indicate if the source can be overrode by a `Build` or `BuildRun`.
 
 Both the `Build` and `BuildRun` APIs will be enhanced to allow volumes to be specified.
 The volume name referenced in the `Build` or `BuildRun` must be declared in the build strategy.
+If a `BuildRun` references a volume that does not exist (either directly or in its parent `Build` object), the build should fail.
 
 #### Deprecate Implicit emptyDir Volumes
 
@@ -106,19 +108,23 @@ spec:
   buildSteps:
   - name: build
     image: quay.io/my-org/my-builder:latest
-    ...
+    volumeMounts:
+    - name: build-metadata
+      mountPath: /home/build/metadata
+    - name: image-cache
+      mountPath: /var/lib/containers/cache
   volumes:
   - name: build-metadata
     description: "Build metadata"
-    mountPath: /home/build/metadata # mount path for every build step
+    optional: true
     volumeSource:
+      type: EmptyDir # Type discriminator, this wil let us support new volume sources over time.
       emptyDir: {}
   - name: image-cache
     description: "Container image cache"
-    optional: true
-    mountPath: /var/lib/containers/cache
     volumeSource:
       overridable: true # indicates the volume source can be different in a Build or BuildRun
+      type: EmptyDir
       emptyDir: {}
 ```
 
@@ -133,6 +139,7 @@ spec:
   volumes:
   - name: image-cache
     volumeSource:
+      type: PersistentVolumeClaim # When overriding, the type can be changed
       persistentVolumeClaim:
         name: pvc-image-cache
 ```
@@ -146,6 +153,57 @@ When Shipwright generates the `TaskRun` for the `BuildRun`, volumes are created
 2. If the `Build` or `BuildRun` specify a different volume source than what is declared in the build strategy, the volume source in the pod template is updated accordingly, with the `BuildRun` taking precedence over the `Build`.
 3. If the `BuildRun` attempts to override a volume whose source does not have `overridable: true`, the `BuildRun` should fail.
 
+#### Example - Buildah with Image Cache
+
+In this example, the [buildah](https://buildah.io/) build strategy is updated to declare a volume for its container layer storage - `/var/lib/containers`.
+By default this is an ephemeral `emptyDir`, which means all images in the build need to be pulled for each `BuildRun`.
+
+```yaml
+kind: ClusterBuildStrategy
+apiVersion: shipwright.io/v1alpha1
+metadata:
+  name: buildah
+spec:
+  buildSteps:
+  - name: build
+    image: ...
+    ...
+    volumeMounts:
+    - name: var-lib-containers
+      mountPath: /var/lib/containers
+  ...
+  volumes:
+  - name: var-lib-containers
+    volumeSource:
+      overridable: true
+      type: EmptyDir
+      emtpyDir: {}
+```
+
+A `Build`, on the other hand, can run in a namespace that has a Persistent Volume Claim provisioned for the image layers:
+
+```yaml
+kind: Build
+apiVersion: shipwright.io/v1alpha1
+metadata:
+  name: app-build
+spec:
+  source:
+    url: https://github.com/shipwright-io/build.git
+  strategy:
+    kind: ClusterBuildStrategy
+    name: buildah
+  volumes:
+  - name: var-lib-containers
+    volumeSource:
+      type: PersistentVolumeClaim
+      persistentVolumeClaim:
+        name: shipwright-build-cache
+```
+
+Each `BuildRun` created from this `Build` will then write its image layers to the persistent volume.
+The layers can then be used in subsequent build runs, which can reduce the overall runtime of the build.
+
 ### Test Plan
 
 Testing will ensure that basic scenarios are covered:
@@ -178,10 +236,9 @@ Volumes support adds complexity to the API that may require developers to fully
 We have assumed with other proposals that developers should not be expected to interact fully with `BuildStrategy` objects.
 That said, volumes could be grouped with build strategy parameters as features that an "intermediate" user of Shipwright would interact with.
 
-This current proposal also assumes that every volume would be present in every build step.
-This shares the same drawback as Tekton's workspaces feature.
-Tekton has an [alpha feature](https://tekton.dev/docs/pipelines/workspaces/#isolated-workspaces) which allows workspaces to be isolated to specific task steps.
-In theory we could pursue a similar feature if that proves useful in upstream Tekton.
+This current proposal requires each build step to opt into using the build volume.
+This attempts to overcome the primary drawback of Tekton's workspaces feature, which adds volume mounts to all task steps.
+To undo this, Tekton has an [alpha feature](https://tekton.dev/docs/pipelines/workspaces/#isolated-workspaces) which allows workspaces to be isolated to specific task steps.
 
 ## Alternatives
 
@@ -205,4 +262,4 @@ No new infrastructure.
 ## Implementation History
 
 2021-08-18: Provisional SHIP proposal
-2021-10-05: Updated to implementable
+2021-10-08: Updated to implementable