Merge pull request #1895 from estroz/feature/unstable-plugin-warn

📖 docs,cli: improve migration docs and CLI warnings

docs/book/src/SUMMARY.md

@@ -59,11 +59,17 @@
 
   - [Kubebuilder v1 vs v2](./migration/v1vsv2.md)
 
-      - [Migration Guide](./migration/migration_guide_v1tov2.md)
+      - [Migration Guide](./migration/legacy/migration_guide_v1tov2.md)
 
   - [Kubebuilder v2 vs v3](./migration/v2vsv3.md)
 
-      - [Migration Guide](./migration/migration_guide_v2tov3.md)
+  - [Project Version Migration Guide](./migration/project/projects.md)
+
+    - [v2 to v3](./migration/project/v2_v3.md)
+
+  - [Plugin Version Migration Guide](./migration/plugin/plugins.md)
+
+    - [v2 to v3](./migration/plugin/v2_v3.md)
 
   - [Single Group to Multi-Group](./migration/multi-group.md)
 

docs/book/src/migration/plugin/plugins.md

@@ -0,0 +1,9 @@
+# Plugin Migrations
+
+Migrating between project [plugins][plugins-doc] involves additions, removals, and/or changes
+to files created by any plugin-supported command, ex. `init` and `create`. A plugin supports
+one or more project config versions; make sure you [upgrade][project-migration] your project's
+config version to the latest supported by your target plugin version before upgrading plugin versions.
+
+[plugins-doc]:/reference/cli-plugins.md
+[project-migration]:/migration/projects.md

docs/book/src/migration/plugin/v2_v3.md

@@ -0,0 +1,3 @@
+# Migration from `go.kubebuilder.io` v2 to v3
+
+TODO

docs/book/src/migration/project/projects.md

@@ -0,0 +1,4 @@
+# Project config Migrations
+
+Migrating between project configuration versions involves additions, removals, and/or changes
+to fields in your project's `PROJECT` file, which is created by running the `init` command.

docs/book/src/migration/migration_guide_v2tov3.md → docs/book/src/migration/project/v2_v3.md

@@ -1,17 +1,17 @@
-# Migration from v2 to v3
+# Migration from project config v2 to v3
 
-Make sure you understand the [differences between Kubebuilder v2 and v3](./v2vsv3.md)
+Make sure you understand the [differences between Kubebuilder v2 and v3](/migration/v2vsv3.md)
 before continuing
 
 Please ensure you have followed the [installation guide](/quick-start.md#installation)
 to install the required components.
 
-## Steps to migrate to v3 project layout
+## Steps to migrate
 
 <aside class="note warning">
 <h1>Note</h1>
 
-The following steps will be based on the [QuickStart][QuickStart] steps. 
+The following steps will be based on the [QuickStart][QuickStart] steps.
 
 </aside>
 
@@ -29,7 +29,7 @@ projectName: example
 
 - Add the `layout`
 
-The default plugin layout which is equivalent to the previous versions is `go.kubebuilder.io/v2`: 
+The default plugin layout which is equivalent to the previous versions is `go.kubebuilder.io/v2`:
 
 ```
 ...
@@ -72,9 +72,9 @@ fine.
 
 <h1>Note</h1>
 
-`v3+` plugins are still in alpha phase and are not scaffolded by default. You are able to use them, try it out and get all improvements made so far by initializing projects with the arg `--plugins=go.kubebuilder.io/v3-alpha`: 
+`v3+` plugins are still in alpha phase and are not scaffolded by default. You are able to use them, try it out and get all improvements made so far by initializing projects with the arg `--plugins=go.kubebuilder.io/v3-alpha`:
 
-```sh 
+```sh
 kubebuilder init --domain my.domain --plugins=go.kubebuilder.io/v3-alpha
 ```
 
@@ -91,15 +91,15 @@ Currently, the plugin `v3-alpha` has NO breaking changes. However, until it is d
 - [Set preserveUnknownFields to false in the CRD conversion webhook patch #933](https://github.com/kubernetes-sigs/kubebuilder/issues/933)
 - [Migrate existing KB project to v1 CRDs and Webhooks with minimal user effort #1065
 ](https://github.com/kubernetes-sigs/kubebuilder/issues/1065)
-   
+
 </aside>
 
 ### Update your PROJECT file
 
-Update the `layout` setting to the new plugin version ` go.kubebuilder.io/v3-alpha` as follows: 
+Update the `layout` setting to the new plugin version ` go.kubebuilder.io/v3-alpha` as follows:
 
 ```sh
- $ cat PROJECT 
+ $ cat PROJECT
 domain: my.domain
 layout: go.kubebuilder.io/v3-alpha
 projectName: example
@@ -118,21 +118,21 @@ version: 3-alpha
 
 <h1>Note</h1>
 
-The following changes are NOT breaking changes. In this way, these changes are optional but recommended in order to keep your project up-to-date with the latest changes made so far. 
+The following changes are NOT breaking changes. In this way, these changes are optional but recommended in order to keep your project up-to-date with the latest changes made so far.
 
 </aside>
 
 #### Manager Rootless
 
 The projects built with v3+ plugin now define a specific `user ID` and `securityContext` policy to prevent root privilege escalation from the manager container.
-  
+
 - Update your Dockerfile to define an ID for the user used:
 
 Replace:
 
 ```
 USER nonroot:nonroot
-``` 
+```
 
 With:
 
@@ -148,7 +148,7 @@ spec:
       securityContext:
         runAsUser: 65532
 ...
-``` 
+```
 
 ```yaml
 ...
@@ -160,7 +160,7 @@ securityContext:
 
 The final result would look like:
 
-```yaml 
+```yaml
 ...
 apiVersion: apps/v1
 kind: Deployment
@@ -213,7 +213,7 @@ From now on, the scaffolded roles include finalizer permissions ([more info](htt
   verbs:
   - update
 ...
-``` 
+```
 
 Also, the following `configmaps/status` permission is no longer scaffolded since they are invalid. Feel free to remove it from your `role.yaml` file in `config/rbac/` directory:
 

docs/book/src/migration/v2vsv3.md

@@ -6,9 +6,17 @@ The details of all changes (breaking or otherwise) can be found in [kubebuilder]
 
 ## Kubebuilder
 
-- A plugin design was introduced to the project. For more info see the [Extensible CLI and Scaffolding Plugins][plugins-phase1-design-doc]   
-- The GO supported version was upgraded from 1.13+ to 1.15+    
+- A plugin design was introduced to the project. For more info see the [Extensible CLI and Scaffolding Plugins][plugins-phase1-design-doc]
+- The GO supported version was upgraded from 1.13+ to 1.15+
 
-[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md
+## Project config versions
+
+- [v3][project-v3]
 
+## `go.kubebuilder.io` plugin versions
 
+- [v3][plugin-v3]
+
+[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md
+[project-v3]:/migration/project/v2_v3.md
+[plugin-v3]:/migration/plugin/v2_v3.md

docs/book/src/migrations.md

@@ -6,5 +6,3 @@ a bit of manual work.
 This section details what's required to migrate, between different
 versions of KubeBuilder scaffolding, as well as to more complex project
 layout structures.
-- 
-- 

pkg/cli/cli.go

@@ -296,13 +296,31 @@ func (c *cli) getInfo() error {
 	return err
 }
 
+// TODO(estroz): link a plugin-specific migration guide.
+const unstablePluginMsg = " (plugin version is unstable, there may be an upgrade available: " +
+	"https://kubebuilder.io/migration/plugin/plugins.html)"
+
 // resolve selects from the available plugins those that match the project version and plugin keys provided.
 func (c *cli) resolve() error {
 	var plugins []plugin.Plugin
 	for _, pluginKey := range c.pluginKeys {
 		name, version := plugin.SplitKey(pluginKey)
 		shortName := plugin.GetShortName(name)
 
+		// Plugins are often released as "unstable" (alpha/beta) versions, then upgraded to "stable".
+		// This upgrade effectively removes a plugin, which is fine because unstable plugins are
+		// under no support contract. However users should be notified _why_ their plugin cannot be found.
+		var extraErrMsg string
+		if version != "" {
+			ver, err := plugin.ParseVersion(version)
+			if err != nil {
+				return fmt.Errorf("error parsing input plugin version from key %q: %v", pluginKey, err)
+			}
+			if !ver.IsStable() {
+				extraErrMsg = unstablePluginMsg
+			}
+		}
+
 		var resolvedPlugins []plugin.Plugin
 		isFullName := shortName != name
 		hasVersion := version != ""
@@ -312,7 +330,7 @@ func (c *cli) resolve() error {
 		case isFullName && hasVersion:
 			p, isKnown := c.plugins[pluginKey]
 			if !isKnown {
-				return fmt.Errorf("unknown fully qualified plugin %q", pluginKey)
+				return fmt.Errorf("unknown fully qualified plugin %q%s", pluginKey, extraErrMsg)
 			}
 			if !plugin.SupportsVersion(p, c.projectVersion) {
 				return fmt.Errorf("plugin %q does not support project version %q", pluginKey, c.projectVersion)
@@ -358,8 +376,8 @@ func (c *cli) resolve() error {
 		// Only 1 plugin can match
 		switch len(resolvedPlugins) {
 		case 0:
-			return fmt.Errorf("no plugin could be resolved with key %q for project version %q",
-				pluginKey, c.projectVersion)
+			return fmt.Errorf("no plugin could be resolved with key %q for project version %q%s",
+				pluginKey, c.projectVersion, extraErrMsg)
 		case 1:
 			plugins = append(plugins, resolvedPlugins[0])
 		default:

pkg/plugin/version.go

@@ -158,3 +158,8 @@ func (v Version) Compare(other Version) int {
 
 	return v.Stage.Compare(other.Stage)
 }
+
+// IsStable returns true if v is stable.
+func (v Version) IsStable() bool {
+	return v.Stage.Compare(StableStage) == -1
+}