📖 Update book-v3 with latest docs fixes and release-3.10 branch with …

…conflicts solved (#3349) We addressed some docs fixes into master, which was synced with release-3.10 So that we can merge release-3.10 to book-v3 to update the prod docs and solve the conflicts. See that is the release-3.10 branch with the solved conflicts with book-v3.
kubernetes-sigs · Apr 21, 2023 · 315e90f · 315e90f
1 parent 918af6d
commit 315e90f
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 63 deletions.
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -124,7 +124,7 @@
       - [deploy-image/v1-alpha](./plugins/deploy-image-plugin-v1-alpha.md)
     - [To be extended for others tools](./plugins/to-be-extended.md)
       - [kustomize/v1 (Deprecated)](./plugins/kustomize-v1.md)
-      - [kustomize/v2-alpha](./plugins/kustomize-v2-alpha.md)
+      - [kustomize/v2](./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)

diff --git a/docs/book/src/migration/v3vsv4.md b/docs/book/src/migration/v3vsv4.md
@@ -34,12 +34,6 @@ Further details can be found in the [go/v4 plugin section][go/v4-doc]
 
 **_More details on this can be found at [here][kb-releases], but for the highlights, check below_**
 
-<aside class="note">
-<h1>Default plugin</h1>
-Projects scaffolded with Kubebuilder v3 release still using the `go.kubebuilder.io/v3` plugin by default.
-
-</aside>
-
 <aside class="note warning">
 <h1>Project customizations</h1>
 
@@ -55,21 +49,6 @@ If you want to upgrade your scaffolding to use the latest and greatest features
 which will cover the steps in the most straightforward way to allow you to upgrade your project to get all
 latest changes and improvements.
 
-<aside class="note warning">
-<h1> Apple Silicon (M1) </h1>
-
-The current scaffold done by the CLI (`go/v3`) uses [kubernetes-sigs/kustomize][kustomize] v3 which does not provide
-a valid binary for Apple Silicon (`darwin/arm64`). Therefore, you can use the `go/v4` plugin
-instead which provides support for this platform:
-
-```bash
-kubebuilder init --domain my.domain --repo my.domain/guestbook --plugins=go/v4
-```
-
-**Note**: The `go/v4` plugin is an unstable version and can have breaking changes in future releases.
-
-</aside>
-
 - [Migration Guide go/v3 to go/v4][migration-guide-gov3-to-gov4] **(Recommended)**
 
 ### By updating the files manually
@@ -88,4 +67,8 @@ This way is more complex, susceptible to errors, and success cannot be assured.
 [go/v4-doc]: ./../plugins/go-v4-plugin.md
 [migration-guide-gov3-to-gov4]: migration_guide_gov3_to_gov4.md
 [manually-upgrade]: manually_migration_guide_gov3_to_gov4.md
-[standard-go-project]: https://github.com/golang-standards/project-layout
+[standard-go-project]: https://github.com/golang-standards/project-layout
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[controller-tools]: https://github.com/kubernetes-sigs/controller-tools
+[kustomize-release]: https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv5.0.0
+[kb-releases]: https://github.com/kubernetes-sigs/kubebuilder/releases
diff --git a/docs/book/src/plugins/go-v4-plugin.md b/docs/book/src/plugins/go-v4-plugin.md
@@ -1,7 +1,8 @@
-# go/v4 (go.kubebuilder.io/v4)
+# [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-alpha` and `base.go.kubebuilder.io/v4`. 
+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. 
@@ -17,15 +18,7 @@ under the [testdata][testdata] directory on the root directory of the Kubebuilde
 
 ## When to use it ?
 
-- If you are looking to scaffold Golang projects to develop projects using [controllers][controller-runtime]
-- If you are looking to experiment with the future default scaffold that will be provided by Kubebuilder CLI
-- If your local environment is Apple Silicon (`darwin/arm64`)
-- If you are looking to use [kubernetes-sigs/kustomize][kustomize] v5
-- If you are looking to have your project update with the latest version available
-- if you are not targeting k8s versions < `1.16` and `1.20` if you are using webhooks
-- If you are looking to work on with scaffolds which are compatible with k8s `1.25+`
-- If you are looking for the new layout following the [Standard Go Project Layout][standard-go-project] where 
-the "api(s)" are scaffold under the `api` directory, "controller(s)" under `internal`, and the `main.go` under `cmd`
+If you are looking to scaffold Golang projects to develop projects using [controllers][controller-runtime]
 
 <aside class="note">
 
@@ -54,7 +47,7 @@ kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io
 ## 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/v3`][v3-plugin].
+- 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.
 
@@ -65,3 +58,5 @@ kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io
 [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/kustomize-v1.md b/docs/book/src/plugins/kustomize-v1.md
@@ -1,4 +1,16 @@
-# Kustomize (kustomize/v1)
+# [Deprecated] Kustomize (kustomize/v1)
+
+<aside class="note warning">
+<h1>Deprecated</h1>
+
+The kustomize/v1 plugin is deprecated. If you are using this plugin, it is recommended
+to migrate to the kustomize/v2 plugin which uses Kustomize v5 and provides support for
+Apple Silicon (M1).
+
+If you are using Golang projects scaffolded with `go/v3` which uses this version please, check 
+the [Migration guide](../migration/v3vsv4.md) to learn how to upgrade your projects.
+
+</aside>
 
 <aside class="note warning">
 <h1>Deprecated</h1>

diff --git a/docs/book/src/plugins/kustomize-v2.md b/docs/book/src/plugins/kustomize-v2.md
@@ -1,6 +1,7 @@
-# Kustomize v2 
+# [Default Scaffold] Kustomize v2 
 
-The kustomize plugin allows you to scaffold all kustomize manifests used to work with the language base plugin `base.go.kubebuilder.io/v3`.
+The kustomize plugin allows you to scaffold all kustomize manifests used to work with the language base plugin `base.go.kubebuilder.io/v4`.
+This plugin is used to generate the manifest under `config/` directory for the projects build within the go/v4 plugin (default scaffold).
 
 Note that projects such as [Operator-sdk][sdk] consume the Kubebuilder project as a lib and provide options to work with other languages
 like Ansible and Helm. The kustomize plugin allows them to easily keep a maintained configuration and ensure that all languages have
@@ -21,7 +22,7 @@ directory of the Kubebuilder project.
 
 - If you are looking to scaffold the kustomize configuration manifests for your own language plugin
 - If you are looking for support on Apple Silicon (`darwin/arm64`). (_Before kustomize `4.x` the binary for this plataform is not provided_)
-- If you are looking for to begin to try out the new syntax and features provide by kustomize v5
+- If you are looking for to begin to try out the new syntax and features provide by kustomize v4 [(More info)][release-notes-v4] and v5 [(More info)][release-notes-v5]
 - If you are NOT looking to build projects which will be used on Kubernetes cluster versions < `1.22` (_The new features provides by kustomize v4 are not officially supported and might not work with kubectl < `1.22`_)
 - If you are NOT looking to rely on special URLs in resource fields
 - If you want to use [replacements][kustomize-replacements] since [vars][kustomize-vars] are deprecated and might be removed soon
@@ -36,7 +37,7 @@ all that is language specific and kustomize for its configuration, see:
 import (
 ...
    kustomizecommonv2alpha "sigs.k8s.io/kubebuilder/v3/pkg/plugins/common/kustomize/v2"
-   golangv3 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v3"
+   golangv4 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v4"
 ...
 )
 
@@ -45,7 +46,7 @@ import (
 	// You can define that one plugin is composite by 1 or Many others plugins
 	gov3Bundle, _ := plugin.NewBundle(golang.DefaultNameQualifier, plugin.Version{Number: 3},
         kustomizecommonv2.Plugin{}, // scaffold the config/ directory and all kustomize files
-		golangv3.Plugin{}, // Scaffold the Golang files and all that specific for the language e.g. go.mod, apis, controllers
+		golangv4.Plugin{}, // Scaffold the Golang files and all that specific for the language e.g. go.mod, apis, controllers
 	)
 ```
 
@@ -98,7 +99,8 @@ The following scaffolds will be created or updated by this plugin:
 * 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]
-* To know more about the changes between kustomize v4 and v5 see its [release notes][release-notes]
+* Check the [release notes][release-notes-v5] for Kustomize v5.0.0
+* Check the [release notes][release-notes-v4] for Kustomuze v4.0.0
 * Also, you can compare the `config/` directory between the samples `project-v3` and `project-v4` to check the difference in the syntax of the manifests provided by default
 
 [sdk]:https://github.com/operator-framework/operator-sdk
@@ -109,4 +111,6 @@ The following scaffolds will be created or updated by this plugin:
 [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]: https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv5.0.0
+[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
+
diff --git a/docs/book/src/reference/project-config.md b/docs/book/src/reference/project-config.md
@@ -2,7 +2,74 @@
 
 ## Overview
 
-The Project Config represents the configuration of a Kubebuilder project. All projects that are scaffolded with the CLI will generate the `PROJECT` file in the projects' root directory.
+The Project Config represents the configuration of a KubeBuilder project. All projects that are scaffolded with the CLI (KB version 3.0 and higher) will generate the `PROJECT` file in the projects' root directory. Therefore, it will store all plugins and input data used to generate the project and APIs to better enable plugins to make useful decisions when scaffolding.
+
+## Example
+
+Following is an example of a PROJECT config file which is the result of a project generated with two APIs using the [Deploy Image Plugin][deploy-image-plugin].
+
+```yaml
+# Code generated by tool. DO NOT EDIT.
+# This file is used to track the info used to scaffold your project
+# and allow the plugins properly work.
+# More info: https://book.kubebuilder.io/reference/project-config.html
+domain: testproject.org
+layout:
+  - go.kubebuilder.io/v4
+plugins:
+  deploy-image.go.kubebuilder.io/v1-alpha:
+    resources:
+      - domain: testproject.org
+        group: example.com
+        kind: Memcached
+        options:
+          containerCommand: memcached,-m=64,-o,modern,-v
+          containerPort: "11211"
+          image: memcached:1.4.36-alpine
+          runAsUser: "1001"
+        version: v1alpha1
+      - domain: testproject.org
+        group: example.com
+        kind: Busybox
+        options:
+          image: busybox:1.28
+        version: v1alpha1
+projectName: project-v4-with-deploy-image
+repo: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image
+resources:
+  - api:
+      crdVersion: v1
+      namespaced: true
+    controller: true
+    domain: testproject.org
+    group: example.com
+    kind: Memcached
+    path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
+    version: v1alpha1
+    webhooks:
+      validation: true
+      webhookVersion: v1
+  - api:
+      crdVersion: v1
+      namespaced: true
+    controller: true
+    domain: testproject.org
+    group: example.com
+    kind: Busybox
+    path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
+    version: v1alpha1
+version: "3"
+```
+## Why do we need to store the plugins and data used?
+
+Following some examples of motivations to track the input used:
+- check if a plugin can or cannot be scaffolded on top of an existing plugin (i.e.) plugin compatibility while chaining multiple of them together.
+- what operations can or cannot be done such as verify if the layout allow API(s) for different groups to be scaffolded for the current configuration or not.
+- verify what data can or not be used in the CLI operations such as to ensure that WebHooks can only be created for pre-existent API(s)
+
+Note that KubeBuilder is not only a CLI tool but can also be used as a library to allow users to create their plugins/tools, provide helpers and customizations on top of their existing projects - an example of which is [Operator-SDK][operator-sdk]. SDK leverages KubeBuilder to create plugins to allow users to work with other languages and provide helpers for their users to integrate their projects with, for example, the [Operator Framework solutions/OLM][olm]. You can check the [plugin's documentation][plugins-doc] to know more about creating custom plugins.
+
+Additionally, another motivation for the PROJECT file is to help us to create a feature that allows users to easily upgrade their projects by providing helpers that automatically re-scaffold the project. By having all the required metadata regarding the APIs, their configurations and versions in the PROJECT file. For example, it can be used to automate the process of re-scaffolding while migrating between plugin versions. ([More info][doc-design-helper]).
 
 ## Versioning
 
@@ -15,30 +82,30 @@ The `PROJECT` version `3` layout looks like:
 ```yaml
 domain: testproject.org
 layout:
-- go.kubebuilder.io/v3
+  - go.kubebuilder.io/v3
 plugins:
   declarative.go.kubebuilder.io/v1:
     resources:
-    - domain: testproject.org
-      group: crew
-      kind: FirstMate
-      version: v1
+      - domain: testproject.org
+        group: crew
+        kind: FirstMate
+        version: v1
 projectName: example
 repo: sigs.k8s.io/kubebuilder/example
 resources:
-- api:
-    crdVersion: v1
-    namespaced: true
-  controller: true
-  domain: testproject.org
-  group: crew
-  kind: Captain
-  path: sigs.k8s.io/kubebuilder/example/api/v1
-  version: v1
-  webhooks:
-    defaulting: true
-    validation: true
-    webhookVersion: v1
+  - api:
+      crdVersion: v1
+      namespaced: true
+    controller: true
+    domain: testproject.org
+    group: crew
+    kind: Captain
+    path: sigs.k8s.io/kubebuilder/example/api/v1
+    version: v1
+    webhooks:
+      defaulting: true
+      validation: true
+      webhookVersion: v1
 ```
 
 Now let's check its layout fields definition:
@@ -68,4 +135,9 @@ Now let's check its layout fields definition:
 
 [project]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v3/PROJECT
 [versioning]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/VERSIONING.md#Versioning
-[core-types]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/options.go
+[core-types]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/options.go
+[deploy-image-plugin]: ../plugins/deploy-image-plugin-v1-alpha.md
+[olm]: https://olm.operatorframework.io/
+[plugins-doc]: ../plugins/creating-plugins.html#why-use-the-kubebuilder-style
+[doc-design-helper]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/helper_to_upgrade_projects_by_rescaffolding.md
+[operator-sdk]: https://sdk.operatorframework.io/