-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
✨ Add go/v4 base and migration guide
Co-authored-by: Varsha <[email protected]>
- Loading branch information
1 parent
89f58d3
commit 8fcc643
Showing
47 changed files
with
3,475 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| # Migration guides from Legacy versions < 3.0.0 | ||
|
|
||
| Following the migration guides from the Legacy Kubebuilder versions up its 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 |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletion
2
docs/book/src/migration/v1vsv2.md → docs/book/src/migration/legacy/v1vsv2.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
86 changes: 86 additions & 0 deletions
86
docs/book/src/migration/manually_migration_guide_gov3_to_gov4.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 began to use 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 what resources are in use, to better 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 scaffold 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 | ||
|
|
138 changes: 138 additions & 0 deletions
138
docs/book/src/migration/migration_guide_gov3_to_gov4.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # V3 - Plugins Layout Migration Guides | ||
|
|
||
| Following the migration guides from the plugins versions. Note that the plugins ecosystem | ||
| was introduced with Kubebuilder v3.0.0 release where the go/v3 version is the default layout | ||
| since `28 Apr 2021`. | ||
|
|
||
| Therefore, you can check here how to migrate the projects built from Kubebuilder 3.x with | ||
| the plugin go/v3 to the latest. | ||
|
|
||
|
|
||
|
|
Oops, something went wrong.