docs for volumes in builds and buildruns

docs/build.md

@@ -16,6 +16,7 @@ SPDX-License-Identifier: Apache-2.0
   - [Defining the Builder or Dockerfile](#defining-the-builder-or-dockerfile)
   - [Defining the Output](#defining-the-output)
   - [Defining Retention Parameters](#defining-retention-parameters)
+  - [Defining Volumes](#defining-volumes)
 - [BuildRun deletion](#BuildRun-deletion)
 
 ## Overview
@@ -571,6 +572,37 @@ An example of a user using both TTL and Limit retention fields. In case of such
 
 **NOTE**: When changes are made to `retention.failedLimit` and `retention.succeededLimit` values, they come into effect as soon as the build is applied, thereby enforcing the new limits. On the other hand, changing the `retention.ttlAfterFailed` and `retention.ttlAfterSucceeded` values will only affect new buildruns. Old buildruns will adhere to the old TTL retention values. In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications.
 
+### Defining Volumes
+
+`Builds` can declare `volumes`. They must override `volumes` defined by the according `BuildStrategy`. If a `volume`
+is not `overridable` then the `BuildRun` will eventually fail.
+
+`Volumes` follow the declaration of [Pod Volumes](https://kubernetes.io/docs/concepts/storage/volumes/), so 
+all the usual `volumeSource` types are supported.
+
+Here is an example of `Build` object that overrides `volumes`:
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: Build
+metadata:
+  name: build-name
+spec:
+  source:
+    url: https://github.com/example/url
+  strategy:
+    name: buildah
+    kind: ClusterBuildStrategy
+  dockerfile: Dockerfile
+  output:
+    image: registry/namespace/image:latest
+  volumes:
+    - name: volume-name
+      volumeSource:
+        configMap:
+          name: test-config
+```
+
 ### Sources
 
 Sources represent remote artifacts, as in external entities added to the build context before the actual Build starts. Therefore, you may employ `.spec.sources` to download artifacts from external repositories.

docs/buildrun.md

@@ -14,6 +14,7 @@ SPDX-License-Identifier: Apache-2.0
   - [Defining ParamValues](#defining-paramvalues)
   - [Defining the ServiceAccount](#defining-the-serviceaccount)
   - [Defining Retention Parameters](#defining-retention-parameters)
+  - [Defining Volumes](#defining-volumes)
 - [Canceling a `BuildRun`](#canceling-a-buildrun)
 - [Automatic `BuildRun` deletion](#automatic-buildrun-deletion)
 - [Specifying Environment Variables](#specifying-environment-variables)
@@ -194,6 +195,34 @@ spec:
 
 **NOTE** In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications.
 
+### Defining Volumes
+
+`BuildRuns` can declare `volumes`. They must override `volumes` defined by the according `BuildStrategy`. If a `volume`
+is not `overridable` then the `BuildRun` will eventually fail.
+
+In case `Build` and `BuildRun` that refers to this `Build` override the same `volume`, one that is defined in the `BuildRun`
+is the one used eventually.
+
+`Volumes` follow the declaration of [Pod Volumes](https://kubernetes.io/docs/concepts/storage/volumes/), so 
+all the usual `volumeSource` types are supported.
+
+Here is an example of `BuildRun` object that overrides `volumes`:
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: BuildRun
+metadata:
+  name: buildrun-name
+spec:
+  buildRef:
+    name: build-name
+  volumes:
+    - name: volume-name
+      volumeSource:
+        configMap:
+          name: test-config
+```
+
 ## Canceling a `BuildRun`
 
 To cancel a `BuildRun` that's currently executing, update its status to mark it as canceled.