✨ (alpha update) initial code for the alpha update command

[vitorfloriano]

The kubebuilder alpha update command performs a three-way Git merge to upgrade a project to a newer Kubebuilder version while preserving user-defined code. The process is fully automated and follows these main steps:

1. Ancestor Branch (baseline scaffold)

• Created from the specified base branch (default is main)
• Cleans the branch, keeping only .git and PROJECT
• Downloads and uses the old Kubebuilder release to re-scaffold the project
• Commits the result — this branch serves as the synthetic ancestor

2. Original Branch (user’s current code)

• Created from the ancestor branch
• Checks out all files from the user’s base branch (git checkout main -- .)
• Stages and commits the current project state

3. Upgrade Branch (target scaffold)

• Created from the ancestor branch
• Cleaned similarly (preserving only .git and PROJECT)
• Uses the new Kubebuilder release to re-scaffold the project
• Stages and commits the upgraded scaffold

4. Merge Branch (final result)

• Created from the upgrade branch
• Merges in the original branch (user code)
• If conflicts occur:
  • The user is notified and must resolve them manually
• If the merge is clean:
  • The result is committed automatically

This command provides a reliable and repeatable way to upgrade project scaffolding while preserving user customizations. Flags like --from-version, --to-version, and --from-branch offer full control over the versions and branches involved in the update.

Example:

$ kubebuilder alpha update --from-version v4.5.2
WARN No --from-branch specified, using 'main' as default 
INFO Checking if is a git repository              
INFO Checking if branch has uncommitted changes   
INFO Binary version v4.5.2 is available           
INFO Binary version v4.6.0 is available           
INFO Checking out base branch: main               
INFO Using branch names:                          
INFO   Ancestor: tmp-ancestor-29-06-25-20-46      
INFO   Original:  tmp-original-29-06-25-20-46     
INFO   Upgrade:  tmp-upgrade-29-06-25-20-46       
INFO   Merge:    tmp-merge-29-06-25-20-46         
INFO Created and checked out ancestor branch      
INFO Cleaning all files and folders except .git and PROJECT 
INFO Successfully cleanup files in ancestor branch 
INFO Downloading the release v4.5.2 binary from: https://github.com/kubernetes-sigs/kubebuilder/releases/download/v4.5.2/kubebuilder_darwin_arm64 
INFO release binary version v4.5.2 successfully downloaded to /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.5.2-520327151/kubebuilder 
INFO Downloaded binary kept at /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.5.2-520327151 for debugging purposes 
INFO Generating project with version v4.5.2       
WARN Using current working directory to re-scaffold the project 
WARN This directory will be cleaned up and all files removed before the re-generation 
INFO Cleaning directory:/Users/camilam/go/src/github/camilamacedo86/wordpress-operator 
INFO Running cleanup:
$ sh -c rm -rf /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/* 
INFO kubebuilder init:
$ kubebuilder init --plugins go.kubebuilder.io/v4 --domain my.domain --repo github/camilamacedo86/wordpress-operator 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO Get controller runtime:
$ go get sigs.k8s.io/[email protected] 
INFO Update dependencies:
$ go mod tidy           
Next: define a resource with:
$ kubebuilder create api
INFO kubebuilder create api:
$ kubebuilder create api --plural wordpresses --group example.com --version v1 --kind Wordpress --resource --namespaced --controller 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO api/v1/wordpress_types.go                    
INFO api/v1/groupversion_info.go                  
INFO internal/controller/suite_test.go            
INFO internal/controller/wordpress_controller.go  
INFO internal/controller/wordpress_controller_test.go 
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
mkdir -p /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin
Downloading sigs.k8s.io/controller-tools/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests
INFO kubebuilder create webhook:
$ kubebuilder create webhook --plural wordpresses --group example.com --version v1 --kind Wordpress --programmatic-validation --defaulting 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO internal/webhook/v1/wordpress_webhook.go     
INFO internal/webhook/v1/wordpress_webhook_test.go 
INFO internal/webhook/v1/webhook_suite_test.go    
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new Webhook and generate the manifests with:
$ make manifests
INFO Grafana plugin not found, skipping migration 
INFO Deploy-image plugin not found, skipping migration 
INFO Successfully ran alpha generatev4.5.2        
INFO Running make manifests:
$ make manifests     
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
INFO Running make generate:
$ make generate       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
INFO Running make fmt:
$ make fmt                 
go fmt ./...
INFO Running make vet:
$ make vet                 
go vet ./...
INFO Running make lint-fix:
$ make lint-fix       
Downloading github.com/golangci/golangci-lint/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/golangci-lint run --fix
INFO Successfully committed tmp-ancestor-29-06-25-20-46 with clean scaffolding 
INFO Successfully checked out tmp-original-29-06-25-20-46 
INFO Successfully checked out content from main onto tmp-original-29-06-25-20-46 branch 
INFO Successfully staged all changes in current   
INFO Successfully committed changes in tmp-original-29-06-25-20-46 
INFO Successfully checked out tmp-upgrade-29-06-25-20-46 off tmp-ancestor-29-06-25-20-46 
INFO Cleaning all files and folders except .git and PROJECT 
INFO Successfully cleanup files in ancestor branch 
INFO Downloading the release v4.6.0 binary from: https://github.com/kubernetes-sigs/kubebuilder/releases/download/v4.6.0/kubebuilder_darwin_arm64 
INFO release binary version v4.6.0 successfully downloaded to /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.6.0-603848834/kubebuilder 
INFO Downloaded binary kept at /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.6.0-603848834 for debugging purposes 
INFO Generating project with version v4.6.0       
WARN Using current working directory to re-scaffold the project 
WARN This directory will be cleaned up and all files removed before the re-generation 
INFO Cleaning directory:/Users/camilam/go/src/github/camilamacedo86/wordpress-operator 
INFO Running cleanup:
$ sh -c rm -rf /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/* 
INFO kubebuilder init:
$ kubebuilder init --plugins go.kubebuilder.io/v4 --domain my.domain --repo github/camilamacedo86/wordpress-operator 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO Get controller runtime:
$ go get sigs.k8s.io/[email protected] 
INFO Update dependencies:
$ go mod tidy           
Next: define a resource with:
$ kubebuilder create api
INFO kubebuilder create api:
$ kubebuilder create api --plural wordpresses --group example.com --version v1 --kind Wordpress --resource --namespaced --controller 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO api/v1/wordpress_types.go                    
INFO api/v1/groupversion_info.go                  
INFO internal/controller/suite_test.go            
INFO internal/controller/wordpress_controller.go  
INFO internal/controller/wordpress_controller_test.go 
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
mkdir -p /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin
Downloading sigs.k8s.io/controller-tools/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests
INFO kubebuilder create webhook:
$ kubebuilder create webhook --plural wordpresses --group example.com --version v1 --kind Wordpress --programmatic-validation --defaulting 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO internal/webhook/v1/wordpress_webhook.go     
INFO internal/webhook/v1/wordpress_webhook_test.go 
INFO internal/webhook/v1/webhook_suite_test.go    
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new Webhook and generate the manifests with:
$ make manifests
INFO Grafana plugin not found, skipping migration 
INFO Deploy-image plugin not found, skipping migration 
INFO Successfully ran alpha generatev4.6.0        
INFO Running make manifests:
$ make manifests     
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
INFO Running make generate:
$ make generate       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
INFO Running make fmt:
$ make fmt                 
go fmt ./...
INFO Running make vet:
$ make vet                 
go vet ./...
INFO Running make lint-fix:
$ make lint-fix       
Downloading github.com/golangci/golangci-lint/v2/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/golangci-lint run --fix
0 issues.
INFO Successfully staged changes in tmp-upgrade-29-06-25-20-46 
INFO Successfully committed tmp-upgrade-29-06-25-20-46 with clean scaffolding 
INFO Checked out merge branch: tmp-merge-29-06-25-20-46 
INFO Merging in original code (tmp-original-29-06-25-20-46) into merge branch (tmp-merge-29-06-25-20-46) 
INFO Running make manifests:
$ make manifests     
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
INFO Running make generate:
$ make generate       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
INFO Running make fmt:
$ make fmt                 
go fmt ./...
INFO Running make vet:
$ make vet                 
go vet ./...
INFO Running make lint-fix:
$ make lint-fix       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/golangci-lint run --fix
0 issues.

[k8s-ci-robot]

Hi @vitorfloriano. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[camilamacedo86]

/ok-to-test

@vitorfloriano great work 🎉 — very solid progress! Amazing ⭐ 🚀

I’ve added some comments to the PR. Once those are addressed, the next step would be to implement a happy path test to validate the new command — similar to the structure used in:

👉 https://github.com/kubernetes-sigs/kubebuilder/tree/master/test/e2e/alphagenerate

---

How can we do the test:

Following some steps and references to help you out:

• Create a project using Kubebuilder Latest release
  Ref: generate_test.go#L231-L239

• Init a new API within the project
  Ref: generate_test.go#L208-L229

• Use plugin utils to modify the controller
  Instead of changing the whole project, we can inject custom reconcile logic into the controller file. Example from this PR commit:
  camilamacedo86/wordpress-operator@380c8c9

• Call the new alpha update command

• Verify the results:

  • The project should reflect the merged scaffold based on the latest version.
    Ref: generate_test.go#L437-L440
    (no errors were faced)

Please let me know if you’d like to pair or discuss any of this further. Happy to help 😄

[camilamacedo86]

Hi @varshaprasad96 and @Kavinjsir

I’m approving this one to allow us to move forward incrementally.
That said, please feel free to take your time and add your reviews— we can address any feedback in a follow-up.

/lgtm
/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86, vitorfloriano

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

New changes are detected. LGTM label has been removed.

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-32-0

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-33-0