✨ add kustomize/v2-alpha plugin to support kustomize versions >= v4 (pinned version 4.5.3)

[camilamacedo86]

Description

✨ add kustomize/v2-alpha plugin to support kustomize versions >= v4

Motivation

• Provides support for the new mac arch (arm64 Mac M1) (kubebuilder init --plugins=kustomize/v2-alpha,base.go.kubebuilder.io/v3)
• Allow users began to experiment and take the advantage of kustomize v4 without introducing breaking changes for who require to stick with v3
• Fix the single responsibility of each plugin. The Kustomize version supported by the scaffolds and used in the Makefile must be defined in the kustomize plugin and not in the golang ones

Notes

• You can check the samples: project-v3-with-kustomize-v2
• You can check that it has been tested on the cluster: new test added in e2e
• For further understanding check the documentation added with this PR

Why can we not upgrade the kustomize stable v1 plugin to use the kustomize v4 version instead of creating a new alpha plugin?

We cannot introduce breaking changes for those who have a project scaffolded previously using kustomize/v1. See that kustomize must bump a major version v4 because it introduces breaking change and does NOT ensure backwards compatibility with the previous versions.

So let's think about the scenario and imagine that:

• A user scaffold a project using our current kustomize/v1 then, the plugin generates the files using the syntax that works with kustomize v3 and not necessarily with v4.
• Now we go there and start to update the (config) the kutomize files to use all advantages of v4 and no longer v3. Therefore, we do our release Kubebuilder CLI 3.Z with the changes.

The user should NOT change their previous scaffolds to be able to still work with KB 3.Z and the plugin already used to scaffold their project kustomize/v1. See the policy: https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/plugins/plugins-versioning.md:

Changes made to plugins only require a plugin version increase if and only if a change is made to a plugin that breaks projects scaffolded with the previous plugin version. Once a plugin version vX is stabilized (it doesn't have an "alpha" or "beta" suffix), a new plugin package should be created containing a new plugin with version v(X+1)-alpha. Typically this is done by (semantically) cp -r pkg/plugins/golang/vX pkg/plugins/golang/v(X+1) then updating version numbers and paths. All further breaking changes to the plugin should be made in this package; the vX plugin would then be frozen to breaking changes.

However, now when they call the command to create api to add its manifests on the project using the go/v3 and kustomize/v1 this subcommand will begin to scaffold the files using the new syntax (valid for kustomize dep v4 and not v3 necessarily) since the project are not implemented to work with kustomize v4 which indeed the user will not have installed locally since its Makefile target should still be downloading kustomize v3 its result will be:

• Old apis scaffolded with kustomize syntax valid for v3
• New apis and webhooks scaffold with syntax valid for v4
• Makefile target downloading any previous version used for kustomize v3 and not v4

That files scaffold with v4 today might work with v3 (not officially supported or guaranteed and etc). However, it can change a lot on the long journey since we can indeed add new features, also we do not know how other projects importing kustomize are using or taking advantage of it. Today it might work but can we ensure that will be the case tomorrow?`

Therefore, that shows for me a breaking change since can break the behaviour of any plugin language which has been using kustomize stable plugin v1 with kustomize v3 syntax as its binary.

See the policy example:

Example: 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 must also add a migration guide to the migrations section of the Kubebuilder book in your PR. It should detail the steps required for users to upgrade their projects from vX to v(X+1)-alpha.

That shows our case here, we will need to let the users know what they need to do in their scaffolded project using kustomize/v1 with the syntax that works with the kustomize binary version v3 to then be able to work with v4 when this new kustomize/v2-alpha plugin becomes to be kustomize/v2 stable)

Do we not bump go versions? Why it is different?

So we bump the go versions, which means any new project scaffold using a new version of the plugin bumped with go 1.18 will have the go mod using go 1.18 with its deps. However, users that scaffold using go 1.15, for example, will NOT be affected by that, they do not need to change anything to be able to work with KB 3.Z and its new version of the go/v3 plugin, for example, they still able to run create api and create webhook for the project scaffolded with any previous 3.Z version and using any previous go version supported.

Closes: #2566
Closes: #2503

Motivations

• Support Apple Silicon (darwin/amd64)
• Begin to be able to scaffold and use the new kustomize v4 to take advantage of its features for the default scaffold ( it has more than a year )
• Begin to provide kustomize v4 with Kubebuilder ( See: Produce darwin/arm64 binaries for v3 kustomize#4612 (comment) / v4 is more than a year old now, and kustomize do not currently have a long-term support policy for v3 )

Co -author: @afritzler

[camilamacedo86]

See here the documentation to better understand it.
Note that after we have this plugin, tools such as SDK (which provides many language plugins) will also be able to allow its users to try out kustomize v4 and support the new mac arch, doing things like:

operator-sdk init --plugins=kustomize/v2-alpha,base.operatorframework.helm.sdk/v1

Then, we can provide all support and advantages to the users without introducing breaking changes.
So that, when the plugins become mature and we no longer need to support k8s versions < 1.22 then we might want to have new languages plugins that adopt them by default.

c/c @jmrodri

[camilamacedo86]

The kustomize version supported by the Kustomize plugin must leave in the Kustomize plugin. Otherwise, we are hurting concepts like single responsibility and cohesion.

[camilamacedo86]

Here is where we check if the kustomize/v2-alpha plugin was used in the chain to properly define what version of the kustomize should be added to the Makefile which is generated by the plugin language.

The language plugin is not responsible for the kustomize and it needs to ensure that will pin in the Makefile target to install the bin locally the version which was used by the kustomize plugin used with.

[camilamacedo86]

Here we have the test to check the new plugin scaffold working on the cluster with go/v3 one.

[camilamacedo86]

This is the line where we scaffold the sample under the testdata

[rashmigottipati]

cc @AlmogBaku

[aemperador]

@camilamacedo86 @afritzler @rashmigottipati what is the projected timeframe for release of this PR after merge? we have been waiting for this update to support ppc64le as well to update kustomize to v4 in an external app

[everettraven]

Everything looks good to me. Just one minor docs typo.

[rashmigottipati]

Changes look good to me.

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86, everettraven, rashmigottipati

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment