⚠️ This is an automatically published staged repository for Kubernetes.
Contributions, including issues and pull requests, should be made to the main Kubernetes repository: https://github.com/kubernetes/kubernetes.
This repository is read-only for importing, and not used for direct contributions.
See CONTRIBUTING.md for more details.

This repository implements a single kubectl plugin for switching the namespace that the current KUBECONFIG context points to. In order to remain as indestructive as possible, no existing contexts are modified.

Note: go-get or vendor this package as k8s.io/sample-cli-plugin.

This particular example demonstrates how to perform basic operations such as:

• How to create a new custom command that follows kubectl patterns
• How to obtain a user's KUBECONFIG settings and modify them
• How to make general use of the provided "cli-runtime" set of helpers for kubectl and third-party plugins

It makes use of the genericclioptions in k8s.io/cli-runtime to generate a set of configuration flags which are in turn used to generate a raw representation of the user's KUBECONFIG, as well as to obtain configuration which can be used with RESTClients when sending requests to a kubernetes api server.

The sample cli plugin uses the client-go library to patch an existing KUBECONFIG file in a user's environment in order to update context information to point the client to a new or existing namespace.

In order to be as non-destructive as possible, no existing contexts are modified in any way. Rather, the current context is examined, and matched against existing contexts to find a context containing the same "AuthInfo" and "Cluster" information, but with the newly desired namespace requested by the user.

This is an example of how to build a kubectl plugin using the same set of tools and helpers available to kubectl.

# assumes you have a working KUBECONFIG $ go build cmd/kubectl-ns.go # place the built binary somewhere in your PATH $ cp ./kubectl-ns /usr/local/bin # you can now begin using this plugin as a regular kubectl command: # update your configuration to point to "new-namespace" $ kubectl ns new-namespace # any kubectl commands you perform from now on will use "new-namespace" $ kubectl get pod NAME READY STATUS RESTARTS AGE new-namespace-pod 1/1 Running 0 1h # list all of the namespace in use by contexts in your KUBECONFIG $ kubectl ns --list # show the namespace that the currently set context in your KUBECONFIG points to $ kubectl ns

This plugin can be used as a developer tool, in order to quickly view or change the current namespace that kubectl points to.

It can also be used as a means of showcasing usage of the cli-runtime set of utilities to aid in third-party plugin development.

This plugin supports shell completion when used through kubectl. To enable shell completion for the plugin you must copy the file ./kubectl_complete-ns somewhere on $PATH and give it executable permissions.

The ./kubectl_complete-ns script shows a hybrid approach to providing completions:

1. it uses the builtin __complete command provided by Cobra for flags
2. it calls kubectl to obtain the list of namespaces to complete arguments (note that a more elegant approach would be to have the kubectl-ns program itself provide completion of arguments by implementing Cobra's ValidArgsFunction to fetch the list of namespaces, but it would then be a less varied example)

One can then do things like:

$ kubectl ns <TAB> default kube-node-lease kube-public kube-system $ kubectl ns --<TAB> --as -- Username to impersonate for the operation. User could be a regular user or a service account in a namespace. --as-group -- Group to impersonate for the operation, this flag can be repeated to specify multiple groups. --as-uid -- UID to impersonate for the operation. --cache-dir -- Default cache directory [...] 

Note: kubectl v1.26 or higher is required for shell completion to work for plugins.

You can "uninstall" this plugin from kubectl by simply removing it from your PATH:

$ rm /usr/local/bin/kubectl-ns 

HEAD of this repository will match HEAD of k8s.io/apimachinery and k8s.io/client-go.

sample-cli-plugin is synced from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/sample-cli-plugin. Code changes are made in that location, merged into k8s.io/kubernetes and later synced here.