Skip to content

Commit 278dd59

Browse files
avinalavinal
committed
SHIP-0040: Extending Build Volumes
Signed-off-by: Avinal Kumar <[email protected]>
1 parent 41475da commit 278dd59

File tree

1 file changed

+208
-0
lines changed

1 file changed

+208
-0
lines changed

‎ships/0042-extending-build-volumes-for-build-and-buildruns.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
<!--
2+
Copyright The Shipwright Contributors
3+
4+
SPDX-License-Identifier: Apache-2.0
5+
-->
6+
7+
---
8+
title: extend-build-volumes-to-mount-directly-to-builds-and-buildruns
9+
authors:
10+
- "@avinal"
11+
reviewers:
12+
- TBD
13+
approvers:
14+
- TBD
15+
creation-date: 2025-04-21
16+
last-updated: yyyy-mm-dd
17+
status: provisional
18+
see-also:
19+
- "0022-build-strategy-volumes.md"
20+
replaces:
21+
- "/docs/proposals/that-less-than-great-idea.md"
22+
superseded-by:
23+
- "/docs/proposals/our-past-effort.md"
24+
---
25+
26+
# Extending Build Volumes to mount directly to Builds and Buildruns
27+
## Release Signoff Checklist
28+
29+
- [ ] Enhancement is `implementable`
30+
- [ ] Design details are appropriately documented from clear requirements
31+
- [ ] Test plan is defined
32+
- [ ] Graduation criteria for dev preview, tech preview, GA
33+
- [ ] User-facing documentation is created in [docs](/docs/)
34+
35+
## Open Questions [optional]
36+
37+
38+
## Summary
39+
40+
This proposal aims to enhance Shipwright by allowing users to define additional volumes directly
41+
within Build and BuildRun resources. These volumes can then be mounted into the build containers.
42+
This capability is essential for scenarios requiring access to external resources like self-signed
43+
certificates for Git/image registries or other necessary build artifacts, independent of BuildStrategy
44+
definitions, overcoming a current limitation where all volumes must be pre-defined or overridable via the strategy.
45+
46+
## Motivation
47+
48+
Currently, Shipwright Builds face challenges when needing to utilize resources like self-signed
49+
certificates for interacting with private Git repositories or image registries. While BuildStrategy
50+
resources can define volumes that Build and BuildRun resources can override, there's no mechanism
51+
to introduce entirely new volumes directly at the Build or BuildRun level without them being
52+
pre-declared in the BuildStrategy. These strategy-defined volumes, even when overridden, are typically
53+
scoped to the build steps defined by the strategy.
54+
55+
The original proposal for strategy volumes (SHIP-0022) explicitly listed adding arbitrary volumes to
56+
builds as a non-goal to simplify its initial scope. This proposal addresses that gap.
57+
58+
### Goals
59+
60+
- Allow Build and BuildRun resources to declare their own volumes, in addition to those provided or
61+
overridden from the BuildStrategy.
62+
- Ensure these directly defined volumes are mountable and accessible to all primary containers involved
63+
in executing the build steps throughout the lifecycle of the build's execution Pod.
64+
65+
### Non-Goals
66+
67+
What is out of scope for this proposal? Listing non-goals helps to focus discussion and make
68+
progress.
69+
70+
## Proposal
71+
72+
### User Stories
73+
74+
#### Using self-signed certificates
75+
76+
As a user, I want to use Git repositories or image registries that are secured with self-signed
77+
certificates. These certificates need to be accessible by the build process, potentially across
78+
multiple steps (e.g., source cloning, image push/pull).
79+
80+
#### Volumes indepedndent of Build Strategies
81+
82+
As a user, I want to provide necessary artifacts or configurations (e.g., custom configuration files, pre-downloaded dependencies)
83+
to my builds using standard Kubernetes volumes (ConfigMap, Secret, EmptyDir). I need the flexibility
84+
to do this directly in my Build or BuildRun without requiring the BuildStrategy to pre-define a
85+
corresponding volume for me to override.
86+
87+
### Implementation Notes
88+
89+
The current Build and BuildRun APIs will be extended to support a mountPath field for each volume
90+
entry and to allow volume definitions that are not simply overrides of BuildStrategy volumes.
91+
92+
The spec.volumes array already exists in Build and BuildRun.
93+
94+
```yaml
95+
apiVersion: shipwright.io/v1beta1 # Ensure this is the correct API group
96+
kind: Build
97+
metadata:
98+
# ...
99+
spec:
100+
# ...
101+
volumes:
102+
- name: custom-certs
103+
secret:
104+
secretName: my-ca-certs
105+
mountPath: /etc/ssl/certs/custom-ca.crt # Proposed field for direct mount
106+
# For ConfigMap
107+
- name: config
108+
configMap:
109+
name: my-build-configmap
110+
mountPath: /etc/build/config
111+
# For EmptyDir
112+
- name: shared-workspace
113+
emptyDir: {}
114+
mountPath: /workspace/shared
115+
```
116+
117+
The current implicit requirement that every volume in Build.spec.volumes or BuildRun.spec.volumes
118+
must correspond to a volume name in the BuildStrategy.spec.volumes will be relaxed.
119+
120+
- If a volume name in Build or BuildRun matches a volume name defined in the BuildStrategy, the
121+
existing override logic and validation (e.g., ensuring the type is compatible if specified by the strategy)
122+
will apply. The mountPath for these overridden strategy volumes would still be determined by the
123+
BuildStrategy's step definitions.
124+
- If a volume name in Build or BuildRun is new (i.e., does not match any volume in the BuildStrategy),
125+
it will be treated as a direct volume mount. For these volumes, the mountPath field in the Build/BuildRun
126+
volume definition becomes mandatory.
127+
128+
129+
Directly defined volumes (those with a mountPath) will be added to the Pod template generated for the build.
130+
These volumes will be mounted into all primary containers responsible for executing the build steps
131+
defined by the BuildStrategy, as well as any essential helper containers injected by Shipwright
132+
(e.g., for source checkout, if applicable and technically feasible to receive these mounts).
133+
This ensures wide availability for common use cases like certificates.
134+
135+
If a volume with the same name is defined at multiple levels, the following precedence will apply
136+
for its definition (e.g., which Secret or ConfigMap to use):
137+
138+
- BuildRun.spec.volumes (highest precedence)
139+
- Build.spec.volumes
140+
- BuildStrategy.spec.volumes (lowest precedence, acts as a default or template)
141+
142+
143+
- For new, directly mounted volumes, a mountPath must be specified.
144+
- The name of the volume must be unique within the list of directly defined volumes for a given Build or BuildRun.
145+
- Standard Kubernetes validation for the volume source (e.g., configMap, secret) will apply.
146+
- If a mountPath defined in a Build/BuildRun for a direct volume conflicts with a mountPath used by
147+
a BuildStrategy volume, or another direct volume, this should result in a validation error during
148+
Build/BuildRun admission to prevent ambiguity.
149+
150+
151+
### Test Plan
152+
153+
154+
### Release Criteria
155+
156+
157+
#### Upgrade Strategy [if necessary]
158+
159+
160+
### Risks and Mitigations
161+
162+
What are the risks of this proposal and how do we mitigate? Think broadly. For example, consider
163+
both security and how this will impact the larger Shipwright ecosystem.
164+
165+
How will security be reviewed and by whom? How will UX be reviewed and by whom?
166+
167+
## Drawbacks
168+
169+
- All-Step Mounting: Mounting directly defined volumes to all primary build step containers by
170+
default offers simplicity but lacks granularity. If a volume is only needed in one specific step,
171+
it will still be mounted in others. This could slightly clutter the Pod spec and provide
172+
wider-than-necessary access within the Pod's lifecycle. However, for common use-cases like certificates
173+
or shared workspace, this broad availability is often desired. The alternative, per-step mount
174+
configuration, would significantly increase API complexity.
175+
- Potential for mountPath Overlap: While validation should prevent this, users need to be mindful
176+
of mountPaths used by the underlying build tools within the strategy containers to avoid unintentional behavior.
177+
178+
## Alternatives
179+
180+
- Dedicated Certificate Management Feature:
181+
182+
- Description: Introduce a specific API section within Build/BuildRun solely for providing CA
183+
certificates or other trust bundles, rather than using general-purpose volumes.
184+
- Reason for Not Choosing: While this would address the self-signed certificate use case directly,
185+
it is less flexible. General-purpose volumes can solve a wider range of problems, such as providing
186+
configuration files, tools, or shared workspace artifacts, beyond just certificates. The proposed
187+
solution leverages existing Kubernetes volume concepts which are familiar to users.
188+
189+
- Relying Solely on BuildStrategy Volume Overrides:
190+
191+
- Description: Not implement this feature and require all volumes to be predefined in BuildStrategy
192+
and then overridden in Build/BuildRun.
193+
- Reason for Not Choosing: This lacks flexibility for users who don't control the BuildStrategy
194+
or when a BuildStrategy is designed to be generic. It forces strategy authors to anticipate all
195+
possible volume needs, which is impractical.
196+
197+
## Infrastructure Needed [optional]
198+
199+
Use this section if you need things from the project. Examples include a new subproject, repos
200+
requested, github details, and/or testing infrastructure.
201+
202+
Listing these here allows the community to get the process for these resources started right away.
203+
204+
## Implementation History
205+
206+
Major milestones in the life cycle of a proposal should be tracked in `Implementation History`.
207+
208+

0 commit comments

Comments
 (0)