Kubectl 用户偏好设置 (kuberc)

Kubernetes kuberc 配置文件允许您定义 kubectl 的偏好设置，例如默认选项和命令别名。与 kubeconfig 文件不同，kuberc 配置文件不包含集群详细信息、用户名或密码。

在 Linux / POSIX 系统中，此配置文件的默认位置为 $HOME/.kube/kuberc。Windows 下的默认路径类似：%USERPROFILE%\.kube\kuberc。要为 kubectl 指定自定义 kuberc 文件路径，请使用 --kuberc 命令行选项，或设置 KUBERC 环境变量。

使用 kubectl.config.k8s.io/v1beta1 格式的 kuberc 允许您定义以下类型的用户偏好设置：

1. 别名 (Aliases) - 允许您创建常用命令的缩写版本，并可选择设置选项和参数。
2. 默认值 (Defaults) - 允许您为常用命令配置默认选项值。
3. 凭据插件策略 (Credential Plugin Policy) - 允许您为 exec 凭据插件配置策略。

aliases (别名)

在 kuberc 配置中，aliases (别名) 部分允许您定义 kubectl 命令的自定义快捷方式，并可选择预设命令行参数和标志。

下面的示例定义了 kubectl get 子命令的 kubectl getn 别名，并额外指定了 JSON 输出格式：--output=json。

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
aliases:
- name: getn
  command: get
  options:
   - name: output
     default: json

在此示例中，使用了以下设置：

1. name - 别名名称不得与内置命令冲突。
2. command - 指定您的别名将执行的底层内置命令。这包括对 create role 等子命令的支持。
3. options - 指定选项的默认值。如果您在运行 kubectl 时显式指定了某个选项，则您提供的值将优先于 kuberc 中定义的默认值。

使用此别名，运行 kubectl getn pods 将默认采用 JSON 输出。但是，如果您执行 kubectl getn pods -oyaml，输出将采用 YAML 格式。

完整的 kuberc 模式可在此处查看。

prependArgs (前置参数)

下一个示例将扩展前一个示例，引入 prependArgs 部分，它允许在 kubectl 命令及其子命令（如果有）之后立即插入任意参数。

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
aliases:
  - name: getn
    command: get
    options:
      - name: output
        default: json
    prependArgs:
      - namespace

在此示例中，使用了以下设置：

1. name - 别名名称不得与内置命令冲突。
2. command - 指定您的别名将执行的底层内置命令。这包括对 create role 等子命令的支持。
3. options - 指定选项的默认值。如果您在运行 kubectl 时显式指定了某个选项，则您提供的值将优先于 kuberc 中定义的默认值。
4. prependArgs - 指定将放置在命令之后且直接生效的显式参数。在此处，它将被转换为 kubectl get namespace test-ns --output json。

appendArgs (追加参数)

下一个示例将引入一种类似于前置参数的机制，不同之处在于，这次我们将参数追加到 kubectl 命令的末尾。

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
aliases:
- name: runx
  command: run
  options:
    - name: image
      default: busybox
    - name: namespace
      default: test-ns
  appendArgs:
    - --
    - custom-arg

在此示例中，使用了以下设置：

1. name - 别名名称不得与内置命令冲突。
2. command - 指定您的别名将执行的底层内置命令。这包括对 create role 等子命令的支持。
3. options - 指定选项的默认值。如果您在运行 kubectl 时显式指定了某个选项，则您提供的值将优先于 kuberc 中定义的默认值。
4. appendArgs - 指定将放置在命令末尾的显式参数。在此处，它将被转换为 kubectl run test-pod --namespace test-ns --image busybox -- custom-arg。

defaults (默认值)

在 kuberc 配置中，defaults 部分允许您为命令行参数指定默认值。

下一个示例将交互式删除模式设为调用 kubectl delete 的默认模式：

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
defaults:
- command: delete
  options:
    - name: interactive
      default: "true"

在此示例中，使用了以下设置：

1. command - 内置命令，这包括对 create role 等子命令的支持。
2. options - 指定选项的默认值。如果您在运行 kubectl 时显式指定了某个选项，则您提供的值将优先于 kuberc 中定义的默认值。

使用此设置，运行 kubectl delete pod/test-pod 将默认提示确认。但是，kubectl delete pod/test-pod --interactive=false 将跳过确认。

Credential plugin policy (凭据插件策略)

kubeconfig 的编辑器可以指定一个可执行插件，用于获取凭据以验证客户端与集群的连接。在 kuberc 配置中，您可以使用两个顶级字段来设置此类插件的执行策略。这两个字段均为可选。

credentialPluginPolicy

您可以使用可选的 credentialPluginPolicy 字段配置凭据插件策略。该字段有三个有效值：

1. "AllowAll"

当策略设置为 "AllowAll" 时，对可以运行的插件没有任何限制。此行为与 1.35 之前的 Kubernetes 版本一致。

2. "DenyAll"

当策略设置为 "DenyAll" 时，将不允许任何 exec 插件运行。

3. "Allowlist"

当策略设置为 "Allowlist" 时，用户可以有选择地允许执行凭据插件。当策略为 "Allowlist" 时，您必须同时提供 credentialPluginAllowlist 字段（也在顶级）。该字段描述如下。

credentialPluginAllowlist

credentialPluginAllowlist 字段指定了一组用于允许执行凭据插件的标准集合（即要求集）。每组要求将依次尝试；一旦插件满足至少一组中的所有要求，即被允许执行。也就是说，将许可名单应用于插件 my-binary-plugin 的最终结果，是列表中每一项所做决定的逻辑或 (OR)。

例如，考虑以下许可名单配置：

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
credentialPluginPolicy: Allowlist
credentialPluginAllowlist:
  - command: foo
  - command: bar
  - command: baz

在上面的示例中，许可名单将允许命令为 "foo"、"bar" 或 "baz" 的插件。

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
credentialPluginPolicy: Allowlist
credentialPluginAllowlist:
  - command: ""

command

command 用于命名可能被执行的凭据插件。它可以指定为所需插件的基本名称 (basename) 或完整路径。如果指定为基本名称，则此字段给出的决定为“允许”，前提是满足以下两个条件之一：

1. command 字段与插件的 command 字段完全相等。
2. 对许可名单的 command 和插件的 command 都执行完整路径解析，且结果相等。

如果指定为完整路径，则此字段给出的决定为“允许”，前提是满足以下条件之一：

1. command 字段与插件的 command 字段完全相等（即插件的 command 也是一个完整路径）。
2. 对插件的 command 执行完整路径解析，且与许可名单的 command 字段完全匹配。

关于本页前面提到的完整路径解析，不会解析符号链接或 shell 通配符。

例如，考虑一个 command 为 /usr/local/bin/my-binary 的许可名单条目，其中 /usr/local/bin/my-binary 是指向 /this/is/a/target 的符号链接。如果 kubeconfig 中指定的 command 是 /this/is/a/target，它将不被允许。为了使其生效，您需要将 /this/is/a/target 显式添加到许可名单中。另一方面，如果 kubeconfig 的 command 为 /usr/local/bin/my-binary，则许可名单将允许它运行。

示例

以下示例展示了带有许可名单的 "Allowlist" 策略：

• POSIX
• Windows

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
credentialPluginPolicy: Allowlist
credentialPluginAllowlist:
  - command: my-trusted-binary
  - command: /usr/local/bin/my-other-trusted-binary

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
credentialPluginPolicy: Allowlist
credentialPluginAllowlist:
  - command: my-trusted-binary
  - command: "C:\my-other-trusted-binary"

使用 kubectl kuberc set 管理凭据插件策略

与其直接编辑 kuberc 文件，您可以使用 kubectl kuberc set 从命令行配置凭据插件策略。

# Set the policy to deny all credential plugins
kubectl kuberc set --section credentialplugin --policy DenyAll

# Set the policy to allow all credential plugins
kubectl kuberc set --section credentialplugin --policy AllowAll

# Allow only specific credential plugins
kubectl kuberc set --section credentialplugin \
    --policy Allowlist \
    --allowlist-entry command=my-trusted-binary \
    --allowlist-entry command=my-other-trusted-binary

在此示例中，使用了以下标志：

1. --section credentialplugin - 选择凭据插件配置部分。
2. --policy - 必需。将策略设置为 AllowAll、DenyAll 或 Allowlist。
3. --allowlist-entry - 当 --policy=Allowlist 时必需。通过逗号分隔的 key=value 对指定要允许的插件。目前 command 是唯一支持的键（例如，command=<binary-name>），但该格式也考虑了未来的扩展，如摘要或公钥验证。重复此标志可允许多个插件。

建议的默认配置

kubectl 维护者鼓励您采用以下默认设置的 kuberc：

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
defaults:
  # (1) default server-side apply
  - command: apply
    options:
      - name: server-side
        default: "true"

  # (2) default interactive deletion
  - command: delete
    options:
      - name: interactive
        default: "true"

# See the above note about managed providers before selecting DenyAll
credentialPluginPolicy: DenyAll

在此示例中，强制执行以下设置：

1. 默认使用 服务端应用 (Server-Side Apply)。
2. 在调用 kubectl delete 时默认为交互式删除，以防止意外删除集群中的资源。
3. 不允许任何可执行凭据插件运行。

禁用 kuberc

要暂时禁用 kuberc 功能，请设置（并导出）环境变量 KUBERC，其值为 off：

export KUBERC=off

或者禁用特性门控 (feature gate)：

export KUBECTL_KUBERC=false

这有助于排查您的 kuberc 是否导致了问题。