Skip to content

Commit cf5dbb3

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #4923 from camilamacedo86/doc-update-command
📖 (doc): Upgrade Migration and Documentation over Alpha Commands
2 parents 5465387 + 3be1249 commit cf5dbb3

File tree

7 files changed

+302
-61
lines changed

7 files changed

+302
-61
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,10 @@
6666
- [Migration by updating the files](migration/manually_migration_guide_gov3_to_gov4.md)
6767
- [Single Group to Multi-Group](./migration/multi-group.md)
6868

69-
- [Project Upgrade Assistant](./reference/rescaffold.md)
69+
- [Alpha Commands](./reference/alpha_commands.md)
70+
71+
- [alpha generate](./reference/commands/alpha_generate.md)
72+
- [alpha update](./reference/commands/alpha_update.md)
7073

7174
---
7275

‎docs/book/src/migrations.md

Lines changed: 75 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,78 @@
11
# Migrations
22

3-
Migrating between project structures in Kubebuilder generally involves
4-
a bit of manual work.
3+
Upgrading your project scaffold to adopt the latest changes in Kubebuilder may involve migrating to a new plugin
4+
version (e.g., `go.kubebuilder.io/v3` → `go.kubebuilder.io/v4`)
5+
or newer CLI toolchain. This process often includes re-scaffolding and
6+
manually merging your custom code.
57

6-
This section details what's required to migrate, between different
7-
versions of Kubebuilder scaffolding, as well as to more complex project
8-
layout structures.
8+
This section details what’s required to migrate, between different versions of Kubebuilder scaffolding,
9+
as well as to more complex project layout structures.
10+
11+
The manual approach can be error-prone. That is why Kubebuilder introduces new alpha commands
12+
that help streamline the migration process.
13+
14+
## Manual Migration
15+
16+
The traditional process involves:
17+
18+
- Re-scaffolding the project using the latest Kubebuilder version or plugins
19+
- Re-adding custom logic manually
20+
- Running project generators:
21+
22+
```bash
23+
make generate
24+
make manifests
25+
```
26+
27+
## Understanding the PROJECT File (Introduced in `v3.0.0`)
28+
29+
All inputs used by Kubebuilder are tracked in the [PROJECT][project-config] file.
30+
If you use the CLI to generate your scaffolds, this file will record the project's configuration and metadata.
31+
32+
<aside class="note warning">
33+
<h1>Project customizations</h1>
34+
35+
After using the CLI to create your project, you are free to customise how you see fit.
36+
Bear in mind, that it is not recommended to deviate from the proposed layout unless you know what you are doing.
37+
38+
For example, you should refrain from moving the scaffolded files, doing so will make it difficult in
39+
upgrading your project in the future. You may also lose the ability to use some of the CLI
40+
features and helpers. For further information on the project layout, see
41+
the doc [What's in a basic project?][basic-project-doc]
42+
43+
</aside>
44+
45+
## Alpha Migration Commands
46+
47+
Kubebuilder provides alpha commands to assist with project upgrades.
48+
49+
<aside class="note warning">
50+
<h1>Automation process will involve deleting all files to regenerate</h1>
51+
Deletes all files except `.git` and `PROJECT`.
52+
</aside>
53+
54+
### `kubebuilder alpha generate`
55+
56+
Re-scaffolds the project using the installed CLI version.
57+
58+
```bash
59+
kubebuilder alpha generate
60+
```
61+
62+
### `kubebuilder alpha update` (available since `v4.7.0`)
63+
64+
Automates the migration by performing a 3-way merge:
65+
66+
- Original scaffold
67+
- Your current customized version
68+
- Latest or specified target scaffold
69+
70+
```bash
71+
kubebuilder alpha update
72+
```
73+
74+
For more details, see the [Alpha Command documentation](./reference/alpha_commands.md).
75+
76+
77+
[project-config]: ./reference/project-config.md
78+
[basic-project-doc]: ./cronjob-tutorial/basic-project.md

‎docs/book/src/plugins/extending/extending_cli_features_and_plugins.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -344,8 +344,8 @@ or [External Plugin][external-plugin] properly uses the
344344
[PROJECT file][project-file-config] to track relevant information.
345345
This ensures that other external tools and plugins can properly
346346
integrate with the project. It also allows tools features to help users
347-
re-scaffold their projects such as the [Project Upgrade Assistant][upgrade-assistant]
348-
provided by Kubebuilder, ensuring the tracked information in the
347+
re-scaffold their projects such as using the [Alpha Commands](./../../reference/alpha_commands.md)
348+
to upgrade the project scaffold to a newer version of Kubebuilder, ensuring the tracked information in the
349349
PROJECT file can be leveraged for various purposes.
350350

351351
For example, plugins can check whether they support the project setup

‎docs/book/src/reference/alpha_commands.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Alpha Commands
2+
3+
Kubebuilder provides experimental **alpha commands** to assist with advanced operations such as
4+
project migration and scaffold regeneration.
5+
6+
These commands are designed to simplify tasks that were previously manual and error-prone
7+
by automating or partially automating the process.
8+
9+
<aside class="note warning">
10+
<h1>Alpha commands are experimental</h1>
11+
12+
Alpha commands are under active development and may change or be removed in future releases.
13+
They make local changes to your project and may delete files during execution.
14+
15+
Always ensure your work is committed or backed up before using them.
16+
</aside>
17+
18+
The following alpha commands are currently available:
19+
20+
- [`alpha generate`](./../reference/commands/alpha_generate.md) — Re-scaffold the project using the installed CLI version
21+
- [`alpha update`](./../reference/commands/alpha_update.md) — Automate the migration process via 3-way merge using scaffold snapshots
22+
23+
For more information, see each command's dedicated documentation.

‎docs/book/src/reference/commands/alpha_generate.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Regenerate your project with (`alpha generate`)
2+
3+
## Overview
4+
5+
The `kubebuilder alpha generate` command re-scaffolds your project using the currently installed
6+
CLI and plugin versions.
7+
8+
It regenerates the full scaffold based on the configuration specified in your [PROJECT][project-config] file.
9+
This allows you to apply the latest layout changes, plugin features, and code generation improvements introduced
10+
in newer Kubebuilder releases.
11+
12+
You may choose to re-scaffold the project in-place (overwriting existing files) or in a separate
13+
directory for diff-based inspection and manual integration.
14+
15+
<aside class="note warning">
16+
<h1>Deletes files during scaffold regeneration</h1>
17+
When executed in-place, this command deletes all files except `.git` and `PROJECT`.
18+
19+
Always back up your project or use version control before running this command.
20+
</aside>
21+
22+
## When to Use It?
23+
24+
You can use `kubebuilder alpha generate` to upgrade your project scaffold when new changes are introduced
25+
in Kubebuilder. This includes updates to plugins (for example, `go.kubebuilder.io/v3` → `go.kubebuilder.io/v4`)
26+
or the CLI releases (for example, 4.3.1 → latest) .
27+
28+
This command is helpful when you want to:
29+
30+
- Update your project to use the latest layout or plugin version
31+
- Regenerate your project scaffold to include recent changes
32+
- Compare the current scaffold with the latest and apply updates manually
33+
- Create a clean scaffold for reviewing or testing changes
34+
35+
Use this command when you want full control of the upgrade process.
36+
It is also useful if your project was created with an older CLI version and does not support `alpha update`.
37+
38+
This approach allows you to compare changes between your current branch and upstream
39+
scaffold updates (e.g., from the main branch), and helps you overlay custom code atop the new scaffold.
40+
41+
<aside class="note tip">
42+
<h1>Looking for a more automated migration?</h1>
43+
44+
If you want to upgrade your project scaffold with less manual work,
45+
try [`kubebuilder alpha update`](./alpha_update.md).
46+
47+
It uses a 3-way merge to keep your code and apply the latest scaffold changes automatically.
48+
Use `alpha generate` if `alpha update` is not available for your project yet
49+
or if you prefer to handle changes manually.
50+
51+
</aside>
52+
53+
## How to Use It?
54+
55+
### Upgrade your current project to CLI version installed (i.e. latest scaffold)
56+
57+
```sh
58+
kubebuilder alpha generate
59+
```
60+
61+
After running this command, your project will be re-scaffolded in place.
62+
You can then compare the local changes with your main branch to see what was updated,
63+
and re-apply your custom code on top as needed.
64+
65+
### Generate Scaffold to a New Directory
66+
67+
Use the `--input-dir` and `--output-dir` flags to specify input and output paths.
68+
69+
```sh
70+
kubebuilder alpha generate \
71+
--input-dir=/path/to/existing/project \
72+
--output-dir=/path/to/new/project
73+
```
74+
75+
After running the command, you can inspect the generated scaffold in the specified output directory.
76+
77+
### Flags
78+
79+
| Flag | Description |
80+
|------------------|-----------------------------------------------------------------------------|
81+
| `--input-dir` | Path to the directory containing the `PROJECT` file. Defaults to CWD. Deletes all files except `.git` and `PROJECT`. |
82+
| `--output-dir` | Directory where the new scaffold will be written. If unset, re-scaffolds in-place. |
83+
| `--plugins` | Plugin keys to use for this generation. |
84+
| `-h, --help` | Show help for this command. |
85+
86+
87+
## Further Resources
88+
89+
- [Video demo on how it works](https://youtu.be/7997RIbx8kw?si=ODYMud5lLycz7osp)
90+
- [Design proposal documentation](../../../../../designs/helper_to_upgrade_projects_by_rescaffolding.md)
91+
92+
[example]: ../../../../../testdata/project-v4-with-plugins/PROJECT
93+
[project-config]: ../../reference/project-config.md

‎docs/book/src/reference/commands/alpha_update.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Update Your Project with (`alpha update`)
2+
3+
## Overview
4+
5+
The `kubebuilder alpha update` command helps you upgrade your project scaffold to a newer Kubebuilder version or plugin layout automatically.
6+
7+
It uses a **3-way merge strategy** to update your project with less manual work.
8+
To achieve that, the command creates the following branches:
9+
10+
- *Ancestor branch*: clean scaffold using the old version
11+
- *Current branch*: your existing project with your custom code
12+
- *Upgrade branch*: scaffold generated using the new version
13+
14+
Then, it creates a **merge branch** that combines everything.
15+
You can review and test this branch before applying the changes.
16+
17+
<aside class="note warning">
18+
<h1>Creates branches and deletes files</h1>
19+
20+
This command creates Git branches starting with `tmp-kb-update-` and deletes files during the process.
21+
Make sure to commit your work before running it.
22+
23+
</aside>
24+
25+
## When to Use It?
26+
27+
Use this command when:
28+
29+
- You want to upgrade your project to a newer Kubebuilder version or plugin layout
30+
- You prefer to automate the migration instead of updating files manually
31+
- You want to review scaffold changes in a separate Git branch
32+
- You want to focus only on fixing merge conflicts instead of re-applying all your code
33+
34+
## How It Works
35+
36+
The command performs the following steps:
37+
38+
1. Downloads the older CLI version (from the `PROJECT` file or `--from-version`)
39+
2. Creates `tmp-kb-update-ancestor` with a clean scaffold using that version
40+
3. Creates `tmp-kb-update-current` and restores your current code on top
41+
4. Creates `tmp-kb-update-upgrade` using the latest scaffold
42+
5. Created `tmp-kb-update-merge` which is a merge of the above branches using the 3-way merge strategy
43+
44+
You can push the `tmp-kb-update-merge` branch to your remote repository,
45+
review the diff, and test the changes before merging into your main branch.
46+
47+
## How to Use It
48+
49+
Run the command from your project directory:
50+
51+
```sh
52+
kubebuilder alpha update
53+
```
54+
55+
If needed, set a specific version or branch:
56+
57+
```sh
58+
kubebuilder alpha update \
59+
--from-version=v4.5.2 \
60+
--to-version=v4.6.0 \
61+
--from-branch=main
62+
```
63+
64+
<aside class="note warning">
65+
<h1>You might need to upgrade your project first</h1>
66+
67+
This command uses `kubebuilder alpha generate` internally.
68+
As a result, the version of the CLI originally used to create your project must support `alpha generate`.
69+
70+
This command has only been tested with projects created using **v4.5.0** or later.
71+
It might not work with projects that were initially created using a Kubebuilder version older than **v4.5.0**.
72+
73+
If your project was created with an older version, run `kubebuilder alpha generate` first to re-scaffold it.
74+
Once updated, you can use `kubebuilder alpha update` for future upgrades.
75+
</aside>
76+
77+
## Flags
78+
79+
| Flag | Description |
80+
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
81+
| `--from-version` | **Required for projects initialized with versions earlier than v4.6.0.** Kubebuilder version your project was created with. If unset, uses the `PROJECT` file. |
82+
| `--to-version` | Version to upgrade to. Defaults to the latest version. |
83+
| `--from-branch` | Git branch that contains your current project code. Defaults to `main`. |
84+
| `-h, --help` | Show help for this command. |
85+
86+
<aside class="note warning">
87+
<h1>Projects generated with </h1>
88+
89+
Projects generated with **Kubebuilder v4.6.0** or later include the `cliVersion` field in the `PROJECT` file.
90+
This field is used by `kubebuilder alpha update` to determine the correct CLI
91+
version for upgrading your project.
92+
93+
</aside>
94+
95+
## Requirements
96+
97+
- A valid [PROJECT][project-config] file at the root of your project
98+
- A clean Git working directory (no uncommitted changes)
99+
- Git must be installed and available
100+
101+
## Further Resources
102+
103+
- [WIP: Design proposal for update automation](https://github.com/kubernetes-sigs/kubebuilder/pull/4302)
104+
105+
[project-config]: ../../reference/project-config.md

‎docs/book/src/reference/rescaffold.md

Lines changed: 0 additions & 53 deletions
This file was deleted.

0 commit comments

Comments
 (0)