Merge pull request #3032 from camilamacedo86/go-v4-base

✨ Add go/v4-alpha base and migration guide from go/v3 to go/v4-alpha

Author: k8s-ci-robot

cmd/main.go

@@ -34,6 +34,7 @@ import (
 	deployimagev1alpha1 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/deploy-image/v1alpha1"
 	golangv2 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v2"
 	golangv3 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v3"
+	golangv4 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v4"
 	grafanav1alpha1 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/optional/grafana/v1alpha"
 )
 
@@ -44,10 +45,10 @@ func main() {
 		kustomizecommonv1.Plugin{},
 		golangv3.Plugin{},
 	)
-	// Bundle plugin which built the golang projects scaffold by Kubebuilder go/v3 with kustomize alpha-v2
+	// Bundle plugin which built the golang projects scaffold by Kubebuilder go/v4 with kustomize alpha-v2
 	gov4Bundle, _ := plugin.NewBundle(golang.DefaultNameQualifier, plugin.Version{Number: 4, Stage: stage.Alpha},
 		kustomizecommonv2alpha.Plugin{},
-		golangv3.Plugin{},
+		golangv4.Plugin{},
 	)
 
 	fs := machinery.Filesystem{
@@ -64,6 +65,7 @@ func main() {
 		cli.WithPlugins(
 			golangv2.Plugin{},
 			golangv3.Plugin{},
+			golangv4.Plugin{},
 			gov3Bundle,
 			gov4Bundle,
 			&kustomizecommonv1.Plugin{},

docs/book/src/SUMMARY.md

@@ -60,15 +60,20 @@
 
 - [Migrations](./migrations.md)
 
-  - [Kubebuilder v1 vs v2](./migration/v1vsv2.md)
+  - [Legacy (before <= v3.0.0)](./migration/legacy.md)
+    - [Kubebuilder v1 vs v2](migration/legacy/v1vsv2.md)
 
-    - [Migration Guide](./migration/legacy/migration_guide_v1tov2.md)
+      - [Migration Guide](./migration/legacy/migration_guide_v1tov2.md)
 
-  - [Kubebuilder v2 vs v3](./migration/v2vsv3.md)
-
-    - [Migration Guide](./migration/migration_guide_v2tov3.md)
-    - [Migration by updating the files](./migration/manually_migration_guide_v2_v3.md)
+    - [Kubebuilder v2 vs v3](migration/legacy/v2vsv3.md)
 
+      - [Migration Guide](migration/legacy/migration_guide_v2tov3.md)
+      - [Migration by updating the files](migration/legacy/manually_migration_guide_v2_v3.md)
+  - [From v3.0.0 with plugins](./migration/v3-plugins.md)
+    - [go/v3 vs go/v4-alpha](migration/v3vsv4.md)
+    
+      - [Migration Guide](migration/migration_guide_gov3_to_gov4.md)
+      - [Migration by updating the files](migration/manually_migration_guide_gov3_to_gov4.md)
   - [Single Group to Multi-Group](./migration/multi-group.md)
 
 ---

docs/book/src/migration/legacy.md

@@ -0,0 +1,18 @@
+# Migration guides from Legacy versions < 3.0.0
+
+Follow the migration guides from the legacy Kubebuilder versions up the required latest v3x version.
+Note that from v3, a new ecosystem using plugins is introduced for better maintainability, reusability and user
+experience .
+
+For more info, see the design docs of:
+
+- [Extensible CLI and Scaffolding Plugins: phase 1][plugins-phase1-design-doc]
+- [Extensible CLI and Scaffolding Plugins: phase 1.5][plugins-phase1-design-doc-1.5]
+- [Extensible CLI and Scaffolding Plugins - Phase 2][plugins-phase2-design-doc]
+
+Also, you can check the [Plugins section][plugins-section].
+
+[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md
+[plugins-phase1-design-doc-1.5]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md
+[plugins-phase2-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md
+[plugins-section]: ./../plugins/plugins.md

docs/book/src/migration/manually_migration_guide_v2_v3.md renamed to docs/book/src/migration/legacy/manually_migration_guide_v2_v3.md

@@ -173,7 +173,7 @@ Change the image name in the Makefile if needed.
 Finally, we can run `make` and `make docker-build` to ensure things are working
 fine.
 
-[v2vsv3]: ./v2vsv3.md
+[v2vsv3]: v2vsv3.md
 [quick-start]: /quick-start.md#installation
 [controller-tools]: https://github.com/kubernetes-sigs/controller-tools/releases
 [controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases

docs/book/src/migration/migration_guide_v2tov3.md renamed to docs/book/src/migration/legacy/migration_guide_v2tov3.md

@@ -1,4 +1,4 @@
-# Kubebuilder v1 vs v2
+# Kubebuilder v1 vs v2 (Legacy v1.0.0+ to v2.0.0 Kubebuilder CLI versions)
 
 This document cover all breaking changes when migrating from v1 to v2.
 

docs/book/src/migration/v1vsv2.md renamed to docs/book/src/migration/legacy/v1vsv2.md

@@ -1,4 +1,4 @@
-# Kubebuilder v2 vs v3
+# Kubebuilder v2 vs v3 (Legacy Kubebuilder v2.0.0+ layout to 3.0.0+)
 
 This document covers all breaking changes when migrating from v2 to v3.
 
@@ -13,7 +13,9 @@ v3 projects use Go modules and request Go 1.18+. Dep is no longer supported for
 
 ## Kubebuilder
 
-- Preliminary support for plugins was added. For more info see the [Extensible CLI and Scaffolding Plugins: phase 1][plugins-phase1-design-doc] and [Extensible CLI and Scaffolding Plugins: phase 1.5][plugins-phase1-design-doc-1.5] 
+- Preliminary support for plugins was added. For more info see the [Extensible CLI and Scaffolding Plugins: phase 1][plugins-phase1-design-doc],
+  the [Extensible CLI and Scaffolding Plugins: phase 1.5][plugins-phase1-design-doc-1.5] and the [Extensible CLI and Scaffolding Plugins - Phase 2][plugins-phase2-design-doc]
+  design docs. Also, you can check the [Plugins section][plugins-section].
 
 - The `PROJECT` file now has a new layout.  It stores more information about what resources are in use, to better enable plugins to make useful decisions when scaffolding.
 
@@ -89,8 +91,10 @@ You will check that you can still using the previous layout by using the `go/v2`
 
 [plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md
 [plugins-phase1-design-doc-1.5]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md
+[plugins-phase2-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md
+[plugins-section]: ./../../plugins/plugins.md
 [manually-upgrade]: manually_migration_guide_v2_v3.md
-[component-config-tutorial]: ../component-config-tutorial/tutorial.md
+[component-config-tutorial]: ../../component-config-tutorial/tutorial.md
 [issue-1893]: https://github.com/kubernetes-sigs/kubebuilder/issues/1839
 [migration-guide-v2-to-v3]: migration_guide_v2tov3.md
 [healthz-ping]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/healthz#CheckHandler 
@@ -102,5 +106,5 @@ You will check that you can still using the previous layout by using the `go/v2`
 [cert-manager-docs]: https://cert-manager.io/docs/installation/upgrading/
 [kb-releases]: https://github.com/kubernetes-sigs/kubebuilder/releases
 [kube-rbac-proxy]: https://github.com/brancz/kube-rbac-proxy/releases
-[basic-project-doc]: ../cronjob-tutorial/basic-project.md
+[basic-project-doc]: ../../cronjob-tutorial/basic-project.md
 [kustomize]: https://github.com/kubernetes-sigs/kustomize

docs/book/src/migration/v2vsv3.md renamed to docs/book/src/migration/legacy/v2vsv3.md

@@ -0,0 +1,86 @@
+# Migration from go/v3 to go/v4-alpha by updating the files manually
+
+Make sure you understand the [differences between Kubebuilder go/v3 and go/v4-alpha][v3vsv4]
+before continuing.
+
+Please ensure you have followed the [installation guide][quick-start]
+to install the required components.
+
+The following guide describes the manual steps required to upgrade your PROJECT config file to begin using `go/v4-alpha`.
+
+This way is more complex, susceptible to errors, and success cannot be assured. Also, by following these steps you will not get the improvements and bug fixes in the default generated project files.
+
+Usually it is suggested to do it manually if you have customized your project and deviated too much from the proposed scaffold. Before continuing, ensure that you understand the note about [project customizations][project-customizations]. Note that you might need to spend more effort to do this process manually than to organize your project customizations. The proposed layout will keep your project maintainable and upgradable with less effort in the future.
+
+The recommended upgrade approach is to follow the [Migration Guide go/v3 to go/v4-alpha][migration-guide-gov3-to-gov4] instead.
+
+## Migration from project config version "go/v3" to "go/v4"
+
+Update `PROJECT` file layout which stores the information about the resources are use to enable plugins to make useful decisions when scaffolding.
+
+Furthermore, the `PROJECT` file itself is now versioned. The `version` field corresponds to the version of the `PROJECT` file itself, while the `layout` field indicates the scaffolding and the primary plugin version in use.
+
+Update: 
+
+```yaml
+layout:
+- go.kubebuilder.io/v3
+```
+
+With:
+
+```yaml
+layout:
+- go.kubebuilder.io/v4-alpha
+
+```
+
+### Steps to migrate
+
+- Update the `main.go` with the changes which can be found in the samples under testdata for the release tag used. (see for example `testdata/project-v4/main.go`).
+- Update the Makefile with the changes which can be found in the samples under testdata for the release tag used. (see for example `testdata/project-v4/Makefile`)
+- Update the `go.mod` with the changes which can be found in the samples under `testdata` for the release tag used. (see for example `testdata/project-v4/go.mod`). Then, run
+`go mod tidy` to ensure that you get the latest dependencies and your Golang code has no breaking changes.
+- Update the manifest under `config/` directory with all changes performed in the default scaffold done with `go/v4-alpha` plugin. (see for example `testdata/project-v4/config/`) to get all changes in the 
+default scaffolds to be applied on your project
+- Replace the import `admissionv1beta1 "k8s.io/api/admission/v1beta1"` with `admissionv1 "k8s.io/api/admission/v1"` in the webhook test files
+
+<aside class="warning">
+<h1>`config/` directory with changes into the scaffold files</h1>
+
+Note that under the `config/` directory you will find scaffolding changes since using
+`go/v4-alpha` you will ensure that you are no longer using Kustomize v3x.
+
+You can mainly compare the `config/` directory from the samples scaffolded under the `testdata`directory by 
+checking the differences between the `testdata/project-v3/config/` with `testdata/project-v4/config/` which
+are samples created with the same commands with the only difference being versions.
+
+However, note that if you create your project with Kubebuilder CLI 3.0.0, its scaffolds
+might change to accommodate changes up to the latest releases using `go/v3` which are not considered 
+breaking for users and/or are forced by the changes introduced in the dependencies 
+used by the project such as [controller-runtime][controller-runtime] and [controller-tools][controller-tools]. 
+
+</aside>
+
+### Verification
+
+In the steps above, you updated your project manually with the goal of ensuring that it follows
+the changes in the layout introduced with the `go/v4-alpha` plugin that update the scaffolds.
+
+There is no option to verify that you properly updated the `PROJECT` file of your project. 
+The best way to ensure that everything is updated correctly, would be to initialize a project using the `go/v4-alpha` plugin,
+(ie) using `kubebuilder init --domain tutorial.kubebuilder.io plugins=go/v4-alpha` and generating the same API(s),
+controller(s), and webhook(s) in order to compare the generated configuration with the manually changed configuration.
+
+Also, after all updates you would run the following commands:
+
+- `make manifests` (to re-generate the files using the latest version of the contrller-gen after you update the Makefile)
+- `make all` (to ensure that you are able to build and perform all operations)
+
+[v3vsv4]: v3vsv4.md
+[quick-start]: ./../quick-start.md#installation
+[migration-guide-gov3-to-gov4]: migration_guide_gov3_to_gov4.md
+[controller-tools]: https://github.com/kubernetes-sigs/controller-tools/releases
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases
+[multi-group]: multi-group.md
+

docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md

@@ -0,0 +1,138 @@
+# Migration from go/v3 to go/v4-alpha
+
+Make sure you understand the [differences between Kubebuilder go/v3 and go/v4-alpha][v3vsv4]
+before continuing.
+
+Please ensure you have followed the [installation guide][quick-start]
+to install the required components.
+
+The recommended way to migrate a go/v3 project is to create a new go/v4-alpha project and
+copy over the API and the reconciliation code. The conversion will end up with a
+project that looks like a native go/v4-alpha project layout (latest version).
+
+However, in some cases, it's possible to do an in-place upgrade (i.e. reuse the go/v3 project layout, upgrading
+the PROJECT file, and scaffolds manually). For further information see [Migration from go/v3 to go/v4-alpha by updating the files manually][manually-upgrade]
+
+## Initialize a go/v4-alpha Project
+
+<aside class="note">
+<h1>Project name</h1>
+
+For the rest of this document, we are going to use `migration-project` as the project name and `tutorial.kubebuilder.io` as the domain. Please, select and use appropriate values for your case.
+
+</aside>
+
+Create a new directory with the name of your project. Note that
+this name is used in the scaffolds to create the name of your manager Pod and of the Namespace where the Manager is deployed by default.
+
+```bash
+$ mkdir migration-project-name
+$ cd migration-project-name
+```
+
+Now, we need to initialize a go/v4-alpha project.  Before we do that, we'll need
+to initialize a new go module if we're not on the `GOPATH`. While technically this is
+not needed inside `GOPATH`, it is still recommended.
+
+```bash
+go mod init tutorial.kubebuilder.io/migration-project
+```
+
+<aside class="note">
+<h1>The module of your project can found in the `go.mod` file at the root of your project:</h1>
+
+```
+module tutorial.kubebuilder.io/migration-project
+```
+
+</aside>
+
+Now, we can finish initializing the project with kubebuilder.
+
+```bash
+kubebuilder init --domain tutorial.kubebuilder.io plugins=go/v4-alpha
+```
+
+<aside class="note">
+<h1>The domain of your project can be found in the PROJECT file:</h1>
+
+```yaml
+...
+domain: tutorial.kubebuilder.io
+...
+```
+</aside>
+
+## Migrate APIs and Controllers
+
+Next, we'll re-scaffold out the API types and controllers.
+
+<aside class="note">
+<h1>Scaffolding both the API types and controllers</h1>
+
+For this example, we are going to consider that we need to scaffold both the API types and the controllers, but remember that this depends on how you scaffolded them in your original project.
+
+</aside>
+
+```bash
+kubebuilder create api --group batch --version v1 --kind CronJob
+```
+
+### Migrate the APIs
+
+<aside class="note">
+<h1>If you're using multiple groups</h1>
+
+Please run `kubebuilder edit --multigroup=true` to enable multi-group support before migrating the APIs and controllers. Please see [this][multi-group] for more details.
+
+</aside>
+
+Now, let's copy the API definition from `api/v1/<kind>_types.go` in our old project to the new one.
+
+These files have not been modified by the new plugin, so you should be able to replace your freshly scaffolded files by your old one. There may be some cosmetic changes. So you can choose to only copy the types themselves.
+
+### Migrate the Controllers
+
+Now, let's migrate the controller code from `controllers/cronjob_controller.go` in our old project to the new one.
+
+## Migrate the Webhooks
+
+<aside class="note">
+<h1>Skip</h1>
+
+If you don't have any webhooks, you can skip this section.
+
+</aside>
+
+Now let's scaffold the webhooks for our CRD (CronJob). We'll need to run the
+following command with the `--defaulting` and `--programmatic-validation` flags
+(since our test project uses defaulting and validating webhooks):
+
+```bash
+kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation
+```
+
+Now, let's copy the webhook definition from `api/v1/<kind>_webhook.go` from our old project to the new one.
+
+## Others
+
+If there are any manual updates in `main.go` in v3, we need to port the changes to the new `main.go`. We’ll also need to ensure all of needed controller-runtime `schemes` have been registered.
+
+If there are additional manifests added under config directory, port them as well. Please, be aware that
+the new version go/v4-alpha uses Kustomize v4x and no longer Kustomize v3. Therefore, if added customized
+implementations in the config you need to ensure that them can work with Kustomize v4 and/if not
+update/upgrade any breaking change that you might face.
+
+Change the image name in the Makefile if needed.
+
+## Verification
+
+Finally, we can run `make` and `make docker-build` to ensure things are working
+fine.
+
+[v3vsv4]: v3vsv4.md
+[quick-start]: ./../quick-start.md#installation
+[controller-tools]: https://github.com/kubernetes-sigs/controller-tools/releases
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases
+[multi-group]: multi-group.md
+[manually-upgrade]: manually_migration_guide_gov3_to_gov4.md

docs/book/src/migration/migration_guide_gov3_to_gov4.md

@@ -20,6 +20,16 @@ to modify the default project structure to support it.
 
 Let's migrate the [CronJob example][cronjob-tutorial].
 
+<aside class="note warning">
+<h1>Using go/v4-alpha</h1>
+
+If you create your project using go/v4-alpha plugin (you can verify it by looking at the PROJECT file )
+then, all steps are the same but you need to keep in mind that the api and controllers directory
+path is now under the `pkg` directory instead. So, you need ensure that you update the
+paths accordingly.
+
+</aside>
+
 Generally, we use the prefix for the API group as the directory name. We
 can check `api/v1/groupversion_info.go` to find that out:
 
@@ -46,6 +56,8 @@ mkdir controllers/batch
 mv controllers/* controllers/batch/
 ```
 
+
+
 Next, we'll need to update all the references to the old package name. 
 For CronJob, that'll be `main.go` and `controllers/batch/cronjob_controller.go`.