Writing kubectl Plugins

Any executable on your PATH that follows the naming convention kubectl-<name> automatically becomes a kubectl plugin. You can write plugins in any language -- Bash, Python, Go, or anything else that produces an executable.

Plugin Naming Convention

kubectl discovers plugins by scanning your PATH for files matching the pattern kubectl-*. The filename determines the subcommand:

# Executable name          kubectl command
# kubectl-hello         -> kubectl hello
# kubectl-pod-status    -> kubectl pod-status  (or kubectl pod status)
# kubectl-ns-list       -> kubectl ns-list

Hyphens in the filename can map to spaces in the command. kubectl tries the longest match first: kubectl-pod-status takes priority over a separate kubectl-pod for the command kubectl pod status.

Writing a Simple Bash Plugin

Create an executable script:

#!/bin/bash
# Save as kubectl-pod-status in a directory on your PATH

# Show pods with their node and status in a compact format
NAMESPACE="${1:---all-namespaces}"

if [ "$NAMESPACE" = "--all-namespaces" ] || [ "$NAMESPACE" = "-A" ]; then
  kubectl get pods -A -o custom-columns=\
NAMESPACE:.metadata.namespace,\
NAME:.metadata.name,\
STATUS:.status.phase,\
NODE:.spec.nodeName
else
  kubectl get pods -n "$NAMESPACE" -o custom-columns=\
NAME:.metadata.name,\
STATUS:.status.phase,\
NODE:.spec.nodeName
fi

# Make it executable and place it on your PATH
chmod +x kubectl-pod-status
mv kubectl-pod-status /usr/local/bin/

# Now use it
kubectl pod-status
kubectl pod-status kube-system

Verifying Plugin Discovery

# List all plugins kubectl can find
kubectl plugin list

# Check for conflicts or issues
kubectl plugin list --name-only

PATH Discovery Order

kubectl searches directories in your PATH from left to right. If two plugins have the same name, the first one found wins.

# See where a plugin lives
which kubectl-pod-status

Key Takeaways