feat: make user-defined plugins discoverable with e.g. kubectl help #116752

xvzf · 2023-03-20T11:34:23Z

What type of PR is this?

/kind feature

What this PR does / why we need it:

Kubectl plugins are a powerful way for extending kubectl, but actually discovering available plugins is hard.
Right now, the only way is to use krew list
, check for kubectl-<plugin-name> executables or use tab-complete.

This PR maps the same behavior of tab-complete to the output of kubectl and kubectl help, including the new command group User-Installed Plugin Commands:.

An example output (with `krew` and `convert` as plugins):

kubectl controls the Kubernetes cluster manager.

 Find more information at: https://kubernetes.io/docs/reference/kubectl/

Basic Commands (Beginner):
  create          Create a resource from a file or from stdin
  expose          Take a replication controller, service, deployment or pod and expose it as a new Kubernetes service
  run             Run a particular image on the cluster
  set             Set specific features on objects

Basic Commands (Intermediate):
  explain         Get documentation for a resource
  get             Display one or many resources
  edit            Edit a resource on the server
  delete          Delete resources by file names, stdin, resources and names, or by resources and label selector

Deploy Commands:
  rollout         Manage the rollout of a resource
  scale           Set a new size for a deployment, replica set, or replication controller
  autoscale       Auto-scale a deployment, replica set, stateful set, or replication controller

Cluster Management Commands:
  certificate     Modify certificate resources.
  cluster-info    Display cluster information
  top             Display resource (CPU/memory) usage
  cordon          Mark node as unschedulable
  uncordon        Mark node as schedulable
  drain           Drain node in preparation for maintenance
  taint           Update the taints on one or more nodes

Troubleshooting and Debugging Commands:
  describe        Show details of a specific resource or group of resources
  logs            Print the logs for a container in a pod
  attach          Attach to a running container
  exec            Execute a command in a container
  port-forward    Forward one or more local ports to a pod
  proxy           Run a proxy to the Kubernetes API server
  cp              Copy files and directories to and from containers
  auth            Inspect authorization
  debug           Create debugging sessions for troubleshooting workloads and nodes
  events          List events

Advanced Commands:
  diff            Diff the live version against a would-be applied version
  apply           Apply a configuration to a resource by file name or stdin
  patch           Update fields of a resource
  replace         Replace a resource by file name or stdin
  wait            Experimental: Wait for a specific condition on one or many resources
  kustomize       Build a kustomization target from a directory or URL

Settings Commands:
  label           Update the labels on a resource
  annotate        Update the annotations on a resource
  completion      Output shell completion code for the specified shell (bash, zsh, fish, or powershell)

User-Installed Plugin Commands:
  convert       The command convert is a plugin installed by the user
  krew          The command krew is a plugin installed by the user

Other Commands:
  api-resources   Print the supported API resources on the server
  api-versions    Print the supported API versions on the server, in the form of "group/version"
  config          Modify kubeconfig files
  plugin          Provides utilities for interacting with plugins
  version         Print the client and server version information

Usage:
  kubectl [flags] [options]

Use "kubectl <command> --help" for more information about a given command.
Use "kubectl options" for a list of global command-line options (applies to all commands).

Which issue(s) this PR fixes:

Fixes #116751

Special notes for your reviewer:

Does this PR introduce a user-facing change?

Changed `kubectl help` to display basic details for subcommands from plugins

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

I did not create a KEP for this change as it doesn't introduce breaking behavior, just a visual change. I'm planning on extending this to improve discovery of plugins by e.g. allowing user-defined descriptions as a KEP.

k8s-ci-robot · 2023-03-20T11:34:32Z

Welcome @xvzf!

It looks like this is your first PR to kubernetes/kubernetes 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/kubernetes has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2023-03-20T11:34:33Z

Hi @xvzf. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

xvzf · 2023-03-20T11:35:26Z

/sig cli

mpuckett159 · 2023-04-03T16:04:42Z

/ok-to-test

Ritikaa96 · 2023-06-06T08:27:27Z

Hi @xvzf Seems like this PR needs a rebase . can you do the same and check for further errors?

xvzf · 2023-06-22T09:12:07Z

Yes, I'll do it this week. Sorry for the long delay, have been busy with work stuff

sftim · 2023-08-21T10:54:27Z

Changelog suggestion:

Changed `kubectl help` to display basic details for subcommands from plugins

staging/src/k8s.io/kubectl/pkg/cmd/plugin/plugin_completion.go

xvzf · 2023-08-22T11:12:39Z

/retest

xvzf · 2023-08-22T11:52:26Z

/test pull-kubernetes-node-e2e-containerd

xvzf · 2023-08-24T08:55:15Z

/test pull-kubernetes-node-e2e-containerd

soltysh

This looks great - thank you for your contribution! I left you one small comment, do you think you can fix that? Once you do, please ping me on slack to get it merged promptly.

soltysh · 2023-09-04T09:34:03Z

staging/src/k8s.io/kubectl/pkg/cmd/plugin/plugin_completion.go

-	streams := genericiooptions.IOStreams{
+// registerPluginCommand allows adding Cobra command to the command tree or extracting them for usage in
+// e.g. the help function or for registering the completion function
+func registerPluginCommands(kubectl *cobra.Command, depth int, register bool) (cmds []*cobra.Command) {


Nit: rather than having 2 arguments depth and register, how about we just add list bool and if that is set it means we only care about the highest level (ie. yours depth = 1 and register = false), when false, we register like in the old days. I don't think we need that much control over the process.

Just did! Lmk if there's anything else please

soltysh · 2023-09-04T09:36:24Z

/assign

Signed-off-by: Matthias Riegler <matthias.riegler@ankorstore.com>

soltysh

/lgtm
/approve

soltysh · 2023-09-06T11:00:31Z

/label tide/merge-method-squash

xvzf · 2023-09-06T11:06:40Z

/remove-lgtm

Signed-off-by: Matthias Riegler <matthias.riegler@ankorstore.com>

xvzf · 2023-09-06T11:55:46Z

/lgtm

k8s-ci-robot · 2023-09-06T11:55:47Z

@xvzf: you cannot LGTM your own PR.

In response to this:

/lgtm

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

xvzf · 2023-09-06T12:54:34Z

/test pull-kubernetes-integration

xvzf · 2023-09-06T12:56:53Z

/test pull-kubernetes-e2e-gce

soltysh

/lgtm

k8s-ci-robot · 2023-09-06T13:06:27Z

LGTM label has been added.

Git tree hash: c7ab4eea20d9c8c0a1540a737a6c5a0b44bced30

k8s-ci-robot · 2023-09-06T13:06:41Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: soltysh, xvzf

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:

~~staging/src/k8s.io/kubectl/OWNERS~~ [soltysh]

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

xvzf · 2023-09-06T14:05:06Z

/retest-required

k8s-ci-robot added needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Mar 20, 2023

k8s-ci-robot added the needs-priority Indicates a PR lacks a `priority/foo` label and requires one. label Mar 20, 2023

k8s-ci-robot requested review from KnVerey and mpuckett159 March 20, 2023 11:34

k8s-ci-robot added the area/kubectl label Mar 20, 2023

k8s-ci-robot added sig/cli Categorizes an issue or PR as relevant to SIG CLI. and removed do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. labels Mar 20, 2023

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Apr 3, 2023

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 12, 2023

xvzf force-pushed the feat/make-plugins-discoverabile-with-kubectl-help branch from 16b60c9 to c47cdd0 Compare June 24, 2023 14:23

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 24, 2023

sftim reviewed Aug 21, 2023

View reviewed changes

staging/src/k8s.io/kubectl/pkg/cmd/plugin/plugin_completion.go Outdated Show resolved Hide resolved

xvzf force-pushed the feat/make-plugins-discoverabile-with-kubectl-help branch from c47cdd0 to babaff8 Compare August 21, 2023 11:10

soltysh reviewed Sep 4, 2023

View reviewed changes

k8s-ci-robot assigned soltysh Sep 4, 2023

xvzf added 2 commits September 6, 2023 12:23

feat: make user-defined plugins discoverable with e.g. kubectl help

927499d

Signed-off-by: Matthias Riegler <matthias.riegler@ankorstore.com>

fix: make help text localizable & rename it

2178fe4

Signed-off-by: Matthias Riegler <matthias.riegler@ankorstore.com>

xvzf force-pushed the feat/make-plugins-discoverabile-with-kubectl-help branch from babaff8 to e14961f Compare September 6, 2023 10:57

chore: address CRs, cleanup

e1cd7a7

Signed-off-by: Matthias Riegler <matthias.riegler@ankorstore.com>

xvzf force-pushed the feat/make-plugins-discoverabile-with-kubectl-help branch from e14961f to e1cd7a7 Compare September 6, 2023 10:59

xvzf requested a review from soltysh September 6, 2023 10:59

soltysh approved these changes Sep 6, 2023

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 6, 2023

k8s-ci-robot added tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Sep 6, 2023

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 6, 2023

k8s-ci-robot requested a review from soltysh September 6, 2023 11:06

fix: plugin execution

f941d1c

Signed-off-by: Matthias Riegler <matthias.riegler@ankorstore.com>

xvzf force-pushed the feat/make-plugins-discoverabile-with-kubectl-help branch from 7200be5 to f941d1c Compare September 6, 2023 11:55

soltysh approved these changes Sep 6, 2023

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 6, 2023

k8s-ci-robot merged commit d7b7a85 into kubernetes:master Sep 6, 2023
14 checks passed

k8s-ci-robot added this to the v1.29 milestone Sep 6, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: make user-defined plugins discoverable with e.g. kubectl help #116752

feat: make user-defined plugins discoverable with e.g. kubectl help #116752

xvzf commented Mar 20, 2023 •

edited

k8s-ci-robot commented Mar 20, 2023

k8s-ci-robot commented Mar 20, 2023

xvzf commented Mar 20, 2023

mpuckett159 commented Apr 3, 2023

Ritikaa96 commented Jun 6, 2023

xvzf commented Jun 22, 2023

sftim commented Aug 21, 2023

xvzf commented Aug 22, 2023

xvzf commented Aug 22, 2023

xvzf commented Aug 24, 2023

soltysh left a comment

soltysh Sep 4, 2023

xvzf Sep 6, 2023

soltysh commented Sep 4, 2023

soltysh left a comment

soltysh commented Sep 6, 2023

xvzf commented Sep 6, 2023

xvzf commented Sep 6, 2023

k8s-ci-robot commented Sep 6, 2023

xvzf commented Sep 6, 2023

xvzf commented Sep 6, 2023

soltysh left a comment

k8s-ci-robot commented Sep 6, 2023

k8s-ci-robot commented Sep 6, 2023

xvzf commented Sep 6, 2023

feat: make user-defined plugins discoverable with e.g. kubectl help #116752

feat: make user-defined plugins discoverable with e.g. kubectl help #116752

Conversation

xvzf commented Mar 20, 2023 • edited

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for your reviewer:

Does this PR introduce a user-facing change?

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

k8s-ci-robot commented Mar 20, 2023

k8s-ci-robot commented Mar 20, 2023

xvzf commented Mar 20, 2023

mpuckett159 commented Apr 3, 2023

Ritikaa96 commented Jun 6, 2023

xvzf commented Jun 22, 2023

sftim commented Aug 21, 2023

xvzf commented Aug 22, 2023

xvzf commented Aug 22, 2023

xvzf commented Aug 24, 2023

/test pull-kubernetes-node-e2e-containerd

soltysh left a comment

Choose a reason for hiding this comment

soltysh Sep 4, 2023

Choose a reason for hiding this comment

xvzf Sep 6, 2023

Choose a reason for hiding this comment

soltysh commented Sep 4, 2023

soltysh left a comment

Choose a reason for hiding this comment

soltysh commented Sep 6, 2023

xvzf commented Sep 6, 2023

xvzf commented Sep 6, 2023

k8s-ci-robot commented Sep 6, 2023

xvzf commented Sep 6, 2023

xvzf commented Sep 6, 2023

soltysh left a comment

Choose a reason for hiding this comment

k8s-ci-robot commented Sep 6, 2023

k8s-ci-robot commented Sep 6, 2023

xvzf commented Sep 6, 2023

xvzf commented Mar 20, 2023 •

edited