Phase 2 Plugins should allow for external plugin authors to define metadata and examples

[everettraven]

What do you want to happen?

Problem

In the current Phase 2 Plugins implementation, external plugin authors are not able to define the subcommand metadata and examples that are output by Kubebuilder when running something like kubebuilder init --plugins myexternalplugin/v1 --help.

Instead the output is this general message:

INFO[0000] Adding external plugin: myexternalplugin     
Initialize a new project.

For further help about a specific plugin, set --plugins.

Usage:
  kubebuilder init [flags]

Examples:
  # Help for initializing a project with version "2"
  kubebuilder init --project-version="2" -h

  # Help for initializing a project with version "3"
  kubebuilder init --project-version="3" -h

Flags:
  -h, --help                     help for init
      --project-version string   project version (default "3")

Global Flags:
      --plugins strings   plugin keys to be used for this subcommand execution

There should be a way for external plugin authors to set the metadata and examples for their external plugin so that Kubebuilder can offer a similar experience to its users for external plugins as it does for the native plugins. For example, the go/v3 help output is much more descriptive like so:

Initialize a new project including the following files:
  - a "go.mod" with project dependencies
  - a "PROJECT" file that stores project configuration
  - a "Makefile" with several useful make targets for the project
  - several YAML files for project deployment under the "config" directory
  - a "main.go" file that creates the manager that will run the project controllers

Usage:
  kubebuilder init [flags]

Examples:
  # Initialize a new project with your domain and name in copyright
  kubebuilder init --plugins go/v3 --domain example.org --owner "Your name"

  # Initialize a new project defining a specific project version
  kubebuilder init --plugins go/v3 --project-version 3


Flags:
      --component-config         create a versioned ComponentConfig file, may be 'true' or 'false'
      --domain string            domain for groups (default "my.domain")
      --fetch-deps               ensure dependencies are downloaded (default true)
  -h, --help                     help for init
      --license string           license to use to boilerplate, may be one of 'apache2', 'none' (default "apache2")
      --owner string             owner to add to the copyright
      --project-name string      name of this project
      --project-version string   project version (default "3")
      --repo string              name to use for go module (e.g., github.com/user/repo), defaults to the go package of the current working directory.
      --skip-go-version-check    if specified, skip checking the Go version

Global Flags:
      --plugins strings   plugin keys to be used for this subcommand execution

Proposed Solution

I propose that a solution similar to this be implemented:

flowchart TD
    A[UpdateMetadata] --> B[Call External Plugin to get Metadata & Examples];
    B ----> C{Error?};
    C -- Yes --> D[generic metadata pointing to external plugin documentation];
    C -- No --> E[UpdateMetadata as per external plugin response];
    D ----> F[Show Metadata on help];
    E ----> F;

Loading

This would allow external plugin authors to define metadata and examples to show when Kubebuilder shows a help message, or if and external plugin author does not define this logic Kubebuilder can recommend to a user to consult the external plugin documentation for further help.

This allows for Kubebuilder to offer a UX feel similar to the native plugins for Phase 2 Plugins.

Extra Labels

No response

[everettraven]

/cc @rashmigottipati

I would like to work on this if this feature is accepted.

[camilamacedo86]

I think that is great. +1

[rashmigottipati]

Great idea @everettraven, thanks for creating and working on this issue!
/assign @everettraven

[everettraven]

I believe @theishshah was interested in working on this issue, so I am happy to be a point of contact for this issue and instead have @theishshah assigned to this issue.