Skip to content

Commit de211ef

Browse files
camilamacedo86camilamacedo86
committed
Proposal: Automated Kubebuilder Project Update Action
1 parent 5c8befa commit de211ef

File tree

1 file changed

+211
-0
lines changed

1 file changed

+211
-0
lines changed

‎designs/update_action.md

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
| Authors | Creation Date | Status | Extra |
2+
|-----------------|---------------|-------------|-------|
3+
| @camilamacedo86 | 2024-11-07 | Implementable | - |
4+
5+
# Proposal: Automated Kubebuilder Project Update Action
6+
7+
This proposal aims to create a GitHub Action similar to Dependabot for Kubebuilder,
8+
automating the process of regenerating scaffolds and preserving custom code when new
9+
versions of Kubebuilder are released. This solution ensures that projects stay
10+
updated with best practices, bug fixes, and features, ultimately improving
11+
maintainability and adoption by reducing the complexity of manual updates.
12+
13+
## Example
14+
15+
This proposal introduces an automated GitHub Action to handle updates for projects created with Kubebuilder. When a new version of Kubebuilder is released, the Action would detect it, regenerate the project scaffold while preserving customizations, and open a pull request in the repository with the latest updates. For example:
16+
17+
1. A user creates a project with Kubebuilder `v4.4`.
18+
2. When Kubebuilder `v4.5` is released, the Action regenerates the scaffold with `v4.5` in a separate directory.
19+
3. A pull request is created with a merge of the user's customizations from the main branch into the regenerated scaffold,
20+
allowing them to review and merge the updates seamlessly.
21+
22+
## Open Questions
23+
24+
1. How will projects handle breaking changes in Kubebuilder updates?
25+
26+
## Summary
27+
28+
TODO
29+
30+
## Motivation
31+
32+
Keeping projects created with Kubebuilder up-to-date with the latest best practices and features is challenging, especially as projects grow and custom code accumulates. Without automated support, developers often delay updates, leading to outdated configurations and the potential for increased technical debt.
33+
34+
This proposal seeks to:
35+
- Facilitate easy updates of Kubebuilder projects.
36+
- Encourage adherence to best practices.
37+
- Make it simpler for developers to maintain the latest, most secure, and feature-rich versions of their projects.
38+
39+
### Goals
40+
41+
- Automatically detect and apply updates to Kubebuilder scaffolds without overwriting customizations.
42+
- Provide pull requests that simplify the process of updating the users project.
43+
- Help keep the projects updated with the latest changes in the scaffolds
44+
45+
### Non-Goals
46+
47+
- Managing or updating non-Kubebuilder project dependencies.
48+
- Resolving complex customizations that directly conflict with updated scaffolds.
49+
- Automatically merging pull requests without review from project maintainers.
50+
51+
## Proposal
52+
53+
### User Stories
54+
55+
- **As a Kubebuilder maintainer**, I want to ensure that users adhere to Kubebuilder scaffolds and best practices by
56+
helping them keep their projects updated with minimal effort.
57+
This will prevent users from deviating from the recommended structure and practices,
58+
maintaining alignment with the project standards. By simplifying updates,
59+
I can also ensure that users remain engaged and see long-term value in using Kubebuilder,
60+
rather than becoming frustrated with manual maintenance.
61+
- **As a user of Kubebuilder**, I want my project built with Kubebuilder to be kept up-to-date
62+
with the latest scaffold best practices so that I can minimize maintenance work.
63+
- **As a user of Kubebuilder**, I want a reliable way to apply Kubebuilder updates
64+
across multiple repositories, saving time on manual updates.
65+
- **As a user of Kubebuilder**, I want to ensure our codebases adhere to current standards,
66+
improving security and maintainability without requiring excessive manual effort.
67+
68+
### Implementation Details/Notes/Constraints
69+
70+
The GitHub Action would be configured as follows:
71+
72+
1. **Version Tracking**:
73+
- Record the initial Kubebuilder version used in each project (`clientVersion`) within the `PROJECT` file.
74+
- When triggered, check for new releases of Kubebuilder.
75+
76+
2. **Three-Way Merge**:
77+
- Generate the original scaffold from the stored version, `clientVersion`, in the `PROJECT` file.
78+
- Regenerate the scaffold with the latest Kubebuilder version.
79+
- Perform a three-way merge between the stored original scaffold, the customized main branch, and the updated scaffold. This preserves customizations while incorporating updates.
80+
81+
3. **PR Creation**:
82+
- Open a pull request in the repository with the scaffold updates.
83+
- Provide detailed descriptions of changes, including how conflicts were resolved, if applicable.
84+
- Schedule updates weekly or on-demand to minimize disruption.
85+
86+
#### Example Workflow
87+
88+
The following example code illustrates the proposed idea but has not been evaluated.
89+
This is an early, incomplete draft intended to demonstrate the approach and basic concept.
90+
91+
We may want to develop a dedicated command-line tool, such as `kubebuilder alpha update`,
92+
to handle tasks like downloading binaries, merging, and updating the scaffold. In this approach,
93+
the GitHub Action would simply invoke this tool to manage the update process and open the
94+
Pull Request, rather than performing each step directly within the Action itself.
95+
96+
```yaml
97+
98+
name: Update Kubebuilder Scaffold
99+
100+
on:
101+
workflow_dispatch:
102+
schedule:
103+
- cron: '0 0 * * 0' # Run weekly to check for new Kubebuilder versions
104+
105+
jobs:
106+
update-scaffold:
107+
runs-on: ubuntu-latest
108+
109+
steps:
110+
- name: Check out the repository
111+
uses: actions/checkout@v2
112+
with:
113+
fetch-depth: 0 # Ensures the full history is checked out
114+
115+
- name: Set up environment and dependencies
116+
run: |
117+
sudo apt-get update
118+
sudo apt-get install -y jq curl
119+
120+
- name: Read Kubebuilder version from PROJECT file
121+
id: read_version
122+
run: |
123+
export INITIAL_VERSION=$(grep "clientVersion" PROJECT | awk '{print $2}')
124+
echo "::set-output name=initial_version::$INITIAL_VERSION"
125+
126+
- name: Download and install the initial Kubebuilder version
127+
run: |
128+
curl -L https://github.com/kubernetes-sigs/kubebuilder/releases/download/${{ steps.read_version.outputs.initial_version }}/kubebuilder_${{ steps.read_version.outputs.initial_version }}_linux_amd64.tar.gz -o kubebuilder_initial.tar.gz
129+
tar -zxvf kubebuilder_initial.tar.gz
130+
sudo mv kubebuilder /usr/local/kubebuilder_initial
131+
132+
- name: Generate initial scaffold in `scaffold_initial` directory
133+
run: |
134+
mkdir scaffold_initial
135+
cp -r . scaffold_initial/
136+
cd scaffold_initial
137+
/usr/local/kubebuilder_initial/bin/kubebuilder init
138+
cd ..
139+
140+
- name: Check for the latest Kubebuilder release
141+
id: get_latest_version
142+
run: |
143+
export LATEST_VERSION=$(curl -s https://api.github.com/repos/kubernetes-sigs/kubebuilder/releases/latest | jq -r .tag_name)
144+
echo "::set-output name=latest_version::$LATEST_VERSION"
145+
146+
- name: Download and install the latest Kubebuilder version
147+
run: |
148+
curl -L https://github.com/kubernetes-sigs/kubebuilder/releases/download/${{ steps.get_latest_version.outputs.latest_version }}/kubebuilder_${{ steps.get_latest_version.outputs.latest_version }}_linux_amd64.tar.gz -o kubebuilder_latest.tar.gz
149+
tar -zxvf kubebuilder_latest.tar.gz
150+
sudo mv kubebuilder /usr/local/kubebuilder_latest
151+
152+
- name: Generate updated scaffold in `scaffold_updated` directory
153+
run: |
154+
mkdir scaffold_updated
155+
cp -r . scaffold_updated/
156+
cd scaffold_updated
157+
/usr/local/kubebuilder_latest/bin/kubebuilder init
158+
cd ..
159+
160+
- name: Copy current project into `scaffold_current` directory
161+
run: |
162+
mkdir scaffold_current
163+
cp -r . scaffold_current/
164+
165+
- name: Perform three-way merge with scaffolds
166+
run: |
167+
# Create a temporary directory to hold the final merged version
168+
mkdir merged_scaffold
169+
# Run three-way merge using scaffold_initial, scaffold_current, and scaffold_updated
170+
# Adjusting merge strategy and paths to use directories
171+
diff3 -m scaffold_current scaffold_initial scaffold_updated > merged_scaffold/merged_files
172+
173+
- name: Copy merged files back to main directory
174+
run: |
175+
cp -r merged_scaffold/* .
176+
git add .
177+
git commit -m "Three-way merge with Kubebuilder updates and custom code"
178+
179+
- name: Create Pull Request
180+
uses: peter-evans/create-pull-request@v3
181+
with:
182+
commit-message: "Update scaffold to Kubebuilder ${{ steps.get_latest_version.outputs.latest_version }}"
183+
title: "Update scaffold to Kubebuilder ${{ steps.get_latest_version.outputs.latest_version }}"
184+
body: |
185+
This pull request updates the scaffold with the latest Kubebuilder version ${{ steps.get_latest_version.outputs.latest_version }}.
186+
branch: kubebuilder-update-${{ steps.get_latest_version.outputs.latest_version }}
187+
```
188+
189+
### Risks and Mitigations
190+
191+
- **Risk**: Potential conflicts with heavily customized code.
192+
- *Mitigation*: GitHub as other tools provide a preview mode where users can inspect conflicts before the merge is attempted.
193+
194+
### Proof of Concept
195+
196+
NA
197+
198+
## Drawbacks
199+
200+
- **Complexity**: Implementing three-way merges and maintaining compatibility across
201+
multiple Kubebuilder versions can add complexity to the Action.
202+
203+
## Alternatives
204+
205+
- **Manual Update Workflow**: Continue with manual updates where users regenerate
206+
and merge changes independently, though this is time-consuming and error-prone.
207+
- **Use alpha generate command**: Continue with updates partial automated provided
208+
by the alpha generate command.
209+
- **Dependabot Integration**: Leverage Dependabot for dependency updates, though this
210+
doesn’t fully support scaffold updates and could lead to incomplete upgrades.
211+

0 commit comments

Comments
 (0)