kubectl 用户偏好设置（kuberc）

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

在 Linux/POSIX 计算机上，此配置文件的默认位置是 $HOME/.kube/kuberc。 在 Windows 上的默认路径是 %USERPROFILE%\.kube\kuberc。 要提供路径指向自定义 kuberc 文件的 kubectl，使用 --kuberc 命令行选项，或设置 KUBERC 环境变量。

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

1. 别名（Aliase） —— 允许你为常用命令创建更短的版本，可以选择设置选项和参数。
2. 默认值（Default） —— 允许你为常用命令配置默认的选项值。
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

下一个示例将介绍一种与前面 prependArgs 类似的机制，
不同之处在于，这次我们会在 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 将跳过确认提示。

凭证插件策略

kubeconfig 的编辑者可以指定一个可执行插件，用来获取向集群验证客户端身份所需的凭证。 在 kuberc 配置中，你可以通过两个顶层字段设置此类插件的执行策略。两个字段都是可选的。

credentialPluginPolicy

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

1. "AllowAll"

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

2. "DenyAll"

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

3. "Allowlist"

   当策略设置为 "Allowlist" 时，用户可以选择性地允许凭证插件执行。 当策略为 "Allowlist" 时，你必须同时提供顶层的 credentialPluginAllowlist 字段。 下文将介绍该字段。

credentialPluginAllowlist

credentialPluginAllowlist 字段指定一组准则集合（即要求集合）的列表， 用于授予执行凭证插件的权限。系统将依次尝试每个要求集合；一旦插件满足至少一个集合中的所有要求， 该插件就被允许执行。也就是说，对插件 my-binary-plugin 应用允许列表的总体结果， 是列表中每个条目所作决策的逻辑或。

例如，考虑以下允许列表配置：

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

在上述示例中，允许列表允许 command 为 "foo"、"bar" 或 "baz" 的插件。

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

command

command 用于指定可执行的凭证插件名称。它可以指定为目标插件的基本名称或完整路径。 如果指定为基本名称，则当满足以下两个条件之一时，该字段作出的决策为“允许”：

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 管理凭证插件策略

你可以使用 kubectl kuberc set 从命令行配置凭证插件策略， 而不必直接编辑 kuberc 文件。

# 将策略设置为拒绝所有凭证插件
kubectl kuberc set --section credentialplugin --policy DenyAll

# 将策略设置为允许所有凭证插件
kubectl kuberc set --section credentialplugin --policy AllowAll

# 仅允许特定的凭证插件
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) 默认启用服务端应用
  - command: apply
    options:
      - name: server-side
        default: "true"

  # (2) 默认启用交互式删除
  - command: delete
    options:
      - name: interactive
        default: "true"

# 先查看上述有关托管提供商的注释，再选择 DenyAll
credentialPluginPolicy: DenyAll

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

1. 默认使用服务端应用。
2. 调用 kubectl delete 时默认进行交互式移除，以防止意外移除集群中的资源。
3. 将不允许执行任何可执行的凭证插件。

要临时禁用 kuberc 功能，只需导出环境变量 KUBERC 并将其值设置为 off：

export KUBERC=off

或者禁用此特性门控：

export KUBECTL_KUBERC=false

这可能有助于排查你的 kuberc 是否造成了某个问题。