kube-apiserver 配置 (v1)

v1 包中包含 API 的 v1 版本。

资源类型

AdmissionConfiguration

AdmissionConfiguration 为准入控制器提供版本化的配置。

字段描述
apiVersion
string
apiserver.config.k8s.io/v1
kind
string
AdmissionConfiguration
plugins
[]AdmissionPluginConfiguration

plugins 字段允许为每个准入控制插件设置配置选项。

AuthorizationConfiguration

字段描述
apiVersion
string
apiserver.config.k8s.io/v1
kind
string
AuthorizationConfiguration
authorizers [必需]
[]AuthorizerConfiguration

authorizers 是用于针对请求进行鉴权的鉴权组件的有序列表。 这类似于 `--authorization-modes` kube-apiserver 标志。 必须至少包含一个元素。

EncryptionConfiguration

EncryptionConfiguration 存储加密驱动的完整配置。它还允许使用通配符来指定应该被加密的资源。 使用 “*.<group>” 以加密组内的所有资源,或使用 “*.*” 以加密所有资源。 “*.” 可用于加密核心组中的所有资源。“*.*” 将加密所有资源,包括在 API 服务器启动后添加的自定义资源。 由于部分配置可能无效,所以不允许在同一资源列表中或跨多个条目使用重叠的通配符。 资源列表被按顺序处理,会优先处理较早的列表。

示例:

kind: EncryptionConfiguration
apiVersion: apiserver.config.k8s.io/v1
resources:
- resources:
  - events
  providers:
  - identity: {}  # 即使以下 *.* 被指定,也不会对事件加密
- resources:
  - secrets
  - configmaps
  - pandas.awesome.bears.example
  providers:
  - aescbc:
      keys:
      - name: key1
        secret: c2VjcmV0IGlzIHNlY3VyZQ==
- resources:
  - '*.apps'
  providers:
  - aescbc:
      keys:
      - name: key2
        secret: c2VjcmV0IGlzIHNlY3VyZSwgb3IgaXMgaXQ/Cg==
- resources:
  - '*.*'
  providers:
  - aescbc:
      keys:
      - name: key3
        secret: c2VjcmV0IGlzIHNlY3VyZSwgSSB0aGluaw==
字段描述
apiVersion
string
apiserver.config.k8s.io/v1
kind
string
EncryptionConfiguration
resources [必需]
[]ResourceConfiguration

resources 是一个包含资源及其对应加密驱动的列表。

AESConfiguration

出现在:

AESConfiguration 包含针对 AES 转换器的 API 配置。

字段描述
keys [必需]
[]Key

keys 是一个用于创建 AES 转换器的密钥列表。 对于 AES-CBC,每个密钥的长度必须是 32 字节; 对于 AES-GCM,每个密钥的长度可以是 16、24 或 32 字节。

AdmissionPluginConfiguration

出现在:

AdmissionPluginConfiguration 为某个插件提供配置信息。

字段描述
name [必需]
string

name 是准入控制器的名称。它必须与所注册的准入插件名称匹配。

path
string

path 是指向包含插件配置信息的配置文件的路径。

configuration
k8s.io/apimachinery/pkg/runtime.Unknown

configuration 是一个内嵌的配置对象,用来保存插件的配置信息。 如果存在,则使用这里的配置信息而不是指向配置文件的路径。

AuthorizerConfiguration

出现在:

字段描述
type [必需]
string

type 指的是鉴权组件的类型。 通用 API 服务器支持 "Webhook"。 其他 API 服务器可能支持额外的鉴权组件类型,如 Node、RBAC、ABAC 等。

name [必需]
string

name 用于描述 Webhook。 此字段的明确用途是供监控机制中的指标使用。 注意:name 值必须是 DNS1123 标签,如 myauthorizername 或子域名, 如 myauthorizer.example.domain。 必需,无默认值。

webhook [必需]
WebhookConfiguration

webhook 定义 Webhook 鉴权组件的配置。 当 type 为 Webhook 时,必须定义。 当 type 不是 Webhook 时,不得定义。

IdentityConfiguration

出现在:

IdentityConfiguration 是一个空结构体,允许在驱动配置中使用身份转换器。

KMSConfiguration

出现在:

KMSConfiguration 包含 KMS 型信封转换器所用的配置文件的名称、缓存大小和路径。

字段描述
apiVersion
string

KeyManagementService 的 apiVersion

name [必需]
string

name 是要使用的 KMS 插件的名称。

cachesize
int32

cachesize 是内存中缓存的最大 Secret 数量。默认值为 1000。 设置为负值将禁用缓存。此字段仅允许用于 KMS v1 驱动。

endpoint [必需]
string

endpoint 是 gRPC 服务器的监听地址,例如 "unix:///var/run/kms-provider.sock"。

timeout
meta/v1.Duration

timeout 是 gRPC 调用到 KMS 插件的超时时间(例如 5s)。默认值为 3 秒。

Key

出现在:

Key 包含为转换器所提供的密钥的名称和 Secret。

字段描述
name [必需]
string

name 是在将数据存储到磁盘时所使用的密钥名称。

secret [必需]
string

secret 是实际的密钥,以 base64 编码。

ProviderConfiguration

出现在:

ProviderConfiguration 存储为加密驱动提供的配置。

字段描述
aesgcm [必需]
AESConfiguration

aesgcm 是 AES-GCM 转换器的配置。

aescbc [必需]
AESConfiguration

aescbc 是 AES-CBC 转换器的配置。

secretbox [必需]
SecretboxConfiguration

secretbox 是基于 Secretbox 的转换器的配置。

identity [必需]
IdentityConfiguration

identity 是身份转换器的(空)配置。

kms [必需]
KMSConfiguration

kms 包含 KMS 型信封转换器所用的配置文件的名称、缓存大小和路径。

ResourceConfiguration

出现在:

ResourceConfiguration 存储每个资源的配置。

字段描述
resources [必需]
[]string

resources 是一个需要加密的 Kubernetes 资源列表。 资源名称来源于组/版本/资源的 “resource” 或 “resource.group”。 例如,pandas.awesome.bears.example 是一个自定义资源,其 “group” 为 awesome.bears.example, “resource” 为 pandas。使用 “*.*” 以加密所有资源,使用 “*.<group>” 以加密特定组中的所有资源。 例如,“*.awesome.bears.example” 将加密 “awesome.bears.example” 组中的所有资源。 再比如,“*.” 将加密核心组中的所有资源(如 Pod、ConfigMap 等)。

providers [必需]
[]ProviderConfiguration

providers 是从磁盘读取资源和写入资源到磁盘要使用的转换器的列表。 例如:aesgcm、aescbc、secretbox、identity、kms。

SecretboxConfiguration

出现在:

SecretboxConfiguration 包含 Secretbox 转换器的 API 配置。

字段描述
keys [必需]
[]Key

keys 是一个用于创建 Secretbox 转换器的密钥列表。每个密钥的长度必须为 32 字节。

WebhookConfiguration

出现在:

字段描述
authorizedTTL [必需]
meta/v1.Duration

用于缓存来自 Webhook 鉴权组件的 'authorized' 响应的持续时间。 与设置 --authorization-webhook-cache-authorized-ttl 标志效果相同。 默认值:5m0s。

unauthorizedTTL [必需]
meta/v1.Duration

用于缓存来自 Webhook 鉴权组件的 'unauthorized' 响应的持续时间。 与设置 --authorization-webhook-cache-unauthorized-ttl 标志效果相同。 默认值:30s。

timeout [必需]
meta/v1.Duration

Webhook 请求的超时时间。 最大允许值为 30s。 必需,无默认值。

subjectAccessReviewVersion [必需]
string

发送到 Webhook 并期望从 Webhook 接收到的 authorization.k8s.io SubjectAccessReview 的 API 版本。 与设置 --authorization-webhook-version 标志效果相同。 有效值:v1beta1、v1。 必需,无默认值。

matchConditionSubjectAccessReviewVersion [必需]
string

matchConditionSubjectAccessReviewVersion 指定了 CEL 表达式求值所用的 SubjectAccessReview 版本。 有效值:v1。 必需,无默认值。

failurePolicy [必需]
string

控制当 Webhook 请求未能完成、返回格式错误的响应或在评估 matchConditions 时发生错误的情况下鉴权决策。 有效值:

  • NoOpinion:继续处理后续的鉴权组件以查看它们中是否有一个允许请求。
  • Deny:拒绝请求,不咨询后续鉴权组件。 必需,无默认值。
connectionInfo [必需]
WebhookConnectionInfo

connectionInfo 定义了我们如何与 Webhook 进行通信。

matchConditions [必需]
[]WebhookMatchCondition

matchConditions 是请求发送到此 Webhook 之前必须满足的一系列条件。 空的 matchConditions 列表匹配所有请求。 最多允许 64 个匹配条件。

精确的匹配逻辑(按顺序)是:

  1. 如果至少一个 matchConditions 元素的计算结果为 FALSE,则跳过此 Webhook。
  2. 如果所有 matchConditions 元素的计算结果都为 TRUE,则调用此 Webhook。
  3. 如果至少一个 matchConditions 元素的计算结果为出错(但没有 FALSE):
    • 如果 failurePolicy 为 Deny,则 Webhook 拒绝请求。
    • 如果 failurePolicy 为 NoOpinion,则忽略错误并跳过此 Webhook。

WebhookConnectionInfo

Appears in:

字段描述
type [必需]
string

控制 Webhook 应如何与服务器通信。 有效值:

    • KubeConfigFile:使用 kubeConfigFile 中指定的文件来定位服务器。
    • InClusterConfig:使用集群内配置调用由 kube-apiserver 上的 SubjectAccessReview API。 此模式不允许用于 kube-apiserver。
kubeConfigFile [必需]
string

KubeConfig 文件的路径,用于获取连接信息。 如果 connectionInfo.type 是 KubeConfig,则必需。

WebhookMatchCondition

出现在:

字段描述
expression [必需]
string

expression 表示将由 CEL 求值的表达式。求值结果必须是布尔值。 CEL 表达式可以访问 v1 版本中的 SubjectAccessReview 的内容。 如果请求变量中指定的 subjectAccessReviewVersion 是 v1beta1, 则在对 CEL 表达式求值之前,其内容会被转换为 v1 版本。

  • 'resourceAttributes' 描述了资源访问请求的信息,在非资源请求中未设置。例如:has(request.resourceAttributes) && request.resourceAttributes.namespace == 'default'
  • 'nonResourceAttributes' 描述了非资源访问请求的信息,在资源请求中未设置。例如: has(request.nonResourceAttributes) && request.nonResourceAttributes.path == '/healthz'
  • 'user' 是要测试的用户。例如:request.user == 'alice'
  • 'groups' 是要测试的组。例如:('group1' in request.groups)
  • 'extra' 对应于身份验证器中的 user.Info.GetExtra() 方法。
  • 'uid' 是关于请求用户的详细信息。例如:request.uid == '1'

关于 CEL 的文档:https://kubernetes.io/docs/reference/using-api/cel/

最后修改 January 18, 2025 at 5:00 PM PST: [zh-cn]sync apiserver-config.v1.md (1520360e2c)