designs/helper_to_upgrade_projects_by_rescaffolding.md
| Authors | Creation Date | Status | Extra |
|---|---|---|---|
| @camilamacedo86,@Kavinjsir,@varshaprasad96 | Feb, 2023 | Implementable | - |
This proposal aims to provide a new alpha command with a helper which would be able to re-scaffold the project from the scratch based on the PROJECT config.
By running a command like following, users would be able to re-scaffold the whole project from the scratch using the current version of KubeBuilder binary available.
kubebuilder alpha generate [OPTIONS]
Following some examples of the workflows
To update the project with minor changes provided
See that for each KubeBuilder release the plugins versions used to scaffold the projects might have bug fixes and new incremental features added to the templates which will result in changes to the files that are generated by the tool for new projects.
In this case, you previously used the tool to generate the project and now would like to update your project with the latest changes provided for the same plugin version. Therefore, you will need to:
kubebuilder alpha generate--no-backup, then you can compare the local directory with the copy of your project
copied to the path .backup/project-name/ before the re-scaffold is done.To update the project with major changes provided
In this case, you are looking for to migrate the project from, for example,
go/v3 to go/v4. The steps are very similar to the above ones. However,
in this case you need to inform the plugin that you want to use to do the scaffold
from scratch kubebuilder alpha generate --plugins=go/v4.
N/A
Therefore, a new command can be designed to load user configs from the PROJECT config file, and run the corresponding kubebuilder subcommands to generate the project based on the new kubebuilder version. Thus, it makes it easier for the users to migrate their operator projects to the new scaffolding.
A common scenario is to upgrade the project based on the newer Kubebuilder. The recommended (straightforward) steps are:
The proposed command will automate the process at maximum, therefore helping operator authors with minimizing the manual effort.
The main motivation of this proposal is to provide a helper for upgrades and make this process less painful. Examples:
The proposed solution to achieve this goal is to create an alpha command as described in the example section above, see:
kubebuilder alpha generate \
--input-dir=<path where the PROJECT file can be found>
--output-dir=<path where the project should be re-scaffold>
--no-backup
--backup-path=<path-where the current version of the project should be copied as backup>
--plugins=<chain of plugins key that can be used to create the layout with init sub-command>
Where:
PROJECT file does not exist, it will fail..backup/project-name.backup/project-nameNote that the backup created in the current directory must be prefixed with
.. Otherwise the tool will not able to perform the scaffold to create a new project from the scratch.
This command would mainly perform the following operations:
.backup/project-name.backup/project-name should be kept.The command should also provide comprehensive help with examples of the proposed workflows. So that, users
are able to understand how to use it when run --help.
As an Operator author:
As a Kubebuiler maintainer:
Note that in the e2e tests the binary is used to do the scaffolds. Also, very similar to the implementation that exist in the integration test KubeBuilder has a code implementation to re-generate the samples used in the docs and add customizations on top, for further information check the hack/docs.
This subcommand could have a similar implementation that could be used by the tests and this plugin. Note that to run the commands using the binaries we are mainly using the following golang implementation:
cmd := exec.Command(t.BinaryName, Options)
_, err := t.Run(cmd)
Hard to keep the command maintained
A risk to consider is that it would be hard to keep this command maintained because we need to develop specific code operations for each plugin. The mitigation for this problem could be developing a design more generic that could work with all plugins.
However, initially a more generic design implementation does not appear to be achievable and would be considered out of the scope of this proposal (no goal). It should to be considered as a second phase of this implementation.
Therefore, the current achievable mitigation in place is that KubeBuilder's policy of not providing official support of maintaining and distributing many plugins.
All input data is tracked. Also, as described above we have examples of code implementation that uses the binary to scaffold the projects. Therefore, the goal of this project seems very reasonable and achievable. An initial work to try to address this requirement can be checked in this pull request
N/A
The idea of automate the re-scaffold of the project is what motivates us track all input data in to the project config in the past. We also tracked the issue based on discussion that we have to indeed try to add further specific implementations to do operations per major bumps. For example:
To upgrade from go/v3 to go/v4 we know exactly what are the changes in the layout then, we could automate these specific operations as well. However, this first idea is harder yet to be addressed and maintained.
We could use it to do cool future features such as creating a GitHub action which would push-pull requests against the project repositories to help users be updated with, for example, minor changes. By using this command, we might able to git clone the project and to do a new scaffold and then use some git strategy merge to result in a PR to purpose the required changes.
We probably need to store the CLI tool tag release used to do the scaffold to persuade this idea. So that we can know if the project requires updates or not.