diff --git a/designs/helper_to_upgrade_projects_by_rescaffolding.md b/designs/helper_to_upgrade_projects_by_rescaffolding.md index cef5554d85..7e49bf49d1 100644 --- a/designs/helper_to_upgrade_projects_by_rescaffolding.md +++ b/designs/helper_to_upgrade_projects_by_rescaffolding.md @@ -83,8 +83,6 @@ make less painful this process. Examples: - Deal with customizations or deviations from the proposed layout - Be able to perform the project upgrade to the latest changes without human interactions - Deal and support external plugins -- Provides support to [declarative](https://book.kubebuilder.io/plugins/declarative-v1.html) plugin - since it is desired and planned to decouple this solution and donate this plugin to its own authors [More info](https://github.com/kubernetes-sigs/kubebuilder/issues/3186) - Provide support to older version before having the Project config (Kubebuilder < 3x) and the go/v2 layout which exists to ensure a backwards compatibility with legacy layout provided by Kubebuilder 2x ## Proposal diff --git a/docs/book/src/plugins/creating-plugins.md b/docs/book/src/plugins/creating-plugins.md index 90db70b2ea..3f301a59c2 100644 --- a/docs/book/src/plugins/creating-plugins.md +++ b/docs/book/src/plugins/creating-plugins.md @@ -143,7 +143,7 @@ This is common as you may expect your plugin to: The Kubebuilder internal plugins use boilerplates to generate the files of code. -For instance, the go/v3 scaffolds the `main.go` file by defining an object that [implements the machinery interface][kubebuilder-machinery]. +For instance, the go/v4 scaffolds the `main.go` file by defining an object that [implements the machinery interface][kubebuilder-machinery]. In the [implementation][go-v3-settemplatedefault] of `Template.SetTemplateDefaults`, the [raw template][go-v3-main-template] is set to the body. Such object that implements the machinery interface will later pass to the [execution of scaffold][go-v3-scaffold-execute]. diff --git a/docs/book/src/plugins/extending-cli.md b/docs/book/src/plugins/extending-cli.md index 9589714920..6bf7d5a396 100644 --- a/docs/book/src/plugins/extending-cli.md +++ b/docs/book/src/plugins/extending-cli.md @@ -41,10 +41,10 @@ var ( // GetPluginsCLI returns the plugins based CLI configured to be used in your CLI binary func GetPluginsCLI() (*cli.CLI) { - // Bundle plugin which built the golang projects scaffold by Kubebuilder go/v3 + // Bundle plugin which built the golang projects scaffold by Kubebuilder go/v4 gov3Bundle, _ := plugin.NewBundleWithOptions(plugin.WithName(golang.DefaultNameQualifier), plugin.WithVersion(plugin.Version{Number: 3}), - plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv3.Plugin{}), + plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv4.Plugin{}), ) diff --git a/docs/book/src/plugins/kustomize-v2.md b/docs/book/src/plugins/kustomize-v2.md index f8709eb3df..c33be8057d 100644 --- a/docs/book/src/plugins/kustomize-v2.md +++ b/docs/book/src/plugins/kustomize-v2.md @@ -36,17 +36,17 @@ all that is language specific and kustomize for its configuration, see: ```go import ( ... - kustomizecommonv2alpha "sigs.k8s.io/kubebuilder/v3/pkg/plugins/common/kustomize/v2" + kustomizecommonv2 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/common/kustomize/v2" golangv4 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v4" ... ) - // Bundle plugin which built the golang projects scaffold by Kubebuilder go/v3 + // Bundle plugin which built the golang projects scaffold by Kubebuilder go/v4 // The follow code is creating a new plugin with its name and version via composition // You can define that one plugin is composite by 1 or Many others plugins gov3Bundle, _ := plugin.NewBundle(plugin.WithName(golang.DefaultNameQualifier), plugin.WithVersion(plugin.Version{Number: 3}), - plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv3.Plugin{}), // scaffold the config/ directory and all kustomize files + plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv4.Plugin{}), // scaffold the config/ directory and all kustomize files // Scaffold the Golang files and all that specific for the language e.g. go.mod, apis, controllers ) ``` @@ -68,7 +68,7 @@ drwx------ 6 camilamacedo86 staff 192 31 Mar 09:56 config Or combined with the base language plugins: ```sh -# Provides the same scaffold of go/v3 plugin which is composition but with kustomize/v2 +# Provides the same scaffold of go/v4 plugin which is composition but with kustomize/v2 kubebuilder init --plugins=kustomize/v2,base.go.kubebuilder.io/v4 --domain example.org --repo example.org/guestbook-operator ``` diff --git a/docs/book/src/plugins/testing-plugins.md b/docs/book/src/plugins/testing-plugins.md index 0758146f1e..32e2b1d3fc 100644 --- a/docs/book/src/plugins/testing-plugins.md +++ b/docs/book/src/plugins/testing-plugins.md @@ -42,13 +42,13 @@ For example, Kubebuilder generate [sample projects](https://github.com/kubernete Simply, you can also use `TextContext` to generate folders of scaffolded projects from your plugin. The commands are very similar as mentioned in [creating-plugins](creating-plugins.md#write-e2e-tests). -Following is a general workflow to create a sample by the plugin `go/v3`: (`kbc` is an instance of `TextContext`) +Following is a general workflow to create a sample by the plugin `go/v4`: (`kbc` is an instance of `TextContext`) - To initialized a project: ```go By("initializing a project") err = kbc.Init( - "--plugins", "go/v3", + "--plugins", "go/v4", "--project-version", "3", "--domain", kbc.Domain, "--fetch-deps=false", diff --git a/docs/book/src/plugins/to-be-extended.md b/docs/book/src/plugins/to-be-extended.md index 49326e5fa9..62fa74b4c9 100644 --- a/docs/book/src/plugins/to-be-extended.md +++ b/docs/book/src/plugins/to-be-extended.md @@ -13,12 +13,10 @@ the base language plugins which are responsible for to scaffold the Golang files another languages (i.e. [Operator-SDK][sdk] does to allow users work with Ansible/Helm) or to add helpers on top, such as [Operator-SDK][sdk] does to add their features to integrate the projects with [OLM][olm]. -| Plugin | Key | Description | -| ---------------------------------------------------------------------------------- |-----------------------------| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [kustomize.common.kubebuilder.io/v1](https://github.com/kubernetes-sigs/kubebuilder/pull/3235/kustomize-v1.md) | kustomize/v1 (Deprecated) | Responsible for scaffolding all manifests to configure projects with [kustomize(v3)][kustomize]. (create and update the `config/` directory). This plugin is used in the composition to create the plugin (`go/v3`). | -| [kustomize.common.kubebuilder.io/v2](kustomize-v2.md) | `kustomize/v2` | It has the same purpose of `kustomize/v1`. However, it works with [kustomize][kustomize] version `v4` and addresses the required changes for future kustomize configurations. It will probably be used with the future `go/v4-alpha` plugin. | -| `base.go.kubebuilder.io/v3` | `base/v3` | Responsible for scaffolding all files that specifically require Golang. This plugin is used in composition to create the plugin (`go/v3`) | -| `base.go.kubebuilder.io/v4` | `base/v4` | Responsible for scaffolding all files which specifically requires Golang. This plugin is used in the composition to create the plugin (`go/v4`) | +| Plugin | Key | Description | +| ---------------------------------------------------------------------------------- |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| [kustomize.common.kubebuilder.io/v2](kustomize-v2.md) | `kustomize/v2` | Responsible for scaffolding all [kustomize][kustomize] files under the `config/` directory | +| `base.go.kubebuilder.io/v4` | `base/v4` | Responsible for scaffolding all files which specifically requires Golang. This plugin is used in the composition to create the plugin (`go/v4`) | [create-plugins]: creating-plugins.md [kustomize]: https://kustomize.io/ diff --git a/docs/book/src/reference/envtest.md b/docs/book/src/reference/envtest.md index 00aa545dda..6506f035fa 100644 --- a/docs/book/src/reference/envtest.md +++ b/docs/book/src/reference/envtest.md @@ -322,5 +322,5 @@ testEnv = &envtest.Environment{ [envtest]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest [setup-envtest]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest [cert-manager]: https://book.kubebuilder.io/cronjob-tutorial/cert-manager.html -[sdk-e2e-sample-example]: https://github.com/operator-framework/operator-sdk/tree/master/testdata/go/v3/memcached-operator/test/e2e +[sdk-e2e-sample-example]: https://github.com/operator-framework/operator-sdk/tree/master/testdata/go/v4/memcached-operator/test/e2e [sdk]: https://github.com/operator-framework/operator-sdk diff --git a/docs/book/src/reference/project-config.md b/docs/book/src/reference/project-config.md index 94c2841c1a..5d1aca1c70 100644 --- a/docs/book/src/reference/project-config.md +++ b/docs/book/src/reference/project-config.md @@ -130,28 +130,28 @@ version: "3" Now let's check its layout fields definition: -| Field | Description | -|----------|-------------| -| `layout` | Defines the global plugins, e.g. a project `init` with `--plugins="go/v3,declarative"` means that any sub-command used will always call its implementation for both plugins in a chain. | -| `domain` | Store the domain of the project. This information can be provided by the user when the project is generate with the `init` sub-command and the `domain` flag. | -| `plugins` | Defines the plugins used to do custom scaffolding, e.g. to use the optional `declarative` plugin to do scaffolding for just a specific api via the command `kubebuider create api [options] --plugins=declarative/v1`. | +| Field | Description | +|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `layout` | Defines the global plugins, e.g. a project `init` with `--plugins="go/v4,deploy-image/v1-alpha"` means that any sub-command used will always call its implementation for both plugins in a chain. | +| `domain` | Store the domain of the project. This information can be provided by the user when the project is generate with the `init` sub-command and the `domain` flag. | +| `plugins` | Defines the plugins used to do custom scaffolding, e.g. to use the optional `deploy-image/v1-alpha` plugin to do scaffolding for just a specific api via the command `kubebuider create api [options] --plugins=deploy-image/v1-alpha`. | | `projectName` | The name of the project. This will be used to scaffold the manager data. By default it is the name of the project directory, however, it can be provided by the user in the `init` sub-command via the `--project-name` flag. | -| `repo` | The project repository which is the Golang module, e.g `github.com/example/myproject-operator`. | -| `resources` | An array of all resources which were scaffolded in the project. | -| `resources.api` | The API scaffolded in the project via the sub-command `create api`. | -| `resources.api.crdVersion` | The Kubernetes API version (`apiVersion`) used to do the scaffolding for the CRD resource. | -| `resources.api.namespaced` | The API RBAC permissions which can be namespaced or cluster scoped. | -| `resources.controller` | Indicates whether a controller was scaffolded for the API. | -| `resources.domain` | The domain of the resource which is provided by the `--domain` flag when the sub-command `create api` is used. | -| `resources.group` | The GKV group of the resource which is provided by the `--group` flag when the sub-command `create api` is used. | -| `resources.version` | The GKV version of the resource which is provided by the `--version` flag when the sub-command `create api` is used. | -| `resources.kind` | Store GKV Kind of the resource which is provided by the `--kind` flag when the sub-command `create api` is used. | -| `resources.path` | The import path for the API resource. It will be `/api/` unless the API added to the project is an external or core-type. For the core-types scenarios, the paths used are mapped [here][core-types]. | -| `resources.webhooks`| Store the webhooks data when the sub-command `create webhook` is used. | -| `resources.webhooks.webhookVersion` | The Kubernetes API version (`apiVersion`) used to scaffold the webhook resource. | -| `resources.webhooks.conversion` | It is `true` when the webhook was scaffold with the `--conversion` flag which means that is a conversion webhook. | -| `resources.webhooks.defaulting` | It is `true` when the webhook was scaffold with the `--defaulting` flag which means that is a defaulting webhook. | -| `resources.webhooks.validation` | It is `true` when the webhook was scaffold with the `--programmatic-validation` flag which means that is a validation webhook. | +| `repo` | The project repository which is the Golang module, e.g `github.com/example/myproject-operator`. | +| `resources` | An array of all resources which were scaffolded in the project. | +| `resources.api` | The API scaffolded in the project via the sub-command `create api`. | +| `resources.api.crdVersion` | The Kubernetes API version (`apiVersion`) used to do the scaffolding for the CRD resource. | +| `resources.api.namespaced` | The API RBAC permissions which can be namespaced or cluster scoped. | +| `resources.controller` | Indicates whether a controller was scaffolded for the API. | +| `resources.domain` | The domain of the resource which is provided by the `--domain` flag when the sub-command `create api` is used. | +| `resources.group` | The GKV group of the resource which is provided by the `--group` flag when the sub-command `create api` is used. | +| `resources.version` | The GKV version of the resource which is provided by the `--version` flag when the sub-command `create api` is used. | +| `resources.kind` | Store GKV Kind of the resource which is provided by the `--kind` flag when the sub-command `create api` is used. | +| `resources.path` | The import path for the API resource. It will be `/api/` unless the API added to the project is an external or core-type. For the core-types scenarios, the paths used are mapped [here][core-types]. | +| `resources.webhooks`| Store the webhooks data when the sub-command `create webhook` is used. | +| `resources.webhooks.webhookVersion` | The Kubernetes API version (`apiVersion`) used to scaffold the webhook resource. | +| `resources.webhooks.conversion` | It is `true` when the webhook was scaffold with the `--conversion` flag which means that is a conversion webhook. | +| `resources.webhooks.defaulting` | It is `true` when the webhook was scaffold with the `--defaulting` flag which means that is a defaulting webhook. | +| `resources.webhooks.validation` | It is `true` when the webhook was scaffold with the `--programmatic-validation` flag which means that is a validation webhook. | [project]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v3/PROJECT [versioning]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/VERSIONING.md#Versioning diff --git a/test/e2e/deployimage/plugin_cluster_test.go b/test/e2e/deployimage/plugin_cluster_test.go index c831dae561..03ef702319 100644 --- a/test/e2e/deployimage/plugin_cluster_test.go +++ b/test/e2e/deployimage/plugin_cluster_test.go @@ -75,7 +75,7 @@ var _ = Describe("kubebuilder", func() { It("should generate a runnable project with deploy-image/v1-alpha options ", func() { var err error - By("initializing a project with go/v3") + By("initializing a project with go/v4") err = kbc.Init( "--plugins", "go/v4", "--project-version", "3",