diff --git a/VERSIONING.md b/VERSIONING.md
index d26a8552434..8d5e7e2a971 100644
--- a/VERSIONING.md
+++ b/VERSIONING.md
@@ -59,4 +59,4 @@ take care of building and publishing the artifacts.
[envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html
[tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases
[kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases
-[cli-plugins-versioning]:docs/book/src/plugins/extending-cli.md#plugin-versioning
+[cli-plugins-versioning]:docs/book/src/plugins/extending#plugin-versioning
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
index 6bc70fa7c67..3b64b77ac3b 100644
--- a/docs/book/src/SUMMARY.md
+++ b/docs/book/src/SUMMARY.md
@@ -117,18 +117,16 @@
- [Plugins][plugins]
- [Available Plugins](./plugins/available-plugins.md)
- - [To scaffold a project](./plugins/to-scaffold-project.md)
- - [go/v4 (Default init scaffold)](./plugins/go-v4-plugin.md)
- - [To add optional features](./plugins/to-add-optional-features.md)
- - [grafana/v1-alpha](./plugins/grafana-v1-alpha.md)
- - [deploy-image/v1-alpha](./plugins/deploy-image-plugin-v1-alpha.md)
- - [To be extended for others tools](./plugins/to-be-extended.md)
- - [kustomize/v2 (Default init scaffold with go/v4)](./plugins/kustomize-v2.md)
- - [Extending the CLI](./plugins/extending-cli.md)
- - [Creating your own plugins](./plugins/creating-plugins.md)
- - [Testing your own plugins](./plugins/testing-plugins.md)
+ - [go/v4](./plugins/available/go-v4-plugin.md)
+ - [grafana/v1-alpha](./plugins/available/grafana-v1-alpha.md)
+ - [deploy-image/v1-alpha](./plugins/available/deploy-image-plugin-v1-alpha.md)
+ - [kustomize/v2](./plugins/available/kustomize-v2.md)
+ - [Extending](./plugins/extending.md)
+ - [CLI and Plugins](./plugins/extending/extending_cli_features_and_plugins.md)
+ - [External Plugins](./plugins/extending/external-plugins.md)
+ - [E2E Tests](./plugins/extending/testing-plugins.md)
- [Plugins Versioning](./plugins/plugins-versioning.md)
- - [Creating external plugins](./plugins/external-plugins.md)
+
---
diff --git a/docs/book/src/plugins/available-plugins.md b/docs/book/src/plugins/available-plugins.md
index 3f723d05274..b4d819b8a6f 100644
--- a/docs/book/src/plugins/available-plugins.md
+++ b/docs/book/src/plugins/available-plugins.md
@@ -6,10 +6,4 @@ This section describes the plugins supported and shipped in with the Kubebuilder
{{#include to-add-optional-features.md }}
{{#include to-be-extended.md }}
-
-
-Plugins Versioning
-
-**ALPHA** plugins can introduce breaking changes. For further info see [Plugins Versioning](./plugins/plugins-versioning.md).
-
-
\ No newline at end of file
+[plugin-versions]: plugins-versioning.md
\ No newline at end of file
diff --git a/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
new file mode 100644
index 00000000000..94136a654ea
--- /dev/null
+++ b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
@@ -0,0 +1,111 @@
+# Deploy Image Plugin (deploy-image/v1-alpha)
+
+The `deploy-image` plugin allows users to create [controllers][controller-runtime] and custom resources that deploy and manage container images on the cluster, following Kubernetes best practices. It simplifies the complexities of deploying images while allowing users to customize their projects as needed.
+
+By using this plugin, you will get:
+
+- A controller implementation to deploy and manage an Operand (image) on the cluster.
+- Tests to verify the reconciliation logic, using [ENVTEST][envtest].
+- Custom resource samples updated with the necessary specifications.
+- Environment variable support for managing the Operand (image) within the manager.
+
+
+Examples
+
+See the `project-v4-with-plugins` directory under the [testdata][testdata]
+directory in the Kubebuilder project to check an example
+of scaffolding created using this plugin.
+
+The `Memcached` API and its controller was scaffolded
+using the command:
+
+```shell
+kubebuilder create api \
+ --group example.com \
+ --version v1alpha1 \
+ --kind Memcached \
+ --image=memcached:memcached:1.6.26-alpine3.19 \
+ --image-container-command="memcached,--memory-limit=64,-o,modern,-v" \
+ --image-container-port="11211" \
+ --run-as-user="1001" \
+ --plugins="deploy-image/v1-alpha"
+```
+
+The `Busybox` API was created with:
+
+```shell
+kubebuilder create api \
+ --group example.com \
+ --version v1alpha1 \
+ --kind Busybox \
+ --image=busybox:1.36.1 \
+ --plugins="deploy-image/v1-alpha"
+```
+
+
+
+## When to use it?
+
+- This plugin is ideal for users who are just getting started with Kubernetes operators.
+- It helps users deploy and manage an image (Operand) using the [Operator pattern][operator-pattern].
+- If you're looking for a quick and efficient way to set up a custom controller and manage a container image, this plugin is a great choice.
+
+## How to use it?
+
+1. **Initialize your project**:
+ After creating a new project with `kubebuilder init`, you can use this
+ plugin to create APIs. Ensure that you've completed the
+ [quick start][quick-start] guide before proceeding.
+
+2. **Create APIs**:
+ With this plugin, you can [create APIs][create-apis] to specify the image (Operand) you want to deploy on the cluster. You can also optionally specify the command, port, and security context using various flags:
+
+ Example command:
+ ```sh
+ kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,--memory-limit=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha"
+ ```
+
+
+Note on make run:
+
+When running the project locally with `make run`, the Operand image
+provided will be stored as an environment variable in the
+`config/manager/manager.yaml` file.
+
+Ensure you export the environment variable before running the project locally, such as:
+
+```shell
+export MEMCACHED_IMAGE="memcached:1.4.36-alpine"
+```
+
+
+
+## Subcommands
+
+The `deploy-image` plugin includes the following subcommand:
+
+- `create api`: Use this command to scaffold the API and controller code to manage the container image.
+
+## Affected files
+
+When using the `create api` command with this plugin, the following
+files are affected, in addition to the existing Kubebuilder scaffolding:
+
+- `controllers/*_controller_test.go`: Scaffolds tests for the controller.
+- `controllers/*_suite_test.go`: Scaffolds or updates the test suite.
+- `api//*_types.go`: Scaffolds the API specs.
+- `config/samples/*_.yaml`: Scaffolds default values for the custom resource.
+- `main.go`: Updates the file to add the controller setup.
+- `config/manager/manager.yaml`: Updates to include environment variables for storing the image.
+
+## Further Resources:
+
+- Check out this [video][video] to see how it works.
+
+[video]: https://youtu.be/UwPuRjjnMjY
+[operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[testdata]: ./.././../../../../testdata/project-v4-with-plugins
+[envtest]: ./../../reference/envtest.md
+[quick-start]: ./../../quick-start.md
+[create-apis]: ../../cronjob-tutorial/new-api.md
\ No newline at end of file
diff --git a/docs/book/src/plugins/available/go-v4-plugin.md b/docs/book/src/plugins/available/go-v4-plugin.md
new file mode 100644
index 00000000000..6e13a9539cc
--- /dev/null
+++ b/docs/book/src/plugins/available/go-v4-plugin.md
@@ -0,0 +1,53 @@
+# go/v4 (go.kubebuilder.io/v4)
+
+**(Default Scaffold)**
+
+Kubebuilder will scaffold using the `go/v4` plugin only if specified when initializing the project.
+This plugin is a composition of the `kustomize.common.kubebuilder.io/v2` and `base.go.kubebuilder.io/v4` plugins
+using the [Bundle Plugin][bundle]. It scaffolds a project template
+that helps in constructing sets of [controllers][controller-runtime].
+
+By following the [quickstart][quickstart] and creating any project,
+you will be using this plugin by default.
+
+
+Examples
+
+You can check samples using this plugin by looking at the `project-v4-` projects under the [testdata][testdata]
+directory on the root directory of the Kubebuilder project.
+
+
+
+## How to use it ?
+
+To create a new project with the `go/v4` plugin the following command can be used:
+
+```sh
+kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project --plugins=go/v4
+```
+
+## Subcommands supported by the plugin
+
+- Init - `kubebuilder init [OPTIONS]`
+- Edit - `kubebuilder edit [OPTIONS]`
+- Create API - `kubebuilder create api [OPTIONS]`
+- Create Webhook - `kubebuilder create webhook [OPTIONS]`
+
+## Further resources
+
+- To see the composition of plugins, you can check the source code for the Kubebuilder [main.go][plugins-main].
+- Check the code implementation of the [base Golang plugin `base.go.kubebuilder.io/v4`][v4-plugin].
+- Check the code implementation of the [Kustomize/v2 plugin][kustomize-plugin].
+- Check [controller-runtime][controller-runtime] to know more about controllers.
+
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[quickstart]: ./../../quick-start.md
+[testdata]: ./../../../../../testdata
+[plugins-main]: ./../../../../../cmd/main.go
+[kustomize-plugin]: ./../../plugins/avaialable/kustomize-v2.md
+[kustomize]: https://github.com/kubernetes-sigs/kustomize
+[standard-go-project]: https://github.com/golang-standards/project-layout
+[v4-plugin]: ./../../../../../pkg/plugins/golang/v4
+[migration-guide-doc]: ./../../migration/migration_guide_gov3_to_gov4.md
+[project-doc]: ./../../reference/project-config.md
+[bundle]: ./../../../../../pkg/plugin/bundle.go
diff --git a/docs/book/src/plugins/grafana-v1-alpha.md b/docs/book/src/plugins/available/grafana-v1-alpha.md
similarity index 83%
rename from docs/book/src/plugins/grafana-v1-alpha.md
rename to docs/book/src/plugins/available/grafana-v1-alpha.md
index 9f8c277be0b..d086fe17f09 100644
--- a/docs/book/src/plugins/grafana-v1-alpha.md
+++ b/docs/book/src/plugins/available/grafana-v1-alpha.md
@@ -1,17 +1,23 @@
# Grafana Plugin (`grafana/v1-alpha`)
-The Grafana plugin is an optional plugin that can be used to scaffold Grafana Dashboards to allow you to check out the default metrics which are exported by projects using [controller-runtime][controller-runtime].
+The Grafana plugin is an optional plugin that can be used to
+scaffold Grafana Dashboards to allow you to check out the
+default metrics which are exported by projects
+using [controller-runtime][controller-runtime].
Examples
-You can check its default scaffold by looking at the `project-v3-with-metrics` projects under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
+You can check its default scaffold by looking at the `project-v4-with-plugins` projects
+under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
## When to use it ?
-- If you are looking to observe the metrics exported by [controller metrics][controller-metrics] and collected by Prometheus via [Grafana][grafana].
+- If you are looking to observe the metrics
+exported by [controller metrics][controller-metrics] and
+collected by Prometheus via [Grafana][grafana].
## How to use it ?
@@ -21,10 +27,10 @@ You can check its default scaffold by looking at the `project-v3-with-metrics` p
- Access to [Prometheus][prometheus].
- Prometheus should have an endpoint exposed. (For `prometheus-operator`, this is similar as: http://prometheus-k8s.monitoring.svc:9090 )
- The endpoint is ready to/already become the datasource of your Grafana. See [Add a data source](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/)
-- Access to [Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/installation/). Make sure you have:
- - [Dashboard edit permission](https://grafana.com/docs/grafana/next/administration/roles-and-permissions/#dashboard-permissions)
+- Access to [Grafana][grafana-install]. Make sure you have:
+ - [Dashboard edit permission][grafana-permissions]
- Prometheus Data source
- 
+ ![pre][prometheus-data-source]
@@ -204,7 +210,7 @@ This time, the plugin will generate `grafana/custom-metrics/custom-metrics-dashb
See an example of how to visualize your custom metrics:
-
+![output2][show-case]
## Subcommands
@@ -222,22 +228,29 @@ The following scaffolds will be created or updated by this plugin:
## Further resources
-- Check out [video to show how it works](https://youtu.be/-w_JjcV8jXc)
-- Checkout the [video to show how the custom metrics feature works](https://youtu.be/x_0FHta2HXc)
-- Refer to a sample of `servicemonitor` provided by [kustomize plugin][kustomize-plugin]
+- Check out [video to show how it works][video]
+- Checkout the [video to show how the custom metrics feature works][video-custom-metrics]
+- Refer to a sample of `serviceMonitor` provided by [kustomize plugin][kustomize-plugin]
- Check the [plugin implementation][plugin-implementation]
- [Grafana Docs][grafana-docs] of importing JSON file
-- The usage of servicemonitor by [Prometheus Operator][servicemonitor]
+- The usage of serviceMonitor by [Prometheus Operator][servicemonitor]
-[controller-metrics]: https://book.kubebuilder.io/reference/metrics-reference.html
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
[grafana]: https://grafana.com/docs/grafana/next/
[grafana-docs]: https://grafana.com/docs/grafana/latest/dashboards/export-import/#import-dashboard
-[kustomize-plugin]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v3/config/prometheus/monitor.yaml
[kube-prometheus]: https://github.com/prometheus-operator/kube-prometheus
-[plugin-implementation]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/optional/grafana/alphav1
[prometheus]: https://prometheus.io/docs/introduction/overview/
[prom-operator]: https://prometheus-operator.dev/docs/prologue/introduction/
-[reference-metrics-doc]: https://book.kubebuilder.io/reference/metrics.html#exporting-metrics-for-prometheus
[servicemonitor]: https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#related-resources
-[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata
+[grafana-install]: https://grafana.com/docs/grafana/latest/setup-grafana/installation/
+[grafana-permissions]: https://grafana.com/docs/grafana/next/administration/roles-and-permissions/#dashboard-permissions
+[prometheus-data-source]: https://user-images.githubusercontent.com/18136486/176119794-f6d69b0b-93f0-4f9e-a53c-daf9f77dadae.gif
+[video]: https://youtu.be/-w_JjcV8jXc
+[video-custom-metrics]: https://youtu.be/x_0FHta2HXc
+[show-case]: https://user-images.githubusercontent.com/18136486/186933170-d2e0de71-e079-4d1b-906a-99a549d66ebf.gif
+[controller-metrics]: ./../../reference/metrics-reference.md
+[kustomize-plugin]: ./../../../../../testdata/project-v4-with-plugins/config/prometheus/monitor.yaml
+[plugin-implementation]: ./../../../../../pkg/plugins/optional/grafana/
+[reference-metrics-doc]: ./../../reference/metrics.md#exporting-metrics-for-prometheus
+[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/project-v4-with-plugins
+
diff --git a/docs/book/src/plugins/available/kustomize-v2.md b/docs/book/src/plugins/available/kustomize-v2.md
new file mode 100644
index 00000000000..929b96457ed
--- /dev/null
+++ b/docs/book/src/plugins/available/kustomize-v2.md
@@ -0,0 +1,105 @@
+# Kustomize v2
+
+**(Default Scaffold)**
+
+The Kustomize plugin allows you to scaffold all kustomize manifests used
+with the language base plugin `base.go.kubebuilder.io/v4`.
+This plugin is used to generate the manifest under the `config/` directory
+for projects built within the `go/v4` plugin (default scaffold).
+
+Projects like [Operator-sdk][sdk] use the Kubebuilder project as a library
+and provide options for working with other languages such as Ansible and Helm.
+The Kustomize plugin helps them maintain consistent configuration across
+languages. It also simplifies the creation of plugins that perform
+changes on top of the default scaffold, removing the need for manual
+updates across multiple language plugins. This approach allows the
+creation of "helper" plugins that work with different projects
+and languages.
+
+
+Examples
+
+You can check the kustomize content by looking at the `config/` directory provided in the sample `project-v4-*`
+under the [testdata][testdata] directory of the Kubebuilder project.
+
+
+
+## How to use it
+
+If you want your language plugin to use kustomize, use the [Bundle Plugin][bundle] to specify that your language plugin is composed of your language-specific plugin and kustomize for its configuration, as shown:
+
+```go
+import (
+ ...
+ kustomizecommonv2 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/common/kustomize/v2"
+ golangv4 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/v4"
+ ...
+)
+
+// Bundle plugin for Golang projects scaffolded by Kubebuilder go/v4
+gov4Bundle, _ := plugin.NewBundle(plugin.WithName(golang.DefaultNameQualifier),
+ plugin.WithVersion(plugin.Version{Number: 4}),
+ plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv4.Plugin{}), // Scaffold the config/ directory and all kustomize files
+)
+```
+
+You can also use kustomize/v2 alone via:
+
+```sh
+kubebuilder init --plugins=kustomize/v2
+$ ls -la
+total 24
+drwxr-xr-x 6 camilamacedo86 staff 192 31 Mar 09:56 .
+drwxr-xr-x 11 camilamacedo86 staff 352 29 Mar 21:23 ..
+-rw------- 1 camilamacedo86 staff 129 26 Mar 12:01 .dockerignore
+-rw------- 1 camilamacedo86 staff 367 26 Mar 12:01 .gitignore
+-rw------- 1 camilamacedo86 staff 94 31 Mar 09:56 PROJECT
+drwx------ 6 camilamacedo86 staff 192 31 Mar 09:56 config
+```
+
+Or combined with the base language plugins:
+
+```sh
+# 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
+```
+
+## Subcommands
+
+The kustomize plugin implements the following subcommands:
+
+* init (`$ kubebuilder init [OPTIONS]`)
+* create api (`$ kubebuilder create api [OPTIONS]`)
+* create webhook (`$ kubebuilder create api [OPTIONS]`)
+
+
+Create API and Webhook
+
+The implementation for the `create api` subcommand scaffolds the kustomize
+manifests specific to each API. See more [here][kustomize-create-api].
+The same applies to `create webhook`.
+
+
+
+## Affected files
+
+The following scaffolds will be created or updated by this plugin:
+
+* `config/*`
+
+## Further resources
+
+* Check the kustomize [plugin implementation](https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize)
+* Check the [kustomize documentation][kustomize-docs]
+* Check the [kustomize repository][kustomize-github]
+
+[sdk]:https://github.com/operator-framework/operator-sdk
+[kustomize-docs]: https://kustomize.io/
+[kustomize-github]: https://github.com/kubernetes-sigs/kustomize
+[kustomize-replacements]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/replacements/
+[kustomize-vars]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/vars/
+[release-notes-v5]: https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv5.0.0
+[release-notes-v4]: https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv4.0.0
+[testdata]: ./../../../../../testdata/
+[bundle]: ./../../../../../pkg/plugin/bundle.go
+[kustomize-create-api]: ./../../../../../pkg/plugins/common/kustomize/v2/scaffolds/api.go
diff --git a/docs/book/src/plugins/creating-plugins.md b/docs/book/src/plugins/creating-plugins.md
deleted file mode 100644
index 131ece3b321..00000000000
--- a/docs/book/src/plugins/creating-plugins.md
+++ /dev/null
@@ -1,222 +0,0 @@
-# Creating your own plugins
-
-[extending-cli]: extending-cli.md
-[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
-[creating-external-plugins]: external-plugins.md
-[operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator
-[sdk-ansible]: https://sdk.operatorframework.io/docs/building-operators/ansible/
-[sdk-cli-pkg]: https://pkg.go.dev/github.com/operator-framework/operator-sdk/internal/cmd/operator-sdk/cli
-[sdk-helm]: https://sdk.operatorframework.io/docs/building-operators/helm/
-[sdk]: https://github.com/operator-framework/operator-sdk
-
-
-
-Note
-
-Extending Kubebuilder can be accomplished in two primary ways:
-
-`By re-using the existing plugins`: In this approach, you use Kubebuilder as a library.
-
-This enables you to import existing Kubebuilder plugins and extend them, leveraging their features to build upon.
-
-It is particularly useful if you want to add functionalities that are closely tied with the existing Kubebuilder features.
-
-
-`By Creating an External Plugin`: This method allows you to create an independent, standalone plugin as a binary.
-
-The plugin can be written in any language and should implement an execution pattern that Kubebuilder knows how to interact with.
-
-You can see [Creating external plugins][creating-external-plugins] for more info.
-
-
-
-## Overview
-
-You can extend the Kubebuilder API to create your own plugins. If [extending the CLI][extending-cli], your plugin will be implemented in your project and registered to the CLI as has been done by the [SDK][sdk] project. See its [CLI code][sdk-cli-pkg] as an example.
-
-## When it is useful?
-
-- If you are looking to create plugins which support and work with another language.
-- If you would like to create helpers and integrations on top of the scaffolds done by the plugins provided by Kubebuiler.
-- If you would like to have customized layouts according to your needs.
-
-## How the plugins can be used?
-
-Kubebuilder provides a set of plugins to scaffold the projects, to help you extend and re-use its implementation to provide additional features.
-For further information see [Available Plugins][available-plugins].
-
-Therefore, if you have a need you might want to propose a solution by adding a new plugin
-which would be shipped with Kubebuilder by default.
-
-However, you might also want to have your own tool to address your specific scenarios and by taking advantage of what is provided by Kubebuilder as a library.
-That way, you can focus on addressing your needs and keep your solutions easier to maintain.
-
-Note that by using Kubebuilder as a library, you can import its plugins and then create your own plugins that do customizations on top.
-For instance, `Operator-SDK` does with the plugins [manifest][operator-sdk-manifest] and [scorecard][operator-sdk-scorecard] to add its features.
-Also see [here][operator-sdk-plugin-ref].
-
-Another option implemented with the [Extensible CLI and Scaffolding Plugins - Phase 2][plugins-phase2-design-doc] is
-to extend Kibebuilder as a LIB to create only a specific plugin that can be called and used with
-Kubebuilder as well.
-
-
- Plugins proposal docs
-
-You can check the proposal documentation for better understanding its motivations. 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].
-
-
-
-## Language-based Plugins
-
-Kubebuilder offers the Golang-based operator plugins, which will help its CLI tool users create projects following the [Operator Pattern][operator-pattern].
-
-The [SDK][sdk] project, for example, has language plugins for [Ansible][sdk-ansible] and [Helm][sdk-helm], which are similar options but for users who would like to work with these respective languages and stacks instead of Golang.
-
-Note that Kubebuilder provides the `kustomize.common.kubebuilder.io` to help in these efforts. This plugin will scaffold the common base without any specific language scaffold file to allow you to extend the Kubebuilder style for your plugins.
-
-In this way, currently, you can [Extend the CLI][extending-cli] and use the `Bundle Plugin` to create your language plugins such as:
-
-```go
- mylanguagev1Bundle, _ := plugin.NewBundle(plugin.WithName(language.DefaultNameQualifier),
- plugin.WithVersion(plugin.Version{Number: 1}),
- plugin.WithPlugins(kustomizecommonv1.Plugin{}, mylanguagev1.Plugin{}), // extend the common base from Kubebuilder
- // your plugin language which will do the scaffolds for the specific language on top of the common base
- )
-```
-
-If you do not want to develop your plugin using Golang, you can follow its standard by using the binary as follows:
-
-```sh
-kubebuilder init --plugins=kustomize
-```
-
-Then you can, for example, create your implementations for the sub-commands `create api` and `create webhook` using your language of preference.
-
-
-Why use the Kubebuilder style?
-
-Kubebuilder and SDK are both broadly adopted projects which leverage the [controller-runtime][controller-runtime] project. They both allow users to build solutions using the [Operator Pattern][operator-pattern] and follow common standards.
-
-Adopting these standards can bring significant benefits, such as joining forces on maintaining the common standards as the features provided by Kubebuilder and take advantage of the contributions made by the community. This allows you to focus on the specific needs and requirements for your plugin and use-case.
-
-And then, you will also be able to use custom plugins and options currently or in the future which might to be provided by these projects as any other which decides to persuade the same standards.
-
-
-
-## Custom Plugins
-
-Note that users are also able to use plugins to customize their scaffolds and address specific needs.
-
-See that Kubebuilder provides the [`deploy-image`][deploy-image] plugin that allows the user to create the controller & CRs which will deploy and manage an image on the cluster:
-
-```sh
-kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,--memory-limit=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha"
-```
-
-This plugin will perform a custom scaffold following the [Operator Pattern][operator-pattern].
-
-Another example is the [`grafana`][grafana] plugin that scaffolds a new folder container manifests to visualize operator status on Grafana Web UI:
-
-```sh
-kubebuilder edit --plugins="grafana.kubebuilder.io/v1-alpha"
-```
-
-In this way, by [Extending the Kubebuilder CLI][extending-cli], you can also create custom plugins such this one.
-
-Feel free to check the implementation under:
-
-- deploy-image:
-- grafana:
-
-## Plugin Scaffolding
-
-Your plugin may add code on top of what is scaffolded by default with Kubebuilder sub-commands(`init`, `create`, ...).
-This is common as you may expect your plugin to:
-
-- Create API
-- Update controller manager logic
-- Generate corresponding manifests
-
-### Boilerplates
-
-The Kubebuilder internal plugins use boilerplates to generate the files of code.
-
-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].
-
-Similar, you may also design your code of plugin implementation by such reference.
-You can also view the other parts of the code file given by the links above.
-
-If your plugin is expected to modify part of the existing files with its scaffold, you may use functions provided by [sigs.k8s.io/kubebuilder/v4/pkg/plugin/util][kb-util].
-See [example of deploy-image][example-of-deploy-image-2].
-In brief, the util package helps you customize your scaffold in a lower level.
-
-### Use Kubebuilder Machinery Lib
-
-Notice that Kubebuilder also provides [machinery pkg][kubebuilder-machinery-pkg] where you can:
-
-- Define file I/O behavior.
-- Add markers to the scaffolded file.
-- Define the template for scaffolding.
-
-#### Overwrite A File
-
-You might want for example to overwrite a scaffold done by using the option:
-
-```go
- f.IfExistsAction = machinery.OverwriteFile
-```
-
-Let's imagine that you would like to have a helper plugin that would be called in a chain with `go/v4` to add customizations on top.
-Therefore after we generate the code calling the subcommand to `init` from `go/v4` we would like to overwrite the Makefile to change this scaffold via our plugin.
-In this way, we would implement the Bollerplate for our Makefile and then use this option to ensure that it would be overwritten.
-
-See [example of deploy-image][example-of-deploy-image-1].
-
-### A Combination of Multiple Plugins
-
-Since your plugin may work frequently with other plugins, the executing command for scaffolding may become cumbersome, e.g:
-
-```shell
-kubebuilder create api --plugins=go/v3,kustomize/v1,yourplugin/v1
-```
-
-You can probably define a method to your scaffolder that calls the plugin scaffolding method in order.
-See [example of deploy-image][example-of-deploy-image-3].
-
-#### Define Plugin Bundles
-
-Alternatively, you can create a plugin bundle to include the target plugins. For instance:
-
-```go
- mylanguagev1Bundle, _ := plugin.NewBundle(plugin.WithName(language.DefaultNameQualifier),
- plugin.WithVersion(plugin.Version{Number: 1}),
- plugin.WithPlugins(kustomizecommonv1.Plugin{}, mylanguagev1.Plugin{}), // extend the common base from Kuebebuilder
- // your plugin language which will do the scaffolds for the specific language on top of the common base
- )
-```
-
-[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
-[deploy-image]: https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/golang/deploy-image/v1alpha1
-[grafana]: https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/optional/grafana/v1alpha
-[extending-cli]: ./extending-cli.md
-[kb-util]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin/util
-[example-of-deploy-image-1]: https://github.com/kubernetes-sigs/kubebuilder/blob/df1ed6ccf19df40bd929157a91eaae6a9215bfc6/pkg/plugins/golang/deploy-image/v1alpha1/scaffolds/internal/templates/api/types.go#L58
-[example-of-deploy-image-2]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/deploy-image/v1alpha1/scaffolds/api.go#L170-L266
-[example-of-deploy-image-3]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/deploy-image/v1alpha1/scaffolds/api.go#L77-L98
-[available-plugins]: ./available-plugins.md
-[operator-sdk-manifest]: https://github.com/operator-framework/operator-sdk/tree/v1.23.0/internal/plugins/manifests/v2
-[operator-sdk-scorecard]: https://github.com/operator-framework/operator-sdk/tree/v1.23.0/internal/plugins/scorecard/v2
-[operator-sdk-plugin-ref]: https://github.com/operator-framework/operator-sdk/blob/v1.23.0/internal/cmd/operator-sdk/cli/cli.go#L78-L160
-[plugins-section]: ???
-[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/designs/extensible-cli-and-scaffolding-plugins-phase-1.md#extensible-cli-and-scaffolding-plugins
-[plugins-phase1-design-doc-1.5]: https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md#extensible-cli-and-scaffolding-plugins---phase-15
-[plugins-phase2-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/designs/extensible-cli-and-scaffolding-plugins-phase-2.md#extensible-cli-and-scaffolding-plugins---phase-2
-[go-v3-main-template]: https://github.com/kubernetes-sigs/kubebuilder/blob/3bfc84ec8767fa760d1771ce7a0cb05a9a8f6286/pkg/plugins/golang/v3/scaffolds/internal/templates/main.go#L183
-[kubebuilder-machinery]: https://github.com/kubernetes-sigs/kubebuilder/blob/3bfc84ec8767fa760d1771ce7a0cb05a9a8f6286/pkg/plugins/golang/v3/scaffolds/internal/templates/main.go#L28
-[go-v3-settemplatedefault]: https://github.com/kubernetes-sigs/kubebuilder/blob/3bfc84ec8767fa760d1771ce7a0cb05a9a8f6286/pkg/plugins/golang/v3/scaffolds/internal/templates/main.go#L40
-[go-v3-scaffold-execute]: https://github.com/kubernetes-sigs/kubebuilder/blob/3bfc84ec8767fa760d1771ce7a0cb05a9a8f6286/pkg/plugins/golang/v3/scaffolds/init.go#L120
-[kubebuilder-machinery-pkg]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/machinery#section-documentation
diff --git a/docs/book/src/plugins/deploy-image-plugin-v1-alpha.md b/docs/book/src/plugins/deploy-image-plugin-v1-alpha.md
deleted file mode 100644
index 6cc993feb5f..00000000000
--- a/docs/book/src/plugins/deploy-image-plugin-v1-alpha.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Deploy Image Plugin (deploy-image/v1-alpha)
-
-The deploy-image plugin allows users to create [controllers][controller-runtime] and custom resources which will deploy and manage an image on the cluster following
-the guidelines and best practices. It abstracts the complexities to achieve this goal while allowing users to improve and customize their projects.
-
-By using this plugin you will have:
-
-- a controller implementation to Deploy and manage an Operand(image) on the cluster
-- tests to check the reconciliation implemented using [ENVTEST][envtest]
-- the custom resources samples updated with the specs used
-- you will check that the Operand(image) will be added on the manager via environment variables
-
-
-Examples
-
-See the "project-v4-with-optional-plugins" directory under the [testdata][testdata] directory of the Kubebuilder project to check an example of a scaffolding created using this plugin.
-
-
-
-
-## When to use it ?
-
-- This plugin is helpful for those who are getting started.
-- If you are looking to Deploy and Manage an image (Operand) using [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) and the tool the plugin will create an API/controller to be reconciled to achieve this goal
-- If you are looking to speed up
-
-## How to use it ?
-
-After you create a new project with `kubebuilder init` you can create APIs using this plugin. Ensure that you have followed the [quick start](https://book.kubebuilder.io/quick-start.html) before trying to use it.
-
-Then, by using this plugin you can [create APIs](https://book.kubebuilder.io/cronjob-tutorial/gvks.html) informing the image (Operand) that you would like to deploy on the cluster. Note that you can optionally specify the command that could be used to initialize this container via the flag `--image-container-command` and the port with `--image-container-port` flag. You can also specify the `RunAsUser` value for the Security Context of the container via the flag `--run-as-user`., i.e:
-
-```sh
-kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,--memory-limit=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha"
-```
-
-
-Using make run
-
-The `make run` will execute the `main.go` outside of the cluster to let you test the project running it locally. Note that by using this plugin the Operand image informed will be stored via an environment variable in the `config/manager/manager.yaml` manifest.
-
-Therefore, before run `make run` you need to export any environment variable that you might have. Example:
-
-```sh
-export MEMCACHED_IMAGE="memcached:1.4.36-alpine"
-```
-
-
-
-## Subcommands
-
-The deploy-image plugin implements the following subcommands:
-
-- create api (`$ kubebuilder create api [OPTIONS]`)
-
-## Affected files
-
-With the `create api` command of this plugin, in addition to the existing scaffolding, the following files are affected:
-
-- `controllers/*_controller.go` (scaffold controller with reconciliation implemented)
-- `controllers/*_controller_test.go` (scaffold the tests for the controller)
-- `controllers/*_suite_test.go` (scaffold/update the suite of tests)
-- `api//*_types.go` (scaffold the specs for the new api)
-- `config/samples/*_.yaml` (scaffold default values for its CR)
-- `main.go` (update to add controller setup)
-- `config/manager/manager.yaml` (update with envvar to store the image)
-
-## Further Resources:
-
-- Check out [video to show how it works](https://youtu.be/UwPuRjjnMjY)
-- See the [desing proposal documentation](../../../../designs/code-generate-image-plugin.md)
-
-[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
-[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/
-[envtest]: ../reference/envtest.md
diff --git a/docs/book/src/plugins/extending-cli.md b/docs/book/src/plugins/extending-cli.md
deleted file mode 100644
index 3cf272dd8d5..00000000000
--- a/docs/book/src/plugins/extending-cli.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# Extending the CLI and Scaffolds
-
-## Overview
-
-You can extend Kubebuilder to allow your project to have the same CLI features and provide the plugins scaffolds.
-
-## CLI system
-
-Plugins are run using a [`CLI`][cli] object, which maps a plugin type to a subcommand and calls that plugin's methods.
-For example, writing a program that injects an `Init` plugin into a `CLI` then calling `CLI.Run()` will call the
-plugin's [SubcommandMetadata][plugin-sub-command], [UpdatesMetadata][plugin-update-meta] and `Run` methods with information a user has passed to the
-program in `kubebuilder init`. Following an example:
-
-```go
-package cli
-
-import (
- log "github.com/sirupsen/logrus"
- "github.com/spf13/cobra"
-
- "sigs.k8s.io/kubebuilder/v4/pkg/cli"
- cfgv3 "sigs.k8s.io/kubebuilder/v4/pkg/config/v3"
- "sigs.k8s.io/kubebuilder/v4/pkg/plugin"
- kustomizecommonv2 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/common/kustomize/v2"
- "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang"
- deployimage "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/deploy-image/v1alpha1"
- golangv4 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/v4"
-
-)
-
-var (
- // The following is an example of the commands
- // that you might have in your own binary
- commands = []*cobra.Command{
- myExampleCommand.NewCmd(),
- }
- alphaCommands = []*cobra.Command{
- myExampleAlphaCommand.NewCmd(),
- }
-)
-
-// 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/v4
- gov3Bundle, _ := plugin.NewBundleWithOptions(plugin.WithName(golang.DefaultNameQualifier),
- plugin.WithVersion(plugin.Version{Number: 3}),
- plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv4.Plugin{}),
- )
-
-
- c, err := cli.New(
- // Add the name of your CLI binary
- cli.WithCommandName("example-cli"),
-
- // Add the version of your CLI binary
- cli.WithVersion(versionString()),
-
- // Register the plugins options which can be used to do the scaffolds via your CLI tool. See that we are using as example here the plugins which are implemented and provided by Kubebuilder
- cli.WithPlugins(
- gov3Bundle,
- &deployimage.Plugin{},
- ),
-
- // Defines what will be the default plugin used by your binary. It means that will be the plugin used if no info be provided such as when the user runs `kubebuilder init`
- cli.WithDefaultPlugins(cfgv3.Version, gov3Bundle),
-
- // Define the default project configuration version which will be used by the CLI when none is informed by --project-version flag.
- cli.WithDefaultProjectVersion(cfgv3.Version),
-
- // Adds your own commands to the CLI
- cli.WithExtraCommands(commands...),
-
- // Add your own alpha commands to the CLI
- cli.WithExtraAlphaCommands(alphaCommands...),
-
- // Adds the completion option for your CLI
- cli.WithCompletion(),
- )
- if err != nil {
- log.Fatal(err)
- }
-
- return c
-}
-
-// versionString returns the CLI version
-func versionString() string {
- // return your binary project version
-}
-```
-
-This program can then be built and run in the following ways:
-
-Default behavior:
-
-```sh
-# Initialize a project with the default Init plugin, "go.example.com/v1".
-# This key is automatically written to a PROJECT config file.
-$ my-bin-builder init
-# Create an API and webhook with "go.example.com/v1" CreateAPI and
-# CreateWebhook plugin methods. This key was read from the config file.
-$ my-bin-builder create api [flags]
-$ my-bin-builder create webhook [flags]
-```
-
-Selecting a plugin using `--plugins`:
-
-```sh
-# Initialize a project with the "ansible.example.com/v1" Init plugin.
-# Like above, this key is written to a config file.
-$ my-bin-builder init --plugins ansible
-# Create an API and webhook with "ansible.example.com/v1" CreateAPI
-# and CreateWebhook plugin methods. This key was read from the config file.
-$ my-bin-builder create api [flags]
-$ my-bin-builder create webhook [flags]
-```
-
-### CLI manages the PROJECT file
-
-The CLI is responsible for managing the [PROJECT file config][project-file-config], representing the configuration of the projects that are scaffold by the CLI tool.
-
-## Plugins
-
-Kubebuilder provides scaffolding options via plugins. Plugins are responsible for implementing the code that will be executed when the sub-commands are called. You can create a new plugin by implementing the [Plugin interface][plugin-interface].
-
-On top of being a `Base`, a plugin should also implement the [`SubcommandMetadata`][plugin-subc] interface so it can be run with a CLI. It optionally to set custom help text for the target command; this method can be a no-op, which will preserve the default help text set by the [cobra][cobra] command constructors.
-
-Kubebuilder CLI plugins wrap scaffolding and CLI features in conveniently packaged Go types that are executed by the
-`kubebuilder` binary, or any binary which imports them. More specifically, a plugin configures the execution of one
-of the following CLI commands:
-
-- `init`: project initialization.
-- `create api`: scaffold Kubernetes API definitions.
-- `create webhook`: scaffold Kubernetes webhooks.
-
-Plugins are identified by a key of the form `/`. There are two ways to specify a plugin to run:
-
-- Setting `kubebuilder init --plugins=`, which will initialize a project configured for plugin with key
- ``.
-
-- A `layout: ` in the scaffolded [PROJECT configuration file][project-file]. Commands (except for `init`, which scaffolds this file) will look at this value before running to choose which plugin to run.
-
-By default, `` will be `go.kubebuilder.io/vX`, where `X` is some integer.
-
-For a full implementation example, check out Kubebuilder's native [`go.kubebuilder.io`][kb-go-plugin] plugin.
-
-### Plugin naming
-
-Plugin names must be DNS1123 labels and should be fully qualified, i.e. they have a suffix like
-`.example.com`. For example, the base Go scaffold used with `kubebuilder` commands has name `go.kubebuilder.io`.
-Qualified names prevent conflicts between plugin names; both `go.kubebuilder.io` and `go.example.com` can both scaffold
-Go code and can be specified by a user.
-
-### Plugin versioning
-
-A plugin's `Version()` method returns a [`plugin.Version`][plugin-version-type] object containing an integer value
-and optionally a stage string of either "alpha" or "beta". The integer denotes the current version of a plugin.
-Two different integer values between versions of plugins indicate that the two plugins are incompatible. The stage
-string denotes plugin stability:
-
-- `alpha`: should be used for plugins that are frequently changed and may break between uses.
-- `beta`: should be used for plugins that are only changed in minor ways, ex. bug fixes.
-
-### Breaking changes
-
-Any change that will break a project scaffolded by the previous plugin version is a breaking change.
-
-### Plugins Deprecation
-
-Once a plugin is deprecated, have it implement a [Deprecated][deprecate-plugin-doc] interface so a deprecation warning will be printed when it is used.
-
-## Bundle Plugins
-
-[Bundle Plugins][bundle-plugin-doc] allow you to create a plugin that is a composition of many plugins:
-
-```go
- // see that will be like myplugin.example/v1`
- myPluginBundle, _ := plugin.NewBundle(plugin.WithName(``),
- plugin.WithVersion(``),
- plugin.WithPlugins(pluginA.Plugin{}, pluginB.Plugin{}, pluginC.Plugin{}),
- )
-
-```
-
-Note that it means that when a user of your CLI calls this plugin, the execution of the sub-commands will be sorted by the order to which they were added in a chain:
-
-
-> `sub-command` of plugin A ➔ `sub-command` of plugin B ➔ `sub-command` of plugin C
-
-Then, to initialize using this "Plugin Bundle" which will run the chain of plugins:
-
-```
-kubebuider init --plugins=myplugin.example/v1
-```
-
-- Runs init `sub-command` of the plugin A
-- And then, runs init `sub-command` of the plugin B
-- And then, runs init `sub-command` of the plugin C
-
-[project-file-config]: ../reference/project-config.md
-[plugin-interface]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Plugin
-[go-dev-doc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4
-[plugin-sub-command]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Subcommand
-[project-file]: ../reference/project-config.md
-[plugin-subc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Subcommand
-[cobra]:https://pkg.go.dev/github.com/spf13/cobra
-[kb-go-plugin]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/v3
-[bundle-plugin-doc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Bundle
-[deprecate-plugin-doc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Deprecated
-[plugin-update-meta]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#UpdatesMetadata
-[cli]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/cli
-[plugin-version-type]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Version
diff --git a/docs/book/src/plugins/extending.md b/docs/book/src/plugins/extending.md
new file mode 100644
index 00000000000..fb5b5e75aea
--- /dev/null
+++ b/docs/book/src/plugins/extending.md
@@ -0,0 +1,57 @@
+# Extending Kubebuilder
+
+Kubebuilder provides an extensible architecture to scaffold
+projects using plugins. These plugins allow you to customize the CLI
+behavior or integrate new features.
+
+## Overview
+
+Kubebuilder’s CLI can be extended through custom plugins, allowing you to:
+
+- Build new scaffolds.
+- Enhance existing ones.
+- Add new commands and functionality to Kubebuilder’s scaffolding.
+
+This flexibility enables you to create custom project
+setups tailored to specific needs.
+
+
+Why use the Kubebuilder style?
+
+Kubebuilder and SDK are both broadly adopted projects which leverage the [controller-runtime][controller-runtime] project. They both allow users to build solutions using the [Operator Pattern][operator-pattern] and follow common standards.
+
+Adopting these standards can bring significant benefits, such as joining forces on maintaining the common standards as the features provided by Kubebuilder and take advantage of the contributions made by the community. This allows you to focus on the specific needs and requirements for your plugin and use-case.
+
+And then, you will also be able to use custom plugins and options currently or in the future which might to be provided by these projects as any other which decides to persuade the same standards.
+
+
+
+## Options to Extend
+
+Extending Kubebuilder can be achieved in two main ways:
+
+1. **Extending CLI features and Plugins**:
+ You can import and build upon existing Kubebuilder plugins to [extend
+ its features and plugins][extending-cli]. This is useful when you need to add specific
+ features to a tool that already benefits from Kubebuilder's scaffolding system.
+ For example, [Operator SDK][sdk] leverages the [kustomize plugin][kustomize-plugin]
+ to provide language support for tools like Ansible or Helm. So that the project
+ can be focused to keep maintained only what is specific language based.
+
+2. **Creating External Plugins**:
+ You can build standalone, independent plugins as binaries. These plugins can be written in any
+ language and should follow an execution pattern that Kubebuilder recognizes. For more information,
+ see [Creating external plugins][external-plugins].
+
+For further details on how to extend Kubebuilder, explore the following sections:
+
+- [CLI and Plugins](./extending/extending_cli_features_and_plugins.md) to learn how to extend CLI features and plugins.
+- [External Plugins](./extending/external-plugins.md) for creating standalone plugins.
+- [E2E Tests](./extending/testing-plugins.md) to ensure your plugin functions as expected.
+
+[extending-cli]: ./extending/extending_cli_features_and_plugins.md
+[external-plugins]: ./extending/external-plugins.md
+[sdk]: https://github.com/operator-framework/operator-sdk
+[kustomize-plugin]: ./available/kustomize-v2.md
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
\ No newline at end of file
diff --git a/docs/book/src/plugins/extending/extending_cli_features_and_plugins.md b/docs/book/src/plugins/extending/extending_cli_features_and_plugins.md
new file mode 100644
index 00000000000..5f794450a1a
--- /dev/null
+++ b/docs/book/src/plugins/extending/extending_cli_features_and_plugins.md
@@ -0,0 +1,411 @@
+# Extending CLI Features and Plugins
+
+Kubebuilder provides an extensible architecture to scaffold
+projects using plugins. These plugins allow you to customize the CLI
+behavior or integrate new features.
+
+In this guide, we’ll explore how to extend CLI features,
+create custom plugins, and bundle multiple plugins.
+
+## Creating Custom Plugins
+
+To create a custom plugin, you need to implement
+the [Kubebuilder Plugin interface][plugin-interface].
+
+This interface allows your plugin to hook into Kubebuilder’s
+commands (`init`, `create api`, `create webhook`, etc.)
+and add custom logic.
+
+### Example of a Custom Plugin
+
+You can create a plugin that generates both
+language-specific scaffolds and the necessary configuration files,
+using the [Bundle Plugin](#bundle-plugin). This example shows how to
+combine the Golang plugin with a Kustomize plugin:
+
+```go
+import (
+ kustomizecommonv2 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/common/kustomize/v2"
+ golangv4 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/v4"
+)
+
+mylanguagev1Bundle, _ := plugin.NewBundle(
+ plugin.WithName("mylanguage.kubebuilder.io"),
+ plugin.WithVersion(plugin.Version{Number: 1}),
+ plugin.WithPlugins(kustomizecommonv2.Plugin{}, mylanguagev1.Plugin{}),
+)
+```
+
+This composition allows you to scaffold a common
+configuration base (via Kustomize) and the
+language-specific files (via `mylanguagev1`).
+
+You can also use your plugin to scaffold specific
+resources like CRDs and controllers, using
+the `create api` and `create webhook` subcommands.
+
+### Plugin Subcommands
+
+Plugins are responsible for implementing the code that will be executed when the sub-commands are called.
+You can create a new plugin by implementing the [Plugin interface][plugin-interface].
+
+On top of being a `Base`, a plugin should also implement the [`SubcommandMetadata`][plugin-subc]
+interface so it can be run with a CLI. It optionally to set custom help
+text for the target command; this method can be a no-op, which will
+preserve the default help text set by the [cobra][cobra] command
+constructors.
+
+Kubebuilder CLI plugins wrap scaffolding and CLI features in conveniently packaged Go types that are executed by the
+`kubebuilder` binary, or any binary which imports them. More specifically, a plugin configures the execution of one
+of the following CLI commands:
+
+- `init`: Initializes the project structure.
+- `create api`: Scaffolds a new API and controller.
+- `create webhook`: Scaffolds a new webhook.
+- `edit`: edit the project structure.
+
+Here’s an example of using the `init` subcommand with a custom plugin:
+
+```sh
+kubebuilder init --plugins=mylanguage.kubebuilder.io/v1
+```
+
+This would initialize a project using the `mylanguage` plugin.
+
+### Plugin Keys
+
+Plugins are identified by a key of the form `/`.
+There are two ways to specify a plugin to run:
+
+- Setting `kubebuilder init --plugins=`, which will initialize a project configured for plugin with key
+ ``.
+
+- A `layout: ` in the scaffolded [PROJECT configuration file][project-file]. Commands (except for `init`, which scaffolds this file) will look at this value before running to choose which plugin to run.
+
+By default, `` will be `go.kubebuilder.io/vX`, where `X` is some integer.
+
+For a full implementation example, check out Kubebuilder's native [`go.kubebuilder.io`][kb-go-plugin] plugin.
+
+### Plugin naming
+
+Plugin names must be DNS1123 labels and should be fully qualified, i.e. they have a suffix like
+`.example.com`. For example, the base Go scaffold used with `kubebuilder` commands has name `go.kubebuilder.io`.
+Qualified names prevent conflicts between plugin names; both `go.kubebuilder.io` and `go.example.com` can both scaffold
+Go code and can be specified by a user.
+
+### Plugin versioning
+
+A plugin's `Version()` method returns a [`plugin.Version`][plugin-version-type] object containing an integer value
+and optionally a stage string of either "alpha" or "beta". The integer denotes the current version of a plugin.
+Two different integer values between versions of plugins indicate that the two plugins are incompatible. The stage
+string denotes plugin stability:
+
+- `alpha`: should be used for plugins that are frequently changed and may break between uses.
+- `beta`: should be used for plugins that are only changed in minor ways, ex. bug fixes.
+
+### Boilerplates
+
+The Kubebuilder internal plugins use boilerplates to generate the
+files of code. Kubebuilder uses templating to scaffold files for plugins.
+For instance, when creating a new project, the `go/v4` plugin
+scaffolds the `go.mod` file using a template defined in
+its implementation.
+
+You can extend this functionality in your custom
+plugin by defining your own templates and using
+[Kubebuilder’s machinery library][machinery] to generate files.
+This library allows you to:
+
+- Define file I/O behaviors.
+- Add [markers][markers-scaffold] to the scaffolded files.
+- Specify templates for your scaffolds.
+
+#### Example: Bollerplate
+
+For instance, the go/v4 scaffolds the `cmd/go.mod` file by defining an object that [implements the machinery interface][machinery].
+The `Template.SetTemplateDefaults`, the `raw template is set to the body:
+
+```go
+{{#include ./../../../../../pkg/plugins/golang/v4/scaffolds/internal/templates/gomod.go}}
+```
+
+Such object that implements the machinery interface will later pass to the
+execution of scaffold:
+
+```go
+// Scaffold implements cmdutil.Scaffolder
+func (s *initScaffolder) Scaffold() error {
+ log.Println("Writing scaffold for you to edit...")
+
+ // Initialize the machinery.Scaffold that will write the boilerplate file to disk
+ // The boilerplate file needs to be scaffolded as a separate step as it is going to
+ // be used by the rest of the files, even those scaffolded in this command call.
+ scaffold := machinery.NewScaffold(s.fs,
+ machinery.WithConfig(s.config),
+ )
+
+ ...
+
+ return scaffold.Execute(
+ ...
+ &templates.GoMod{
+ ControllerRuntimeVersion: ControllerRuntimeVersion,
+ },
+ ...
+ )
+}
+```
+
+#### Example: Overwriting a File in a Plugin
+
+Let's imagine that when a subcommand is called, you want
+to overwrite an existing file.
+
+For example, to modify the `Makefile` and add custom build steps,
+in the definition of your Template you can use the following option:
+
+```go
+f.IfExistsAction = machinery.OverwriteFile
+```
+
+By using those options, your plugin can take control
+of certain files generated by Kubebuilder’s default scaffolds.
+
+## Customizing Existing Scaffolds
+
+Kubebuilder provides utility functions to help you modify the default scaffolds. By using the [plugin utilities][plugin-utils], you can insert, replace, or append content to files generated by Kubebuilder, giving you full control over the scaffolding process.
+
+These utilities allow you to:
+
+- **Insert content**: Add content at a specific location within a file.
+- **Replace content**: Search for and replace specific sections of a file.
+- **Append content**: Add content to the end of a file without removing or altering the existing content.
+
+### Example
+
+If you need to insert custom content into a scaffolded file,
+you can use the `Insert` function provided by the plugin utilities:
+
+```go
+pluginutil.Insert(file, location, content)
+```
+
+This approach enables you to extend and modify the generated
+scaffolds while building custom plugins.
+
+For more details, refer to the [Kubebuilder plugin utilities][kb-utils].
+
+## Bundle Plugin
+
+Plugins can be bundled to compose more complex scaffolds.
+A plugin bundle is a composition of multiple plugins that
+are executed in a predefined order. For example:
+
+```go
+myPluginBundle, _ := plugin.NewBundle(
+ plugin.WithName("myplugin.example.com"),
+ plugin.WithVersion(plugin.Version{Number: 1}),
+ plugin.WithPlugins(pluginA.Plugin{}, pluginB.Plugin{}, pluginC.Plugin{}),
+)
+```
+
+This bundle will execute the `init` subcommand for each
+plugin in the specified order:
+
+1. `pluginA`
+2. `pluginB`
+3. `pluginC`
+
+The following command will run the bundled plugins:
+
+```sh
+kubebuilder init --plugins=myplugin.example.com/v1
+```
+
+## CLI system
+
+Plugins are run using a [`CLI`][cli] object, which maps a plugin type to a subcommand and calls that plugin's methods.
+For example, writing a program that injects an `Init` plugin into a `CLI` then calling `CLI.Run()` will call the
+plugin's [SubcommandMetadata][plugin-sub-command], [UpdatesMetadata][plugin-update-meta] and `Run` methods with information a user has passed to the
+program in `kubebuilder init`. Following an example:
+
+```go
+package cli
+
+import (
+ log "github.com/sirupsen/logrus"
+ "github.com/spf13/cobra"
+
+ "sigs.k8s.io/kubebuilder/v4/pkg/cli"
+ cfgv3 "sigs.k8s.io/kubebuilder/v4/pkg/config/v3"
+ "sigs.k8s.io/kubebuilder/v4/pkg/plugin"
+ kustomizecommonv2 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/common/kustomize/v2"
+ "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang"
+ deployimage "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/deploy-image/v1alpha1"
+ golangv4 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/v4"
+
+)
+
+var (
+ // The following is an example of the commands
+ // that you might have in your own binary
+ commands = []*cobra.Command{
+ myExampleCommand.NewCmd(),
+ }
+ alphaCommands = []*cobra.Command{
+ myExampleAlphaCommand.NewCmd(),
+ }
+)
+
+// 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/v4
+ gov3Bundle, _ := plugin.NewBundleWithOptions(plugin.WithName(golang.DefaultNameQualifier),
+ plugin.WithVersion(plugin.Version{Number: 3}),
+ plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv4.Plugin{}),
+ )
+
+
+ c, err := cli.New(
+ // Add the name of your CLI binary
+ cli.WithCommandName("example-cli"),
+
+ // Add the version of your CLI binary
+ cli.WithVersion(versionString()),
+
+ // Register the plugins options which can be used to do the scaffolds via your CLI tool. See that we are using as example here the plugins which are implemented and provided by Kubebuilder
+ cli.WithPlugins(
+ gov3Bundle,
+ &deployimage.Plugin{},
+ ),
+
+ // Defines what will be the default plugin used by your binary. It means that will be the plugin used if no info be provided such as when the user runs `kubebuilder init`
+ cli.WithDefaultPlugins(cfgv3.Version, gov3Bundle),
+
+ // Define the default project configuration version which will be used by the CLI when none is informed by --project-version flag.
+ cli.WithDefaultProjectVersion(cfgv3.Version),
+
+ // Adds your own commands to the CLI
+ cli.WithExtraCommands(commands...),
+
+ // Add your own alpha commands to the CLI
+ cli.WithExtraAlphaCommands(alphaCommands...),
+
+ // Adds the completion option for your CLI
+ cli.WithCompletion(),
+ )
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ return c
+}
+
+// versionString returns the CLI version
+func versionString() string {
+ // return your binary project version
+}
+```
+
+This program can then be built and run in the following ways:
+
+Default behavior:
+
+```sh
+# Initialize a project with the default Init plugin, "go.example.com/v1".
+# This key is automatically written to a PROJECT config file.
+$ my-bin-builder init
+# Create an API and webhook with "go.example.com/v1" CreateAPI and
+# CreateWebhook plugin methods. This key was read from the config file.
+$ my-bin-builder create api [flags]
+$ my-bin-builder create webhook [flags]
+```
+
+Selecting a plugin using `--plugins`:
+
+```sh
+# Initialize a project with the "ansible.example.com/v1" Init plugin.
+# Like above, this key is written to a config file.
+$ my-bin-builder init --plugins ansible
+# Create an API and webhook with "ansible.example.com/v1" CreateAPI
+# and CreateWebhook plugin methods. This key was read from the config file.
+$ my-bin-builder create api [flags]
+$ my-bin-builder create webhook [flags]
+```
+
+### Inputs should be tracked in the PROJECT file
+
+The CLI is responsible for managing the [PROJECT file configuration][project-file-config],
+which represents the configuration of the projects scaffolded by the
+CLI tool.
+
+When extending Kubebuilder, it is recommended to ensure that your tool
+or [External Plugin][external-plugin] properly uses the
+[PROJECT file][project-file-config] to track relevant information.
+This ensures that other external tools and plugins can properly
+integrate with the project. It also allows tools features to help users
+re-scaffold their projects such as the [Project Upgrade Assistant][upgrade-assistant]
+provided by Kubebuilder, ensuring the tracked information in the
+PROJECT file can be leveraged for various purposes.
+
+For example, plugins can check whether they support the project setup
+and re-execute commands based on the tracked inputs.
+
+#### Example
+
+By running the following command to use the
+[Deploy Image][deploy-image] plugin to scaffold
+an API and its controller:
+
+```sh
+kubebyilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:memcached:1.6.26-alpine3.19 --image-container-command="memcached,--memory-limit=64,-o,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha" --make=false
+```
+
+The following entry would be added to the PROJECT file:
+
+```yaml
+...
+plugins:
+ deploy-image.go.kubebuilder.io/v1-alpha:
+ resources:
+ - domain: testproject.org
+ group: example.com
+ kind: Memcached
+ options:
+ containerCommand: memcached,--memory-limit=64,-o,modern,-v
+ containerPort: "11211"
+ image: memcached:memcached:1.6.26-alpine3.19
+ runAsUser: "1001"
+ version: v1alpha1
+ - domain: testproject.org
+ group: example.com
+ kind: Busybox
+ options:
+ image: busybox:1.36.1
+ version: v1alpha1
+...
+```
+
+By inspecting the PROJECT file, it becomes possible to understand how
+the plugin was used and what inputs were provided. This not only allows
+re-execution of the command based on the tracked data but also enables
+creating features or plugins that can rely on this information.
+
+[sdk]: https://github.com/operator-framework/operator-sdk
+[plugin-interface]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin
+[machinery]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/machinery
+[plugin-subc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Subcommand
+[plugin-version-type]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Version
+[bundle-plugin-doc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Bundle
+[deprecate-plugin-doc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Deprecated
+[plugin-sub-command]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#Subcommand
+[plugin-update-meta]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin#UpdatesMetadata
+[markers-scaffold]: ./../../reference/markers/scaffold.md
+[kb-utils]: ./../../../../../pkg/plugin/util/util.go
+[project-file-config]: ./../../reference/project-config.md
+[cli]: ./../../../../../pkg/cli
+[kb-go-plugin]: ./../../../../../pkg/plugins/golang/v4
+[cobra]: https://github.com/spf13/cobra
+[external-plugin]: external-plugins.md
+[deploy-image]: ./../available/deploy-image-plugin-v1-alpha.md
+[upgrade-assistant]: ./../../reference/rescaffold.md
\ No newline at end of file
diff --git a/docs/book/src/plugins/extending/external-plugins.md b/docs/book/src/plugins/extending/external-plugins.md
new file mode 100644
index 00000000000..03c344037f5
--- /dev/null
+++ b/docs/book/src/plugins/extending/external-plugins.md
@@ -0,0 +1,151 @@
+# Creating External Plugins for Kubebuilder
+
+## Overview
+
+Kubebuilder's functionality can be extended through external plugins.
+These plugins are executables (written in any language) that follow an
+execution pattern recognized by Kubebuilder. Kubebuilder interacts with
+these plugins via `stdin` and `stdout`, enabling seamless communication.
+
+## Why Use External Plugins?
+
+External plugins enable third-party solution maintainers to integrate their tools with Kubebuilder.
+Much like Kubebuilder's own plugins, these can be opt-in, offering users
+flexibility in tool selection. By developing plugins in their repositories,
+maintainers ensure updates are aligned with their CI pipelines and can
+manage any changes within their domain of responsibility.
+
+If you are interested in this type of integration, collaborating with the
+maintainers of the third-party solution is recommended. Kubebuilder's maintainers
+is always willing to provide support in extending its capabilities.
+
+## How to Write an External Plugin
+
+Communication between Kubebuilder and an external plugin occurs via
+standard I/O. Any language can be used to create the plugin, as long
+as it follows the [PluginRequest][code-plugin-external] and [PluginResponse][code-plugin-external]
+structures.
+
+### PluginRequest
+
+`PluginRequest` contains the data collected from the CLI and any previously executed plugins. Kubebuilder sends this data as a JSON object to the external plugin via `stdin`.
+
+**Example `PluginRequest` (triggered by `kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain`):**
+
+```json
+{
+ "apiVersion": "v1alpha1",
+ "args": ["--domain", "my.domain"],
+ "command": "init",
+ "universe": {}
+}
+```
+
+### PluginResponse
+
+`PluginResponse` contains the modifications made by the plugin to the project. This data is serialized as JSON and returned to Kubebuilder through `stdout`.
+
+**Example `PluginResponse`:**
+```json
+{
+ "apiVersion": "v1alpha1",
+ "command": "init",
+ "metadata": {
+ "description": "The `init` subcommand initializes a project via Kubebuilder. It scaffolds a single file: `initFile`.",
+ "examples": "kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain"
+ },
+ "universe": {
+ "initFile": "A file created with the `init` subcommand."
+ },
+ "error": false,
+ "errorMsgs": []
+}
+```
+
+
+
+
+Avoid printing directly to `stdout` in your external plugin.
+Since communication between Kubebuilder and the plugin occurs through
+`stdin` and `stdout` using structured JSON, any unexpected output
+(like debug logs) may cause errors. Write logs to a file if needed.
+
+
+
+## How to Use an External Plugin
+
+### Prerequisites
+
+- Kubebuilder CLI version > 3.11.0
+- An executable for the external plugin
+- Plugin path configuration using `${EXTERNAL_PLUGINS_PATH}` or default OS-based paths:
+ - Linux: `$HOME/.config/kubebuilder/plugins/${name}/${version}/${name}`
+ - macOS: `~/Library/Application Support/kubebuilder/plugins/${name}/${version}/${name}`
+
+**Example:** For a plugin `foo.acme.io` version `v2` on Linux, the path would be `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io`.
+
+### Available Subcommands
+
+External plugins can support the following Kubebuilder subcommands:
+- `init`: Project initialization
+- `create api`: Scaffold Kubernetes API definitions
+- `create webhook`: Scaffold Kubernetes webhooks
+- `edit`: Update project configuration
+
+**Optional subcommands for enhanced user experience:**
+- `metadata`: Provide plugin descriptions and examples with the `--help` flag.
+- `flags`: Inform Kubebuilder of supported flags, enabling early error detection.
+
+
+More about `flags` subcommand
+
+The `flags` subcommand in an external plugin allows for early error detection by informing Kubebuilder about the flags the plugin supports. If an unsupported flag is identified, Kubebuilder can issue an error before the plugin is called to execute.
+If a plugin does not implement the `flags` subcommand, Kubebuilder will pass all flags to the plugin, making it the external plugin's responsibility to handle any invalid flags.
+
+
+
+### Configuring Plugin Path
+
+Set the environment variable `$EXTERNAL_PLUGINS_PATH`
+to specify a custom plugin binary path:
+
+```sh
+export EXTERNAL_PLUGINS_PATH=
+```
+
+Otherwise, Kubebuilder would search for the plugins in a default path based on your OS.
+
+### Example CLI Commands
+
+Now, you can using it by calling the CLI commands:
+
+```sh
+# Initialize a new project with the external plugin named `sampleplugin`
+kubebuilder init --plugins sampleplugin/v1
+
+# Display help information of the `init` subcommand of the external plugin
+kubebuilder init --plugins sampleplugin/v1 --help
+
+# Create a new API with the above external plugin with a customized flag `number`
+kubebuilder create api --plugins sampleplugin/v1 --number 2
+
+# Create a webhook with the above external plugin with a customized flag `hooked`
+kubebuilder create webhook --plugins sampleplugin/v1 --hooked
+
+# Update the project configuration with the above external plugin
+kubebuilder edit --plugins sampleplugin/v1
+
+# Create new APIs with external plugins v1 and v2 by respecting the plugin chaining order
+kubebuilder create api --plugins sampleplugin/v1,sampleplugin/v2
+
+# Create new APIs with the go/v4 plugin and then pass those files to the external plugin by respecting the plugin chaining order
+kubebuilder create api --plugins go/v4,sampleplugin/v1
+```
+
+## Further resources
+
+- A [sample external plugin written in Go](https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1)
+- A [sample external plugin written in Python](https://github.com/rashmigottipati/POC-Phase2-Plugins)
+- A [sample external plugin written in JavaScript](https://github.com/Eileen-Yu/kb-js-plugin)
+
+[code-plugin-external]: ./../../../../../pkg/plugin/external/types.go
diff --git a/docs/book/src/plugins/extending/testing-plugins.md b/docs/book/src/plugins/extending/testing-plugins.md
new file mode 100644
index 00000000000..f58121a60bd
--- /dev/null
+++ b/docs/book/src/plugins/extending/testing-plugins.md
@@ -0,0 +1,108 @@
+# Write E2E Tests
+
+You can check the [Kubebuilder/v4/test/e2e/utils][utils-kb] package, which offers `TestContext` with rich methods:
+
+- [NewTestContext][new-context] helps define:
+ - A temporary folder for testing projects.
+ - A temporary controller-manager image.
+ - The [Kubectl execution method][kubectl-ktc].
+ - The CLI executable (whether `kubebuilder`, `operator-sdk`, or your extended CLI).
+
+Once defined, you can use `TestContext` to:
+
+1. **Setup the testing environment**, e.g.:
+ - Clean up the environment and create a temporary directory. See [Prepare][prepare-method].
+ - Install prerequisite CRDs. See [InstallCertManager][cert-manager-install], [InstallPrometheusManager][prometheus-manager-install].
+
+2. **Validate the plugin behavior**, e.g.:
+ - Trigger the plugin's bound subcommands. See [Init][init-subcommand], [CreateAPI][create-api-subcommand].
+ - Use [PluginUtil][plugin-util] to verify scaffolded outputs. See [InsertCode][insert-code], [ReplaceInFile][replace-in-file], [UncommentCode][uncomment-code].
+
+3. **Ensure the scaffolded output works**, e.g.:
+ - Execute commands in your `Makefile`. See [Make][make-command].
+ - Temporarily load an image of the testing controller. See [LoadImageToKindCluster][load-image-to-kind].
+ - Call Kubectl to validate running resources. See [Kubectl][kubectl-ktc].
+
+4. **Cleanup temporary resources after testing**:
+ - Uninstall prerequisite CRDs. See [UninstallPrometheusOperManager][uninstall-prometheus-manager].
+ - Delete the temporary directory. See [Destroy][destroy-method].
+
+**References**:
+- [operator-sdk e2e tests][sdk-e2e-tests]
+- [kubebuilder e2e tests][kb-e2e-tests]
+
+
+## Generate Test Samples
+
+It's straightforward to view the content of sample projects generated
+by your plugin.
+
+For example, Kubebuilder generates [sample projects][kb-samples] based
+on different plugins to validate the layouts.
+
+You can also use `TestContext` to generate folders of scaffolded
+projects from your plugin. The commands are similar to those
+mentioned in [Extending CLI Features and Plugins][extending-cli].
+
+Here’s a general workflow to create a sample project using the `go/v4` plugin (`kbc` is an instance of `TestContext`):
+
+- **To initialize a project**:
+ ```go
+ By("initializing a project")
+ err = kbc.Init(
+ "--plugins", "go/v4",
+ "--project-version", "3",
+ "--domain", kbc.Domain,
+ "--fetch-deps=false",
+ )
+ ExpectWithOffset(1, err).NotTo(HaveOccurred())
+ ```
+
+- **To define API:**
+ ```go
+ By("creating API definition")
+ err = kbc.CreateAPI(
+ "--group", kbc.Group,
+ "--version", kbc.Version,
+ "--kind", kbc.Kind,
+ "--namespaced",
+ "--resource",
+ "--controller",
+ "--make=false",
+ )
+ ExpectWithOffset(1, err).NotTo(HaveOccurred())
+ ```
+
+- **To scaffold webhook configurations:**
+ ```go
+ By("scaffolding mutating and validating webhooks")
+ err = kbc.CreateWebhook(
+ "--group", kbc.Group,
+ "--version", kbc.Version,
+ "--kind", kbc.Kind,
+ "--defaulting",
+ "--programmatic-validation",
+ )
+ ExpectWithOffset(1, err).NotTo(HaveOccurred())
+ ```
+
+[sdk-e2e-tests]: https://github.com/operator-framework/operator-sdk/tree/master/test/e2e/go
+[new-context]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#NewTestContext
+[kubectl-ktc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#Kubectl
+[prepare-method]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.Prepare
+[cert-manager-install]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.InstallCertManager
+[prometheus-manager-install]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.InstallPrometheusOperManager
+[init-subcommand]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.Init
+[create-api-subcommand]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.CreateAPI
+[plugin-util]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin/util
+[insert-code]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin/util#InsertCode
+[replace-in-file]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin/util#ReplaceInFile
+[uncomment-code]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin/util#UncommentCode
+[make-command]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.Make
+[load-image-to-kind]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.LoadImageToKindCluster
+[uninstall-prometheus-manager]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.UninstallPrometheusOperManager
+[destroy-method]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#TestContext.Destroy
+[kb-samples]: ./../../../../../testdata
+[kb-e2e-tests]: ./../../../../../test/e2e/
+[utils-kb]: ./../../../../../test/e2e/utils
+[extending-cli]: ./extending_cli_features_and_plugins.md
diff --git a/docs/book/src/plugins/external-plugins.md b/docs/book/src/plugins/external-plugins.md
deleted file mode 100644
index 19076470e07..00000000000
--- a/docs/book/src/plugins/external-plugins.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# Creating External Plugins
-
-## Overview
-
-Kubebuilder's functionality can be extended through the use of external plugins.
-
-An external plugin is an executable (can be written in any language) that implements an execution pattern that Kubebuilder knows how to interact with.
-
-The Kubebuilder CLI loads the external plugin in the specified path and interacts with it through `stdin` & `stdout`.
-
-## When is it useful?
-
-- If you want to create helpers or addons on top of the scaffolds done by Kubebuilder's default scaffolding.
-
-- If you design customized layouts and want to take advantage of functions from Kubebuilder library.
-
-- If you are looking for implementing plugins in a language other than `Go`.
-
-## How to write it?
-
-The inter-process communication between your external plugin and Kubebuilder is through the standard I/O.
-
-Your external plugin can be written in any language, given it adheres to the [PluginRequest][PluginRequest] and [PluginResponse][PluginResponse] type structures.
-
-`PluginRequest` encompasses all the data Kubebuilder collects from the CLI and previously executed plugins in the plugin chain.
-Kubebuilder conveys the marshaled PluginRequest (a `JSON` object) to the external plugin over `stdin`.
-
-Below is a sample JSON object of the `PluginRequest` type, triggered by `kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain`:
-```json
-{
- "apiVersion": "v1alpha1",
- "args": ["--domain", "my.domain"],
- "command": "init",
- "universe": {}
-}
-```
-
-`PluginResponse` represents the updated state of the project, as modified by the plugin. This data structure is serialized into `JSON` and sent back to Kubebuilder via `stdout`.
-
-Here is a sample JSON representation of the `PluginResponse` type:
-```json
-{
- "apiVersion": "v1alpha1",
- "command": "init",
- "metadata": {
- "description": "The `init` subcommand is meant to initialize a project via Kubebuilder. It scaffolds a single file: `initFile`",
- "examples": "kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain"
- },
- "universe": {
- "initFile": "A simple file created with the `init` subcommand"
- },
- "error": false,
- "errorMsgs": []
-}
-```
-
-In this example, the `init` command of the plugin has created a new file called `initFile`.
-
-The content of this file is: `A simple file created with the init subcommand`, which is recorded in the `universe` field of the response.
-
-This output is then sent back to Kubebuilder, allowing it to incorporate the changes made by the plugin into the project.
-
-
-Caution
-
-When writing your own external plugin, you **should not** directly echo or print anything to the stdout.
-
-This is because Kubebuilder and your plugin are communicating with each other via `stdin` and `stdout` using structured `JSON` data.
-Any additional information sent to stdout (such as debug messages or logs) that's not part of the expected PluginResponse JSON structure may cause parsing errors when Kubebuilder tries to read and decode the response from your plugin.
-
-If you need to include logs or debug messages while developing your plugin, consider writing these messages to a log file instead.
-
-
-
-## How to use it?
-
-### Prerequisites
-- kubebuilder CLI > 3.11.0
-- An executable for the external plugin.
-
- This could be a plugin that you've created yourself, or one from an external source.
-- Configuration of the external plugin's path.
-
- This can be done by setting the `${EXTERNAL_PLUGINS_PATH}` environment variable, or by placing the plugin in a path that follows a `group-like name and version` scheme:
-```sh
-# for Linux
-$HOME/.config/kubebuilder/plugins/${name}/${version}/${name}
-
-# for OSX
-~/Library/Application Support/kubebuilder/plugins/${name}/${version}/${name}
-```
-As an example, if you're on Linux and you want to use `v2` of an external plugin called `foo.acme.io`, you'd place the executable in the folder `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/` with a file name that also matches the plugin name up to an (optional) file extension.
-In other words, passing the flag `--plugins=foo.acme.io/v2` to `kubebuilder` would find the plugin at either of these locations
-* `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io`
-* `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io.sh`
-* `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io.py`
-* etc...
-
-### Subcommands:
-
-The external plugin supports the same subcommands as kubebuilder already provides:
-- `init`: project initialization.
-- `create api`: scaffold Kubernetes API definitions.
-- `create webhook`: scaffold Kubernetes webhooks.
-- `edit`: update the project configuration.
-
-Also, there are **Optional** subcommands for a better user experience:
-- `metadata`: add customized plugin description and examples when a `--help` flag is specified.
-- `flags`: specify valid flags for Kubebuilder to pass to the external plugin.
-
-
-More about `flags` subcommand
-
-The `flags` subcommand in an external plugin allows for early error detection by informing Kubebuilder about the flags the plugin supports. If an unsupported flag is identified, Kubebuilder can issue an error before the plugin is called to execute.
-If a plugin does not implement the `flags` subcommand, Kubebuilder will pass all flags to the plugin, making it the external plugin's responsibility to handle any invalid flags.
-
-
-
-### Configuration
-
-You can configure your plugin path with a ENV VAR `$EXTERNAL_PLUGINS_PATH` to tell Kubebuilder where to search for the plugin binary, such as:
-```sh
-export EXTERNAL_PLUGINS_PATH =
-```
-
-Otherwise, Kubebuilder would search for the plugins in a default path based on your OS.
-
-Now, you can using it by calling the CLI commands:
-```sh
-# Initialize a new project with the external plugin named `sampleplugin`
-kubebuilder init --plugins sampleplugin/v1
-
-# Display help information of the `init` subcommand of the external plugin
-kubebuilder init --plugins sampleplugin/v1 --help
-
-# Create a new API with the above external plugin with a customized flag `number`
-kubebuilder create api --plugins sampleplugin/v1 --number 2
-
-# Create a webhook with the above external plugin with a customized flag `hooked`
-kubebuilder create webhook --plugins sampleplugin/v1 --hooked
-
-# Update the project configuration with the above external plugin
-kubebuilder edit --plugins sampleplugin/v1
-
-# Create new APIs with external plugins v1 and v2 by respecting the plugin chaining order
-kubebuilder create api --plugins sampleplugin/v1,sampleplugin/v2
-
-# Create new APIs with the go/v4 plugin and then pass those files to the external plugin by respecting the plugin chaining order
-kubebuilder create api --plugins go/v4,sampleplugin/v1
-```
-
-
-## Further resources
-
-- Check the [design proposal of the external plugin](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md)
-- Check the [plugin implementation](https://github.com/kubernetes-sigs/kubebuilder/pull/2338)
-- A [sample external plugin written in Go](https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1)
-- A [sample external plugin written in Python](https://github.com/rashmigottipati/POC-Phase2-Plugins)
-- A [sample external plugin written in JavaScript](https://github.com/Eileen-Yu/kb-js-plugin)
-
-[PluginRequest]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugin/external/types.go#L23
-[PluginResponse]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugin/external/types.go#L42
diff --git a/docs/book/src/plugins/go-v4-plugin.md b/docs/book/src/plugins/go-v4-plugin.md
deleted file mode 100644
index b79d8a59562..00000000000
--- a/docs/book/src/plugins/go-v4-plugin.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# [Default Scaffold] go/v4 (go.kubebuilder.io/v4)
-
-Kubebuilder will scaffold using the `go/v4` plugin only if specified when initializing the project.
-This plugin is a composition of the plugins ` kustomize.common.kubebuilder.io/v2` and `base.go.kubebuilder.io/v4`.
-It scaffolds a project template that helps in constructing sets of [controllers][controller-runtime].
-
-It scaffolds boilerplate code to create and design controllers.
-Note that by following the [quickstart][quickstart] you will be using this plugin.
-
-
-Examples
-
-You can check samples using this plugin by looking at the `project-v4-` projects
-under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
-
-
-
-## When to use it ?
-
-If you are looking to scaffold Golang projects to develop projects using [controllers][controller-runtime]
-
-
-
-Migration from `go/v3`
-
-If you have a project created with `go/v3` (default layout since `28 Apr 2021` and Kubebuilder release version `3.0.0`) to `go/v4` then,
-see the migration guide [Migration from go/v3 to go/v4](./../migration/migration_guide_gov3_to_gov4.md)
-
-
-
-## How to use it ?
-
-To create a new project with the `go/v4` plugin the following command can be used:
-
-```sh
-kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project --plugins=go/v4
-```
-
-## Subcommands supported by the plugin
-
-- Init - `kubebuilder init [OPTIONS]`
-- Edit - `kubebuilder edit [OPTIONS]`
-- Create API - `kubebuilder create api [OPTIONS]`
-- Create Webhook - `kubebuilder create webhook [OPTIONS]`
-
-## Further resources
-
-- To see the composition of plugins, you can check the source code for the Kubebuilder [main.go][plugins-main].
-- Check the code implementation of the [base Golang plugin `base.go.kubebuilder.io/v4`][v4-plugin].
-- Check the code implementation of the [Kustomize/v2 plugin][kustomize-plugin].
-- Check [controller-runtime][controller-runtime] to know more about controllers.
-
-[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
-[quickstart]: ../quick-start.md
-[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata
-[plugins-main]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/cmd/main.go
-[kustomize-plugin]: ../plugins/kustomize-v2.md
-[kustomize]: https://github.com/kubernetes-sigs/kustomize
-[standard-go-project]: https://github.com/golang-standards/project-layout
-[v4-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/golang/v4
diff --git a/docs/book/src/plugins/plugins-versioning.md b/docs/book/src/plugins/plugins-versioning.md
index add3389f875..a0a34dada38 100644
--- a/docs/book/src/plugins/plugins-versioning.md
+++ b/docs/book/src/plugins/plugins-versioning.md
@@ -1,10 +1,10 @@
# Plugins Versioning
-| Name | Example | Description |
-|----------|-------------|--------|
-| Kubebuilder version | `v2.2.0`, `v2.3.0`, `v2.3.1` | Tagged versions of the Kubebuilder project, representing changes to the source code in this repository. See the [releases][kb-releases] page for binary releases. |
-| Project version | `"1"`, `"2"`, `"3"` | Project version defines the scheme of a `PROJECT` configuration file. This version is defined in a `PROJECT` file's `version`. |
-| Plugin version | `v2`, `v3` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. This version is defined in a plugin key, ex. `go.kubebuilder.io/v2`. See the [design doc][cli-plugins-versioning] for more details. |
+| Name | Example | Description |
+|----------|-----------------------------------------|--------|
+| Kubebuilder version | `v2.2.0`, `v2.3.0`, `v2.3.1`, `v4.2.0` | Tagged versions of the Kubebuilder project, representing changes to the source code in this repository. See the [releases][kb-releases] page for binary releases. |
+| Project version | `"1"`, `"2"`, `"3"` | Project version defines the scheme of a `PROJECT` configuration file. This version is defined in a `PROJECT` file's `version`. |
+| Plugin version | `v2`, `v3`, `v4` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. This version is defined in a plugin key, ex. `go.kubebuilder.io/v2`. See the [design doc][cli-plugins-versioning] for more details. |
### Incrementing versions
@@ -15,14 +15,6 @@ Project versions should only be increased if a breaking change is introduced in
Similarly, the introduction of a new plugin version might only lead to a new minor version release of Kubebuilder, since no breaking change is being made to the CLI itself. It'd only be a breaking change to Kubebuilder if we remove support for an older plugin version. See the plugins design doc [versioning section][cli-plugins-versioning]
for more details on plugin versioning.
-
-
-Why go/2 is different?
-
-The scheme for project version `"2"` was defined before the concept of plugins was introduced, so plugin `go.kubebuilder.io/v2` is implicitly used for those project types. Schema for project versions `"3"` and beyond define a `layout` key that informs the plugin system of which plugin to use.
-
-
-
## Introducing changes to plugins
Changes made to plugins only require a plugin version increase if and only if a change is made to a plugin
@@ -40,14 +32,21 @@ for users to upgrade their projects from `vX` to `v(X+1)-alpha`.
Example
-Kubebuilder scaffolds projects with plugin `go.kubebuilder.io/v3` by default.
+Kubebuilder scaffolds projects with plugin `go.kubebuilder.io/v4` by default.
-You create a feature that adds a new marker to the file `main.go` scaffolded by `init` that `create api` will use to update that file. The changes introduced in your feature would cause errors if used with projects built with plugins `go.kubebuilder.io/v2` without users manually updating their projects. Thus, your changes introduce a breaking change to plugin `go.kubebuilder.io`, and can only be merged into plugin version `v3-alpha`. This plugin's package should exist already.
+You create a feature that adds a new marker to the file `main.go` scaffolded by `init` that `create api` will use to update that file.
+The changes introduced in your feature would cause errors if used with projects built with
+plugins `go.kubebuilder.io/v4` without users manually updating their projects.
+
+Thus, your changes introduce a breaking change to plugin `go.kubebuilder.io`,
+and can only be merged into plugin version `v5-alpha`.
+This plugin's package should exist already.
-[design-doc]: ./extending-cli.md
-[cli-plugins-versioning]:./extending-cli.md#plugin-versioning
+
[semver]: https://semver.org/
[migrations]: ../migrations.md
[kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases
+[design-doc]: ./extending
+[cli-plugins-versioning]:./extending#plugin-versioning
\ No newline at end of file
diff --git a/docs/book/src/plugins/plugins.md b/docs/book/src/plugins/plugins.md
index 0f71d9f2ba4..66dae4859b6 100644
--- a/docs/book/src/plugins/plugins.md
+++ b/docs/book/src/plugins/plugins.md
@@ -1,40 +1,47 @@
# Plugins
-Since the `3.0.0` Kubebuilder version, preliminary support for plugins was added. You can [Extend the CLI and Scaffolds][extending-cli] as well. See that when users run the CLI commands to perform the scaffolds, the plugins are used:
+Kubebuilder's architecture is fundamentally plugin-based.
+This design enables the Kubebuilder CLI to evolve while maintaining
+backward compatibility with older versions, allowing users to opt-in or
+opt-out of specific features, and enabling seamless integration
+with external tools.
-- To initialize a project with a chain of global plugins:
+By leveraging plugins, projects can extend Kubebuilder and use it as a
+library to support new functionalities or implement custom scaffolding
+tailored to their users' needs. This flexibility allows maintainers
+to build on top of Kubebuilder’s foundation, adapting it to specific
+use cases while benefiting from its powerful scaffolding engine.
-```sh
-kubebuilder init --plugins=pluginA,pluginB
-```
+Plugins offer several key advantages:
+
+- **Backward compatibility**: Ensures older layouts and project structures remain functional with newer versions.
+- **Customization**: Allows users to opt-in or opt-out for specific features (i.e. [Grafana][grafana-plugin] and [Deploy Image][deploy-image] plugins)
+- **Extensibility**: Facilitates integration with third-party tools and projects that wish to provide their own [External Plugins][external-plugins], which can be used alongside Kubebuilder to modify and enhance project scaffolding or introduce new features.
-- To perform an optional scaffold using custom plugins:
+**For example, to initialize a project with multiple global plugins:**
```sh
-kubebuilder create api --plugins=pluginA,pluginB
+kubebuilder init --plugins=pluginA,pluginB,pluginC
```
-This section details how to extend Kubebuilder and create your plugins following the same layout structures.
-
-
-Note
-
-You can check the existing design proposal docs at [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] to know more on what is provided by Kubebuilder CLI and API currently.
+**For example, to apply custom scaffolding using specific plugins:**
-
-
-
-What is about to come next?
-
-To know more about Kubebuilder's future vision of the Plugins architecture, see the section [Future vision for Kubebuilder Plugins][section-future-vision-plugins].
+```sh
+kubebuilder create api --plugins=pluginA,pluginB,pluginC
+OR
+kubebuilder create webhook --plugins=pluginA,pluginB,pluginC
+OR
+kubebuilder edit --plugins=pluginA,pluginB,pluginC
+```
-
+This section details the available plugins, how to extend Kubebuilder,
+and how to create your own plugins while following the same layout structures.
-- [Extending the CLI and Scaffolds](extending-cli.md)
-- [Creating your own plugins](creating-plugins.md)
-- [Testing your plugins](testing-plugins.md)
+- [Available Plugins](./available-plugins.md)
+- [Extending](./extending.md)
+- [Plugins Versioning](./plugins-versioning.md)
-[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
-[extending-cli]: extending-cli.md
-[section-future-vision-plugins]: https://book.kubebuilder.io/plugins/creating-plugins.html#future-vision-for-kubebuilder-plugins
+[extending-cli]: extending.md
+[grafana-plugin]: ./available/grafana-v1-alpha.md
+[deploy-image]: ./available/deploy-image-plugin-v1-alpha.md
+[external-plugins]: ./extending/external-plugins.md
\ No newline at end of file
diff --git a/docs/book/src/plugins/testing-plugins.md b/docs/book/src/plugins/testing-plugins.md
deleted file mode 100644
index d22028a8a96..00000000000
--- a/docs/book/src/plugins/testing-plugins.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Test Your Plugins
-
-You can test your plugin in two dimension:
-
-1. Validate your plugin behavior through E2E tests
-2. Generate sample projects based on your plugin that can be placed in `./testdata/`
-
-## Write E2E Tests
-
-You can check [Kubebuilder/v3/test/e2e/utils](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils) package that offers `TestContext` of rich methods:
-
-- [NewTestContext](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L51) helps define:
- - Temporary folder for testing projects
- - Temporary controller-manager image
- - [Kubectl execution method](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#Kubectl)
- - The cli executable (`kubebuilder`, `operator-sdk`, OR your extended-cli)
-
-Once defined, you can use `TestContext` to:
-
-1. Setup testing environment, e.g:
- - Clean up the environment, create temp dir. See [Prepare](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L97)
- - Install prerequisites CRDs: See [InstallCertManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L138), [InstallPrometheusManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/test/e2e/utils/test_context.go#L171)
-2. Validate the plugin behavior, e.g:
- - Trigger the plugin's bound subcommands. See [Init](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L213), [CreateAPI](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/test/e2e/utils/test_context.go#L222)
- - Use [PluginUtil](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/plugin/util) to verify the scaffolded outputs. See [InsertCode](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/pkg/plugin/util/util.go#L67), [ReplaceInFile](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/pkg/plugin/util/util.go#L196), [UncommendCode](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/pkg/plugin/util/util.go#L86)
-3. Further make sure the scaffolded output works, e.g:
- - Execute commands in your `Makefile`. See [Make](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L240)
- - Temporary load image of the testing controller. See [LoadImageToKindCluster](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L283)
- - Call Kubectl to validate running resources. See [utils.Kubectl](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/test/e2e/utils#Kubectl)
-4. Delete temporary resources after testing exited, e.g:
- - Uninstall prerequisites CRDs: See [UninstallPrometheusOperManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L183)
- - Delete temp dir. See [Destroy](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L255)
-
-**References:** [operator-sdk e2e tests](https://github.com/operator-framework/operator-sdk/tree/master/test/e2e/go), [kubebuiler e2e tests](https://github.com/kubernetes-sigs/kubebuilder/tree/master/test/e2e/v3)
-
-## Generate Test Samples
-
-It can be straightforward to view content of sample projects generated by your plugin.
-
-For example, Kubebuilder generate [sample projects](https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/testdata) based on different plugins to validate the layouts.
-
-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/v4`: (`kbc` is an instance of `TextContext`)
-
-- To initialized a project:
- ```go
- By("initializing a project")
- err = kbc.Init(
- "--plugins", "go/v4",
- "--project-version", "3",
- "--domain", kbc.Domain,
- "--fetch-deps=false",
- )
- ExpectWithOffset(1, err).NotTo(HaveOccurred())
- ```
-- To define API:
- ```go
- By("creating API definition")
- err = kbc.CreateAPI(
- "--group", kbc.Group,
- "--version", kbc.Version,
- "--kind", kbc.Kind,
- "--namespaced",
- "--resource",
- "--controller",
- "--make=false",
- )
- ExpectWithOffset(1, err).NotTo(HaveOccurred())
- ```
-- To scaffold webhook configurations:
- ```go
- By("scaffolding mutating and validating webhooks")
- err = kbc.CreateWebhook(
- "--group", kbc.Group,
- "--version", kbc.Version,
- "--kind", kbc.Kind,
- "--defaulting",
- "--programmatic-validation",
- )
- ExpectWithOffset(1, err).NotTo(HaveOccurred())
- ```
diff --git a/docs/book/src/plugins/to-add-optional-features.md b/docs/book/src/plugins/to-add-optional-features.md
index 048a23d8730..6b95e7c02c2 100644
--- a/docs/book/src/plugins/to-add-optional-features.md
+++ b/docs/book/src/plugins/to-add-optional-features.md
@@ -2,7 +2,10 @@
The following plugins are useful to generate code and take advantage of optional features
-| Plugin | Key | Description |
-|-------------------------------------------------------------------------| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [grafana.kubebuilder.io/v1-alpha](grafana-v1-alpha.md) | `grafana/v1-alpha` | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime. |
-| [deploy-image.go.kubebuilder.io/v1-alpha](deploy-image-plugin-v1-alpha) | `deploy-image/v1-alpha` | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image). |
+| Plugin | Key | Description |
+|---------------------------------------------------| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [grafana.kubebuilder.io/v1-alpha][grafana] | `grafana/v1-alpha` | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime. |
+| [deploy-image.go.kubebuilder.io/v1-alpha][deploy] | `deploy-image/v1-alpha` | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image). |
+
+[grafana]: ./available/grafana-v1-alpha.md
+[deploy]: ./available/deploy-image-plugin-v1-alpha.md
\ No newline at end of file
diff --git a/docs/book/src/plugins/to-be-extended.md b/docs/book/src/plugins/to-be-extended.md
index 62fa74b4c96..962eda6f44d 100644
--- a/docs/book/src/plugins/to-be-extended.md
+++ b/docs/book/src/plugins/to-be-extended.md
@@ -1,25 +1,24 @@
-## To help projects using Kubebuilder as Lib to composite new solutions and plugins
+## To be extended
-
+The following plugins are useful for other tools and [External Plugins][external-plugins] which are looking to extend the
+Kubebuilder functionality.
-You can also create your own plugins, see:
+You can use the kustomize plugin, which is responsible for scaffolding the
+kustomize files under `config/`. The base language plugins are responsible
+for scaffolding the necessary Golang files, allowing you to create your
+own plugins for other languages (e.g., [Operator-SDK][sdk] enables
+users to work with Ansible/Helm) or add additional functionality.
-- [Creating your own plugins][create-plugins].
+For example, [Operator-SDK][sdk] has a plugin which integrates the
+projects with [OLM][olm] by adding its own features on top.
-
+| Plugin | Key | Description |
+|--------------------------------------------------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| [kustomize.common.kubebuilder.io/v2][kustomize-plugin] | `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`) |
-Then, see that you can use the kustomize plugin, which is responsible for to scaffold the kustomize files under `config/`, as
-the base language plugins which are responsible for to scaffold the Golang files to create your own plugins to work with
-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/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/
[sdk]: https://github.com/operator-framework/operator-sdk
[olm]: https://olm.operatorframework.io/
-
+[kustomize-plugin]: ./available/kustomize-v2.md
+[external-plugins]: ./extending/external-plugins.md
diff --git a/docs/book/src/plugins/to-scaffold-project.md b/docs/book/src/plugins/to-scaffold-project.md
index c91217191d6..7e1744e94fc 100644
--- a/docs/book/src/plugins/to-scaffold-project.md
+++ b/docs/book/src/plugins/to-scaffold-project.md
@@ -2,6 +2,9 @@
The following plugins are useful to scaffold the whole project with the tool.
-| Plugin | Key | Description |
-|------------------------------------------------------------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [go.kubebuilder.io/v4 - (Default scaffold with Kubebuilder init)](go-v4-plugin.md) | `go/v4` | Scaffold composite by `base.go.kubebuilder.io/v4` and [kustomize.common.kubebuilder.io/v2](kustomize-v2.md). Responsible for scaffolding Golang projects and its configurations. |
+| Plugin | Key | Description |
+|--------------------------------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [go.kubebuilder.io/v4 - (Default scaffold with Kubebuilder init)][go-v4] | `go/v4` | Scaffold composite by `base.go.kubebuilder.io/v4` and [kustomize.common.kubebuilder.io/v2][kustomize-v2]. Responsible for scaffolding Golang projects and its configurations. |
+
+[go-v4]: ./available/go-v4-plugin.md
+[kustomize-v2]: ./available/kustomize-v2.md
\ No newline at end of file