Skip to content

Commit f7040ce

Browse files
hasanawad94hasanawad94
committed
feat: SHIP-0040 BuildRun Executor field
Explination of the Executor field which was added in shipwright-io/build#1956. Executor field defines the resource responsible for executing a build. Signed-off-by: Hasan Awad <[email protected]>
1 parent 592c922 commit f7040ce

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

‎ships/0043-buildrun-executor-field.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
<!--
2+
Copyright The Shipwright Contributors
3+
4+
SPDX-License-Identifier: Apache-2.0
5+
-->
6+
7+
---
8+
title: buildrun-executor-field
9+
authors:
10+
- "@hasan"
11+
reviewers:
12+
- TBD
13+
approvers:
14+
- TBD
15+
creation-date: 2024-12-19
16+
last-updated: 2024-12-19
17+
status: implemented
18+
see-also:
19+
- "/ships/0023-surface-results-in-buildruns.md"
20+
- "/ships/0024-surfacing-errors-to-buildrun.md"
21+
replaces: []
22+
superseded-by: []
23+
---
24+
25+
# BuildRun Executor Field
26+
27+
This enhancement proposes adding a new `executor` field to the `BuildRunStatus` to track which resource (TaskRun or PipelineRun) is responsible for executing a specific BuildRun.
28+
29+
## Release Signoff Checklist
30+
31+
- [x] Enhancement is `implementable`
32+
- [x] Design details are appropriately documented from clear requirements
33+
- [x] Test plan is defined
34+
- [ ] Graduation criteria for dev preview, tech preview, GA
35+
- [ ] User-facing documentation is created in [docs](/docs/)
36+
37+
## Open Questions
38+
39+
TBD
40+
41+
## Summary
42+
43+
This enhancement adds a new `executor` field to the `BuildRunStatus` that provides visibility into which underlying Tekton resource (TaskRun or PipelineRun) is responsible for executing a BuildRun. This field will contain the name and kind of the executor resource, enabling better debugging, monitoring, and observability of the build execution process.
44+
45+
## Motivation
46+
47+
This enhancement is motivated by the need to support PipelineRun as an alternative execution mode to TaskRun in Shipwright's build logic. As part of refactoring Shipwright to execute builds in Tekton PipelineRuns, cluster admins will be able to switch between the object type Shipwright creates to run builds. This is a necessary prerequisite for fanning out parallel multi-arch builds.
48+
49+
The introduction of PipelineRun support as an "alpha" feature (disabled by default) ensures we don't break existing TaskRun-based behavior while allowing experimentation with the PipelineRun "mode" for operating builds. However, with multiple execution modes available, users and operators need visibility into which specific Tekton resource (TaskRun or PipelineRun) is actually executing their BuildRun to enable proper debugging, monitoring, and troubleshooting.
50+
51+
### Goals
52+
53+
- Provide clear visibility into which Tekton resource (TaskRun or PipelineRun) is executing a BuildRun
54+
- Enable better debugging and troubleshooting capabilities for build execution issues
55+
- Support monitoring and observability tools that need to correlate BuildRun status with underlying Tekton resources
56+
- Maintain backward compatibility with existing BuildRun resources
57+
- Replace the deprecated `TaskRunName` field with a more comprehensive `Executor` field that supports both TaskRun and PipelineRun execution modes
58+
59+
### Non-Goals
60+
61+
- Modifying the core build execution logic
62+
- Changing how BuildRuns are created or managed
63+
- Adding executor information to Build resources (only BuildRun status)
64+
65+
## Proposal
66+
67+
### User Stories
68+
69+
#### Story 1: Introduce Executor field for runner kinds
70+
As a developer, I want a new Executor field to be added to the BuildRunStatus to define the resource responsible for executing a build.
71+
72+
### Implementation Notes
73+
74+
The new `executor` field will be added to the `BuildRunStatus` struct with the following structure:
75+
76+
```go
77+
type BuildRunStatus struct {
78+
// ... existing fields ...
79+
80+
// TaskRunName is the name of the TaskRun responsible for executing this BuildRun.
81+
//
82+
// Deprecated: Use Executor instead to describe the taskrun.
83+
// +optional
84+
TaskRunName *string `json:"taskRunName,omitempty"`
85+
86+
// Executor is the name and kind of the resource responsible for executing this BuildRun.
87+
//
88+
// +optional
89+
Executor *BuildExecutor `json:"executor,omitempty"`
90+
91+
// ... other existing fields ...
92+
}
93+
94+
// BuildExecutor defines the name and kind of the build runner.
95+
type BuildExecutor struct {
96+
// Name is the name of the TaskRun or PipelineRun that was created to execute this BuildRun
97+
Name string `json:"name"`
98+
99+
// Kind is the kind of the object that was created to execute the BuildRun (e.g., "TaskRun", "PipelineRun")
100+
Kind string `json:"kind"`
101+
}
102+
```
103+
104+
The field will be populated by the Shipwright controller when it creates the underlying Tekton resource. The controller will set this field immediately after creating the TaskRun or PipelineRun, ensuring that the executor information is available throughout the build lifecycle. This will be particularly important when the alpha PipelineRun feature is enabled, as users will need to distinguish between the two execution modes.
105+
106+
**Note**: The existing `TaskRunName` field in `BuildRunStatus` is now deprecated in favor of the new `Executor` field, which provides more comprehensive information about the execution resource.
107+
108+
#### Example
109+
110+
Here's an example of how the new `executor` field will appear in a BuildRun status:
111+
112+
```yaml
113+
apiVersion: shipwright.io/v1beta1
114+
kind: BuildRun
115+
metadata:
116+
name: buildah-golang-buildrun
117+
namespace: default
118+
spec:
119+
build:
120+
name: buildah-golang-build
121+
status:
122+
# ... other status fields ...
123+
executor:
124+
name: buildah-golang-buildrun-ml6wg
125+
kind: TaskRun
126+
# ... other status fields ...
127+
```
128+
129+
When viewed with `kubectl describe`, the executor information will be displayed as:
130+
131+
```
132+
Status:
133+
# ... other status fields ...
134+
Executor:
135+
Name: buildah-golang-buildrun-ml6wg
136+
Kind: TaskRun
137+
# ... other status fields ...
138+
```
139+
140+
### Test Plan
141+
142+
- Unit tests for the new Executor field
143+
- Integration tests to verify the executor field is populated correctly for both TaskRun and PipelineRun execution paths (including alpha PipelineRun feature)
144+
- End-to-end tests to ensure the field is available in the BuildRun status throughout the build lifecycle
145+
- Tests to verify backward compatibility with existing BuildRuns that don't have the executor field
146+
147+
### Release Criteria
148+
149+
#### Removing a deprecated feature
150+
Not applicable - this is a new field addition.
151+
152+
#### Upgrade Strategy
153+
This is a purely additive change with no breaking modifications:
154+
- Existing BuildRuns will continue to work without the executor field
155+
- New BuildRuns will have the executor field populated automatically
156+
- No migration is required for existing resources
157+
158+
### Risks and Mitigations
159+
160+
**Risk**: The executor field might become stale if the underlying Tekton resource is deleted.
161+
**Mitigation**: The field should be treated as informational and not relied upon for critical operations. Users should always check the actual Tekton resource status.
162+
163+
**Risk**: Additional API surface area increases complexity.
164+
**Mitigation**: The field is optional and backward compatible, minimizing impact on existing integrations.
165+
166+
**Risk**: Performance impact from additional field updates.
167+
**Mitigation**: The field is set once during resource creation and not updated frequently, minimizing performance impact.
168+
169+
## Drawbacks
170+
171+
- Adds complexity to the BuildRunStatus API
172+
- Creates a dependency on the underlying Tekton resource lifecycle
173+
- May encourage tight coupling between BuildRun and Tekton resource management
174+
175+
## Alternatives
176+
177+
1. **Status Conditions Approach**: Instead of a dedicated field, add the executor information as a status condition. However, this would make the information less discoverable and harder to query.
178+
179+
2. **Annotations Approach**: Store executor information in annotations rather than the status field. This would be less structured and harder to validate.
180+
181+
3. **Separate Resource**: Create a separate resource to track executor relationships. This would add unnecessary complexity and resource overhead.
182+
183+
## Infrastructure Needed
184+
185+
None - this enhancement only requires changes to the existing Shipwright controller and API definitions.
186+
187+
## Implementation History
188+
189+
- Work is done in https://github.com/shipwright-io/build/pull/1956

0 commit comments

Comments
 (0)