Sign In

Curriculum 24: Kubectl Plugins & Krew

Plugin Best Practices

12 min · 35 XP

Plugin Best Practices

Building a kubectl plugin that others can rely on requires attention to distribution, testing, versioning, and documentation. These practices help your plugin feel like a natural extension of kubectl.

Distribution

The primary distribution channel for kubectl plugins is the Krew index. To submit a plugin:

# Fork the krew-index repository
# Add a plugin manifest file: plugins/my-plugin.yaml
# Submit a pull request

# Your plugin manifest defines download URLs and checksums
# Example structure in the krew-index:
# apiVersion: krew.googlecontainertools.github.com/v1alpha2
# kind: Plugin
# metadata:
#   name: my-plugin
# spec:
#   version: v1.0.0
#   platforms:
#     - selector:
#         matchLabels:
#           os: linux
#           arch: amd64
#       uri: https://github.com/user/kubectl-my-plugin/releases/download/v1.0.0/linux-amd64.tar.gz
#       sha256: abc123...

For private plugins, distribute via internal package managers or simply place the binary in a shared directory.

Testing

Test your plugin like any other CLI tool:

# Unit test the logic in your chosen language
go test ./...

# Integration test against a real cluster
# Use kind or minikube for local testing
kind create cluster --name plugin-test
kubectl my-plugin --expected-output
kind delete cluster --name plugin-test

# Test across multiple kubectl versions
# Plugins should handle version differences gracefully

Validate that your plugin handles edge cases: empty output, missing resources, permission errors, and unreachable clusters.

Versioning

Follow semantic versioning (semver) for your releases:

  • Patch (v1.0.1) -- bug fixes
  • Minor (v1.1.0) -- new features, backward compatible
  • Major (v2.0.0) -- breaking changes
# Tag releases in git
git tag -a v1.2.0 -m "Add namespace filtering support"
git push origin v1.2.0

Documentation

Every plugin should include:

  • A clear --help flag explaining usage and available flags
  • A README with installation instructions and examples
  • Error messages that guide users toward solutions
# Plugins should support --help
kubectl my-plugin --help
# Usage: kubectl my-plugin [flags]
# Flags:
#   -n, --namespace string   Target namespace (default: current)
#   -o, --output string      Output format: table, json, yaml
#       --help               Show this help message

Key Takeaways

  • Distribute through the Krew index for public plugins or internal package managers for private ones
  • Test against real clusters using kind or minikube
  • Use semantic versioning and tag releases in git
  • Always implement --help and provide clear error messages