From 870fa6ffda446428030de73946e187ff5e81fce4 Mon Sep 17 00:00:00 2001 From: Eric Stroczynski Date: Thu, 10 Dec 2020 12:18:06 -0800 Subject: [PATCH] docs/book/src/migration: reorganize migration section so project and plugin version upgrades are in separate paths pkg/cli/cli.go: add upgrade directions if plugin resolution fails on an unstable plugin pkg/plugin/version.go: add the IsUnstable() helper --- docs/book/src/SUMMARY.md | 10 ++++-- .../{ => legacy}/migration_guide_v1tov2.md | 0 docs/book/src/migration/plugin/plugins.md | 9 ++++++ docs/book/src/migration/plugin/v2_v3.md | 3 ++ docs/book/src/migration/project/projects.md | 4 +++ .../v2_v3.md} | 32 +++++++++---------- docs/book/src/migration/v2vsv3.md | 14 ++++++-- docs/book/src/migrations.md | 2 -- pkg/cli/cli.go | 24 ++++++++++++-- pkg/plugin/version.go | 5 +++ 10 files changed, 77 insertions(+), 26 deletions(-) rename docs/book/src/migration/{ => legacy}/migration_guide_v1tov2.md (100%) create mode 100644 docs/book/src/migration/plugin/plugins.md create mode 100644 docs/book/src/migration/plugin/v2_v3.md create mode 100644 docs/book/src/migration/project/projects.md rename docs/book/src/migration/{migration_guide_v2tov3.md => project/v2_v3.md} (94%) diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 1e33a46f139..bc77fb92ef2 100644 --- a/docs/book/src/SUMMARY.md +++ b/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) diff --git a/docs/book/src/migration/migration_guide_v1tov2.md b/docs/book/src/migration/legacy/migration_guide_v1tov2.md similarity index 100% rename from docs/book/src/migration/migration_guide_v1tov2.md rename to docs/book/src/migration/legacy/migration_guide_v1tov2.md diff --git a/docs/book/src/migration/plugin/plugins.md b/docs/book/src/migration/plugin/plugins.md new file mode 100644 index 00000000000..a2c57220c10 --- /dev/null +++ b/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 diff --git a/docs/book/src/migration/plugin/v2_v3.md b/docs/book/src/migration/plugin/v2_v3.md new file mode 100644 index 00000000000..dbbc7b515c4 --- /dev/null +++ b/docs/book/src/migration/plugin/v2_v3.md @@ -0,0 +1,3 @@ +# Migration from `go.kubebuilder.io` v2 to v3 + +TODO diff --git a/docs/book/src/migration/project/projects.md b/docs/book/src/migration/project/projects.md new file mode 100644 index 00000000000..0ca87551096 --- /dev/null +++ b/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. diff --git a/docs/book/src/migration/migration_guide_v2tov3.md b/docs/book/src/migration/project/v2_v3.md similarity index 94% rename from docs/book/src/migration/migration_guide_v2tov3.md rename to docs/book/src/migration/project/v2_v3.md index f389456ec50..2fe2340334d 100644 --- a/docs/book/src/migration/migration_guide_v2tov3.md +++ b/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 @@ -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.

Note

-`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) - + ### 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

Note

-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. #### 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: diff --git a/docs/book/src/migration/v2vsv3.md b/docs/book/src/migration/v2vsv3.md index a4bf728e54b..a025ba6de2b 100644 --- a/docs/book/src/migration/v2vsv3.md +++ b/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 diff --git a/docs/book/src/migrations.md b/docs/book/src/migrations.md index 3a4b3af3546..3c5fe6c4aa7 100644 --- a/docs/book/src/migrations.md +++ b/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. -- -- diff --git a/pkg/cli/cli.go b/pkg/cli/cli.go index c01b7e8c184..ffb10a84d1f 100644 --- a/pkg/cli/cli.go +++ b/pkg/cli/cli.go @@ -296,6 +296,10 @@ 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 @@ -303,6 +307,20 @@ func (c *cli) resolve() error { 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: diff --git a/pkg/plugin/version.go b/pkg/plugin/version.go index 251c635d4f6..1196afdce1e 100644 --- a/pkg/plugin/version.go +++ b/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 +}