kube-apiserver 配置 (v1)

收集器的端点，此组件将把跟踪报告到该端点。连接不安全，目前不支持 TLS。建议取消设置，端点是 otlp grpc 默认值，localhost:4317。

SamplingRatePerMillion 是每百万跨度要收集的样本数。建议取消设置。如果取消设置，采样器会尊重其父跨度的采样率，但否则永远不会采样。

Plugins 允许为每个准入控制插件指定配置。

jwt 是一个列表，用于使用符合 JWT 标准的令牌对 Kubernetes 用户进行身份验证。身份验证器将尝试解析原始 ID 令牌，并验证其是否已由配置的颁发者签名。使用 OIDC 发现从颁发者的公共端点发现用于验证签名的公钥。对于传入的令牌，将按此列表中指定的顺序尝试每个 JWT 身份验证器。但是，请注意，其他身份验证器可能在 JWT 身份验证器之前或之后运行。JWT 身份验证器与其他身份验证器的特定位置在不同版本中未定义且不稳定。由于每个 JWT 身份验证器必须具有唯一的颁发者 URL，因此最多只有一个 JWT 身份验证器将尝试以加密方式验证令牌。

最小的有效 JWT 有效负载必须包含以下声明：{ "iss": "https://issuer.example.com", "aud": ["audience"], "exp": 1234567890, "": "username" }

如果存在，则不得设置 --anonymous-auth

Authorizers 是一个有序的授权器列表，用于对请求进行授权。这类似于 kube-apiserver 标志 --authorization-modes 必须至少有一个。

resources 是一个列表，包含资源及其相应的加密提供程序。

嵌入组件配置跟踪配置结构

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

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

Path 是指向包含插件配置的配置文件路径

Configuration 是一个嵌入式配置对象，用作插件的配置。如果存在，它将代替指向配置文件的路径。

启用匿名身份验证的路径。

如果设置，则仅当请求满足其中一个条件时，才允许匿名身份验证。

Type 指示授权器的类型 "Webhook" 在通用 API 服务器中受支持。其他 API 服务器可能支持其他授权器类型，例如 Node、RBAC、ABAC 等。

用于描述 webhook 的名称。这在监控机制中明确用于指标。必需，没有默认值

Webhook 定义 Webhook 授权器的配置。必须在 Type=Webhook 时定义。在 Type!=Webhook 时不得定义。

username 表示 username 属性的选项。声明的值必须是单个字符串。与 --oidc-username-claim 和 --oidc-username-prefix 标志相同。如果 username.expression 已设置，则表达式必须生成一个字符串值。如果 username.expression 使用 'claims.email'，则 username.expression 或 extra[].valueExpression 或 claimValidationRules[].expression 中必须使用 'claims.email_verified'。自动应用于将声明设置为 'email' 时的验证规则的示例表达式是 'claims.?email_verified.orValue(true) == true'。通过显式将值与 true 进行比较，我们让类型检查看到结果将是布尔值，并确保非布尔 email_verified 声明将在运行时被捕获。

在基于标志的方法中，--oidc-username-claim 和 --oidc-username-prefix 是可选的。如果未设置 --oidc-username-claim，则默认值为“sub”。对于身份验证配置，声明或前缀没有默认值。必须显式设置声明和前缀。对于声明，如果未使用旧版标志方法设置 --oidc-username-claim，请在身份验证配置中设置 username.claim="sub"。对于前缀：(1) --oidc-username-prefix="-"，未向用户名添加任何前缀。使用身份验证配置获得相同行为，请设置 username.prefix="" (2) --oidc-username-prefix="" 且 --oidc-username-claim != "email"，前缀为“<value of --oidc-issuer-url>#”。使用身份验证配置获得相同行为，请设置 username.prefix="#" (3) --oidc-username-prefix=""。使用身份验证配置获得相同行为，请设置 username.prefix=""

groups 表示 groups 属性的选项。声明的值必须是字符串或字符串数组声明。如果 groups.claim 已设置，则必须指定前缀（可以是空字符串）。如果 groups.expression 已设置，则表达式必须生成字符串或字符串数组值。“”、“[]”和 null 值被视为组映射不存在。

uid 表示 uid 属性的选项。声明必须是单个字符串声明。如果 uid.expression 已设置，则表达式必须生成一个字符串值。

extra 表示 extra 属性的选项。表达式必须生成字符串或字符串数组值。如果该值为空，则不会存在额外的映射。

硬编码的额外键/值

• key: "foo" valueExpression: "'bar'" 这将导致额外的属性 - foo: ["bar"]

硬编码的键，复制声明值

• key: "foo" valueExpression: "claims.some_claim" 这将导致额外的属性 - foo: [some_claim 的值]

硬编码的键，从声明值派生的值

• key: "admin" valueExpression: '(has(claims.is_admin) && claims.is_admin) ? "true":""' 这将导致
• 如果 is_admin 声明存在且为 true，则额外的属性 - admin: ["true"]
• 如果 is_admin 声明存在且为 false 或 is_admin 声明不存在，则不会添加额外的属性

claim 是要使用的 JWT 声明。claim 或 expression 必须设置。与 expression 互斥。

expression 是将由 CEL 评估的表达式。

CEL 表达式可以访问令牌声明的内容，这些内容组织到 CEL 变量中

• 'claims' 是声明名称到声明值的映射。例如，可以作为 'claims.sub' 访问名为 'sub' 的变量。可以使用点符号访问嵌套声明，例如 'claims.foo.bar'。

CEL 文档：https://kubernetes.ac.cn/docs/reference/using-api/cel/

与 claim 互斥。

claim 是必需声明的名称。与 --oidc-required-claim 标志相同。仅支持字符串声明键。与 expression 和 message 互斥。

requiredValue 是必需声明的值。与 --oidc-required-claim 标志相同。仅支持字符串声明值。如果设置了 claim 且未设置 requiredValue，则必须存在声明，其值设置为空字符串。与 expression 和 message 互斥。

expression 是将由 CEL 评估的表达式。必须生成一个布尔值。

CEL 表达式可以访问令牌声明的内容，这些内容组织到 CEL 变量中

• 'claims' 是声明名称到声明值的映射。例如，可以作为 'claims.sub' 访问名为 'sub' 的变量。可以使用点符号访问嵌套声明，例如 'claims.foo.bar'。必须返回 true 才能通过验证。

CEL 文档：https://kubernetes.ac.cn/docs/reference/using-api/cel/

与 claim 和 requiredValue 互斥。

message 自定义表达式返回 false 时的返回错误消息。message 是文字字符串。与 claim 和 requiredValue 互斥。

key 是用作额外属性键的字符串。key 必须是域前缀路径（例如 example.org/foo）。所有在第一个 "/" 之前的字符必须是 RFC 1123 中定义的有效子域。所有跟在第一个 "/" 之后的字符必须是 RFC 3986 中定义的有效 HTTP 路径字符。key 必须为小写。需要是唯一的。

valueExpression 是一个 CEL 表达式，用于提取额外的属性值。valueExpression 必须生成字符串或字符串数组值。"", [], 和 null 值被视为额外的映射不存在。字符串数组中包含的空字符串值将被过滤掉。

CEL 表达式可以访问令牌声明的内容，这些内容组织到 CEL 变量中

• 'claims' 是声明名称到声明值的映射。例如，可以作为 'claims.sub' 访问名为 'sub' 的变量。可以使用点符号访问嵌套声明，例如 'claims.foo.bar'。

CEL 文档：https://kubernetes.ac.cn/docs/reference/using-api/cel/

url 指向以 https://url 或 https://url/path 格式的 issuer URL。它必须与呈现的 JWT 中的 "iss" claim 以及从 discovery 返回的 issuer 匹配，与 --oidc-issuer-url 标志的值相同。除非被 discoveryURL 覆盖，否则 discovery 信息从 "{url}/.well-known/openid-configuration" 获取。必须在所有 JWT 身份验证器中是唯一的。请注意，出站选择配置不用于此网络连接。

如果指定了 discoveryURL，它将覆盖用于获取 discovery 信息而不是使用 "{url}/.well-known/openid-configuration" 的 URL。使用指定的确切值，因此如果需要，discoveryURL 必须包含 "/.well-known/openid-configuration"。

获取的 discovery 信息中的 "issuer" 字段必须与 AuthenticationConfiguration 中的 "issuer.url" 字段匹配，并将用于验证呈现的 JWT 中的 "iss" claim。这适用于 well-known 和 jwks 端点托管在与 issuer 不同的位置的场景（例如，集群本地）。

示例：一个使用 kubernetes service 'oidc' 在 'oidc-namespace' 命名空间中公开的 discovery url，discovery 信息在 '/.well-known/openid-configuration' 可用。discoveryURL: "https://oidc.oidc-namespace/.well-known/openid-configuration" certificateAuthority 用于验证 TLS 连接，并且叶证书上的主机名必须设置为 'oidc.oidc-namespace'。

curl https://oidc.oidc-namespace/.well-known/openid-configuration (.discoveryURL 字段) { issuer: "https://oidc.example.com" (.url 字段) }

discoveryURL 必须与 url 不同。必须在所有 JWT 身份验证器中是唯一的。请注意，出站选择配置不用于此网络连接。

certificateAuthority 包含用于验证获取 discovery 信息时连接的 PEM 编码的证书颁发机构证书。如果未设置，则使用系统验证器。与 --oidc-ca-file 标志引用的文件的内容相同。

audiences 是 JWT 必须签发到的可接受的受众集合。至少有一个条目必须与呈现的 JWT 中的 "aud" claim 匹配。与 --oidc-client-id 标志的值相同（尽管此字段支持数组）。必须不为空。

audienceMatchPolicy 定义了如何使用 "audiences" 字段来匹配呈现的 JWT 中的 "aud" claim。允许的值是

1. "MatchAny" 当指定多个受众时，以及
2. 空（或未设置）或 "MatchAny" 当指定单个受众时。

• MatchAny：呈现的 JWT 中的 "aud" claim 必须匹配 "audiences" 字段中的至少一个条目。例如，如果 "audiences" 是 ["foo", "bar"]，则呈现的 JWT 中的 "aud" claim 必须包含 "foo" 或 "bar"（并且可能同时包含两者）。

• "": 如果在 "audiences" 字段中指定单个受众，则匹配策略可以为空（或未设置）。呈现的 JWT 中的 "aud" claim 必须包含单个受众（并且可能包含其他受众）。

对于更细致的受众验证，请使用 claimValidationRules。例如：claimValidationRule[].expression: 'sets.equivalent(claims.aud, ["bar", "foo", "baz"])' 以需要完全匹配。

egressSelectorType 是一个指示符，指示应使用哪个出站选择来发送与此 issuer 相关的所有流量（discovery、JWKS、分布式 claim 等）。如果未指定，则不使用自定义拨号器。如果指定，则有效选项是 "controlplane" 和 "cluster"。这些对应于 --egress-selector-config-file 中的相关值。

• controlplane：用于打算发送到控制平面的流量。

• cluster：用于打算发送到 Kubernetes 管理的系统的流量。

issuer 包含基本的 OIDC 提供商连接选项。

claimValidationRules 是应用于验证令牌 claim 以进行用户身份验证的规则。

claimMappings 将令牌的 claim 指向被视为用户属性。

userValidationRules 是应用于完成身份验证之前的最终用户的规则。这些允许对传入的身份应用不变性，例如防止使用 Kubernetes 组件常用的前缀。验证规则在逻辑上进行 AND 运算，并且所有规则都必须返回 true 才能通过验证。

KeyManagementService 的 API 版本

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

cachesize 是内存中缓存的密钥的最大数量。默认值为 1000。设置为负值以禁用缓存。此字段仅允许用于 KMS v1 提供商。

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

对 kms-plugin 的 gRPC 调用超时时间（例如 5s）。默认值为 3 秒。

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

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

claim 是要使用的 JWT claim。与 expression 互斥。

prefix 是附加到 claim 的值的前缀，以防止与现有名称冲突。如果设置了 claim 并且可以为空字符串，则需要设置 prefix。与 expression 互斥。

expression 是将由 CEL 评估的表达式。

CEL 表达式可以访问令牌声明的内容，这些内容组织到 CEL 变量中

• 'claims' 是声明名称到声明值的映射。例如，可以作为 'claims.sub' 访问名为 'sub' 的变量。可以使用点符号访问嵌套声明，例如 'claims.foo.bar'。

CEL 文档：https://kubernetes.ac.cn/docs/reference/using-api/cel/

与 claim 和 prefix 互斥。

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

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

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

identity 是身份转换器的（空）配置。

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

resources 是必须加密的 Kubernetes 资源的列表。资源名称源自 resource 或 resource.group 的组/版本/资源。例如：pandas.awesome.bears.example 是一个具有 'group': awesome.bears.example、'resource': pandas 的自定义资源。使用 '.' 加密所有资源，使用 '.' 加密特定组中的所有资源。例如：'.awesome.bears.example' 将加密组 'awesome.bears.example' 中的所有资源。例如：'*.' 将加密核心组中的所有资源（例如 pods、configmaps 等）。

providers 是用于读取和写入磁盘上的资源的转换器列表。例如：aesgcm、aescbc、secretbox、identity、kms。

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

expression 表示将由 CEL 评估的表达式。必须返回 true 才能通过验证。

CEL 表达式可以访问 UserInfo 的内容，组织到 CEL 变量中

• 'user' - authentication.k8s.io/v1, Kind=UserInfo 对象 请参阅 https://github.com/kubernetes/api/blob/release-1.28/authentication/v1/types.go#L105-L122 以获取定义。API 文档：https://kubernetes.ac.cn/docs/reference/generated/kubernetes-api/v1.28/#userinfo-v1-authentication-k8s-io

CEL 文档：https://kubernetes.ac.cn/docs/reference/using-api/cel/

message 自定义规则返回 false 时的返回错误消息。message 是文字字符串。

从 webhook 授权器缓存“授权”响应的持续时间。与设置 --authorization-webhook-cache-authorized-ttl 标志相同。默认值：5m0s

CacheAuthorizedRequests 指定是否应缓存授权请求。如果设置为 true，则可以通过 AuthorizedTTL 字段配置缓存决策的 TTL。默认值：true

从 webhook 授权器缓存“未授权”响应的持续时间。与设置 --authorization-webhook-cache-unauthorized-ttl 标志相同。默认值：30s

CacheUnauthorizedRequests 指定是否应缓存未授权请求。如果设置为 true，则可以通过 UnauthorizedTTL 字段配置缓存决策的 TTL。默认值：true

webhook 请求的超时时间。允许的最大值为 30s。必需，没有默认值。

要发送到 webhook 并从中期望的 authorization.k8s.io SubjectAccessReview 的 API 版本。与设置 --authorization-webhook-version 标志相同。有效值：v1beta1、v1。必需，没有默认值

MatchConditionSubjectAccessReviewVersion 指定 CEL 表达式针对其进行评估的 SubjectAccessReview 版本。有效值：v1。必需，没有默认值

控制当 webhook 请求无法完成或返回格式错误的响应或评估 matchConditions 时，授权决策。有效值

• NoOpinion：继续到后续授权器，以查看其中一个是否允许请求
• Deny：拒绝请求，而不咨询后续授权器。必需，没有默认值。

ConnectionInfo 定义了我们如何与 webhook 通信

matchConditions 是一个条件列表，必须满足这些条件才能将请求发送到此 webhook。空的 matchConditions 列表将匹配所有请求。允许的最大 matchConditions 数量为 64 个。

确切的匹配逻辑是（按顺序）

1. 如果至少一个 matchCondition 评估为 FALSE，则跳过 webhook。
2. 如果所有 matchCondition 都评估为 TRUE，则调用 webhook。
3. 如果至少一个 matchCondition 评估出错（但没有一个为 FALSE）
   • 如果 failurePolicy=Deny，则 webhook 拒绝该请求
   • 如果 failurePolicy=NoOpinion，则忽略该错误并跳过 webhook

控制 webhook 如何与服务器通信。有效值

• KubeConfigFile：使用 kubeConfigFile 中指定的文件来定位服务器。
• InClusterConfig：使用集群内配置来调用由 kube-apiserver 托管的 SubjectAccessReview API。此模式不允许用于 kube-apiserver。

连接信息的 KubeConfigFile 路径。如果 connectionInfo.Type 为 KubeConfig，则必需。

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' 对应于 authenticator 的 user.Info.GetExtra() 方法。
• 'uid' 是关于请求用户的的信息。例如：request.uid == '1'

CEL 文档：https://kubernetes.ac.cn/docs/reference/using-api/cel/