使用插件扩展 kubectl
本指南演示了如何为 kubectl 安装和编写扩展。通过将核心 kubectl
命令视为与 Kubernetes 集群交互的基本构建块,集群管理员可以将插件视为利用这些构建块创建更复杂行为的手段。插件通过新的子命令扩展 kubectl
,从而允许在 kubectl
主发行版中不包含新的自定义功能。
准备工作
你需要安装一个可用的 kubectl
二进制文件。
安装 kubectl 插件
插件是一个独立的可执行文件,其名称以 kubectl-
开头。要安装插件,将其可执行文件移动到 PATH
中的任何位置。
你还可以使用 Krew 发现和安装开源中可用的 kubectl 插件。Krew 是由 Kubernetes SIG CLI 社区维护的插件管理器。
注意
通过 Krew 插件索引 可用的 Kubectl 插件未经安全审计。你应该自行承担安装和运行第三方插件的风险,因为它们是在你的机器上运行的任意程序。发现插件
kubectl
提供了一个命令 kubectl plugin list
,该命令会在你的 PATH
中搜索有效的插件可执行文件。执行此命令会导致遍历 PATH
中的所有文件。任何可执行文件且以 kubectl-
开头的文件都会在命令输出中**按其在 `PATH` 中出现的顺序**显示。对于任何以 kubectl-
开头但**不可执行**的文件,将包含警告。对于任何名称重叠的有效插件文件,也将包含警告。
你可以使用 Krew 从社区维护的插件索引发现和安装 kubectl
插件。
创建插件
kubectl
允许插件通过在 PATH
中提供 kubectl-create-something
二进制文件来添加形如 kubectl create something
的自定义创建命令。
限制
目前无法创建覆盖现有 kubectl
命令或扩展除 create
之外的命令的插件。例如,创建插件 kubectl-version
将导致该插件永远不会被执行,因为现有的 kubectl version
命令将始终优先于它。由于此限制,也**无法**使用插件向现有 kubectl
命令添加新的子命令。例如,通过将插件命名为 kubectl-attach-vm
来添加子命令 kubectl attach vm
将导致该插件被忽略。
kubectl plugin list
会显示针对任何试图这样做的有效插件的警告。
编写 kubectl 插件
你可以使用任何允许编写命令行命令的编程语言或脚本来编写插件。
不需要插件安装或预加载。插件可执行文件接收来自 kubectl
二进制文件的继承环境。插件根据其名称确定要实现的命令路径。例如,名为 kubectl-foo
的插件提供命令 kubectl foo
。你必须将插件可执行文件安装在 PATH
中的某个位置。
插件示例
#!/bin/bash
# optional argument handling
if [[ "$1" == "version" ]]
then
echo "1.0.0"
exit 0
fi
# optional argument handling
if [[ "$1" == "config" ]]
then
echo "$KUBECONFIG"
exit 0
fi
echo "I am a plugin named kubectl-foo"
使用插件
要使用插件,请使其可执行
sudo chmod +x ./kubectl-foo
并将其放置在 PATH
中的任意位置
sudo mv ./kubectl-foo /usr/local/bin
现在你可以将插件作为 kubectl
命令调用
kubectl foo
I am a plugin named kubectl-foo
所有参数和标志都按原样传递给可执行文件
kubectl foo version
1.0.0
所有环境变量也按原样传递给可执行文件
export KUBECONFIG=~/.kube/config
kubectl foo config
/home/<user>/.kube/config
KUBECONFIG=/etc/kube/config kubectl foo config
/etc/kube/config
此外,传递给插件的第一个参数始终是调用它的完整路径(在上面的示例中,`$0` 将等于 `/usr/local/bin/kubectl-foo`)。
命名插件
如上面的示例所示,插件根据其文件名确定它将实现的命令路径。插件目标命令路径中的每个子命令都用一个破折号(-
)分隔。例如,当用户调用命令 kubectl foo bar baz
时,希望被调用的插件的文件名将是 kubectl-foo-bar-baz
。
标志和参数处理
注意
插件机制**不会**为插件进程创建任何自定义的、特定于插件的值或环境变量。
较旧的 kubectl 插件机制提供了诸如 KUBECTL_PLUGINS_CURRENT_NAMESPACE
这样的环境变量;现在不再这样了。
kubectl 插件必须解析并验证传递给它们的所有参数。有关针对插件作者的 Go 库的详细信息,请参阅使用命令行运行时包。
以下是用户在提供额外标志和参数时调用你的插件的一些额外情况。这建立在上述场景中的 kubectl-foo-bar-baz
插件之上。
如果你运行 kubectl foo bar baz arg1 --flag=value arg2
,kubectl 的插件机制将首先尝试查找名称最长的插件,在这种情况下是 kubectl-foo-bar-baz-arg1
。如果找不到该插件,kubectl 会将最后一个以破折号分隔的值视为一个参数(在本例中为 arg1
),然后尝试查找下一个最长的可能名称 kubectl-foo-bar-baz
。在找到具有此名称的插件后,kubectl 会调用该插件,将插件名称之后的所有参数和标志作为参数传递给插件进程。
示例
# create a plugin
echo -e '#!/bin/bash\n\necho "My first command-line argument was $1"' > kubectl-foo-bar-baz
sudo chmod +x ./kubectl-foo-bar-baz
# "install" your plugin by moving it to a directory in your $PATH
sudo mv ./kubectl-foo-bar-baz /usr/local/bin
# check that kubectl recognizes your plugin
kubectl plugin list
The following kubectl-compatible plugins are available:
/usr/local/bin/kubectl-foo-bar-baz
# test that calling your plugin via a "kubectl" command works
# even when additional arguments and flags are passed to your
# plugin executable by the user.
kubectl foo bar baz arg1 --meaningless-flag=true
My first command-line argument was arg1
如你所见,你的插件是根据用户指定的 kubectl
命令找到的,所有额外的参数和标志在找到后都按原样传递给插件可执行文件。
带有破折号和下划线的名称
尽管 kubectl
插件机制在插件文件名中使用破折号(-
)来分隔插件处理的子命令序列,但仍然可以通过在文件名中使用下划线(_
)来创建在命令行调用中包含破折号的插件命令。
示例
# create a plugin containing an underscore in its filename
echo -e '#!/bin/bash\n\necho "I am a plugin with a dash in my name"' > ./kubectl-foo_bar
sudo chmod +x ./kubectl-foo_bar
# move the plugin into your $PATH
sudo mv ./kubectl-foo_bar /usr/local/bin
# You can now invoke your plugin via kubectl:
kubectl foo-bar
I am a plugin with a dash in my name
请注意,在插件文件名中引入下划线并不会阻止你拥有诸如 kubectl foo_bar
这样的命令。上述示例中的命令可以使用破折号(-
)或下划线(_
)进行调用。
# You can invoke your custom command with a dash
kubectl foo-bar
I am a plugin with a dash in my name
# You can also invoke your custom command with an underscore
kubectl foo_bar
I am a plugin with a dash in my name
名称冲突和遮蔽
在你的 PATH
中,可能在不同的位置有多个同名插件。例如,给定 PATH
值为:PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins
,插件 kubectl-foo
的一个副本可能存在于 /usr/local/bin/plugins
和 /usr/local/bin/moreplugins
中,这样 kubectl plugin list
命令的输出将是
PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins kubectl plugin list
The following kubectl-compatible plugins are available:
/usr/local/bin/plugins/kubectl-foo
/usr/local/bin/moreplugins/kubectl-foo
- warning: /usr/local/bin/moreplugins/kubectl-foo is overshadowed by a similarly named plugin: /usr/local/bin/plugins/kubectl-foo
error: one plugin warning was found
在上述情景中,/usr/local/bin/moreplugins/kubectl-foo
下的警告告诉你此插件永远不会被执行。相反,PATH
中首先出现的那个可执行文件,即 /usr/local/bin/plugins/kubectl-foo
,将始终由 kubectl
插件机制首先找到并执行。
解决此问题的一种方法是确保你希望与 kubectl
一起使用的插件的位置始终在你的 PATH
中优先。例如,如果你希望在每次调用 kubectl
命令 kubectl foo
时都使用 /usr/local/bin/moreplugins/kubectl-foo
,则将你的 PATH
值更改为 /usr/local/bin/moreplugins:/usr/local/bin/plugins
。
调用最长的可执行文件名
插件文件名还可能发生另一种遮蔽。给定用户 PATH
中存在的两个插件:kubectl-foo-bar
和 kubectl-foo-bar-baz
,kubectl
插件机制将始终为给定的用户命令选择最长的插件名称。下面的一些示例进一步阐明了这一点
# for a given kubectl command, the plugin with the longest possible filename will always be preferred
kubectl foo bar baz
Plugin kubectl-foo-bar-baz is executed
kubectl foo bar
Plugin kubectl-foo-bar is executed
kubectl foo bar baz buz
Plugin kubectl-foo-bar-baz is executed, with "buz" as its first argument
kubectl foo bar buz
Plugin kubectl-foo-bar is executed, with "buz" as its first argument
这种设计选择确保插件子命令可以根据需要在多个文件中实现,并且这些子命令可以嵌套在“父”插件命令下。
ls ./plugin_command_tree
kubectl-parent
kubectl-parent-subcommand
kubectl-parent-subcommand-subsubcommand
检查插件警告
你可以使用上述的 kubectl plugin list
命令来确保你的插件对 kubectl
可见,并验证没有任何警告阻止它作为 kubectl
命令被调用。
kubectl plugin list
The following kubectl-compatible plugins are available:
test/fixtures/pkg/kubectl/plugins/kubectl-foo
/usr/local/bin/kubectl-foo
- warning: /usr/local/bin/kubectl-foo is overshadowed by a similarly named plugin: test/fixtures/pkg/kubectl/plugins/kubectl-foo
plugins/kubectl-invalid
- warning: plugins/kubectl-invalid identified as a kubectl plugin, but it is not executable
error: 2 plugin warnings were found
使用命令行运行时包
如果你正在为 kubectl 编写插件并使用 Go 语言,你可以利用 cli-runtime 工具库。
这些库提供了一些辅助函数,用于解析或更新用户的 kubeconfig 文件,向 API 服务器发出 REST 风格的请求,或绑定与配置和打印相关的标志。
有关 CLI Runtime 仓库中提供的工具的示例用法,请参阅示例 CLI 插件。
分发 kubectl 插件
如果你已经开发了一个供他人使用的插件,你应该考虑如何打包、分发它以及向用户提供更新。
Krew
Krew 提供了一种跨平台的打包和分发插件的方式。通过这种方式,你可以为所有目标平台(Linux、Windows、macOS 等)使用单一的打包格式,并向用户提供更新。Krew 还维护一个插件索引,以便其他人可以发现并安装你的插件。
原生/平台特定的包管理
或者,你也可以使用传统的包管理器,例如 Linux 上的 apt
或 yum
,Windows 上的 Chocolatey,以及 macOS 上的 Homebrew。任何包管理器都适用,只要它能将新的可执行文件放置在用户的 PATH
中的某个位置。作为插件作者,如果选择此选项,你还需要承担每个版本在多个平台上更新 kubectl 插件分发包的负担。
源代码
你可以发布源代码;例如,作为 Git 仓库。如果你选择此选项,想要使用该插件的人必须获取代码,设置构建环境(如果需要编译),然后部署插件。如果你还提供已编译的包,或者使用 Krew,那将使安装更容易。
下一步
- 查看示例 CLI 插件仓库,了解用 Go 编写的插件的详细示例。如有任何问题,请随时联系 SIG CLI 团队。
- 阅读关于 Krew,一个 kubectl 插件的包管理器。