kube-apiserver 配置 (v1alpha1)

此组件将向其报告追踪数据的收集器的 endpoint。连接是不安全的，目前不支持 TLS。建议保持未设置，endpoint 是 otlp grpc 的默认值，localhost:4317。

SamplingRatePerMillion 是每百万个 span 中收集的采样数。建议保持未设置。如果未设置，采样器将尊重其父 span 的采样率，但除此之外不会进行采样。

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

jwt 是一个身份认证器列表，用于使用符合 JWT 规范的令牌来认证 Kubernetes 用户。身份认证器将尝试解析原始 ID 令牌，并验证它是否由配置的颁发者签名。用于验证签名的公钥通过 OIDC 发现从颁发者的公共 endpoint 获取。对于传入的令牌，列表中的每个 JWT 身份认证器将按其指定的顺序尝试。但请注意，其他身份认证器可能会在 JWT 身份认证器之前或之后运行。JWT 身份认证器相对于其他身份认证器的具体位置既未定义也不稳定。由于每个 JWT 身份认证器必须具有唯一的颁发者 URL，因此最多只有一个 JWT 身份认证器会尝试加密验证令牌。

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

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

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

connectionServices 包含一个出口选择器客户端配置列表

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

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

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

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

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

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

Type 指授权者的类型。“Webhook” 在通用 API 服务器中受支持。其他 API 服务器可能支持额外的授权者类型，如 Node、RBAC、ABAC 等。

用于描述 Webhook 的名称。这在用于指标的监控机制中显式使用。注意：名称必须是 DNS1123 Label，如 myauthorizername 或子域，如 myauthorizer.example.domain。必需，无默认值。

Webhook 定义了 Webhook 授权器的配置。当 Type=Webhook 时必须定义，当 Type!=Webhook 时不能定义。

username 表示 username 属性的一个选项。Claim 的值必须是一个单一字符串。与 --oidc-username-claim 和 --oidc-username-prefix 标志相同。如果设置了 username.expression，则表达式必须生成一个字符串值。如果 username.expression 使用 'claims.email'，则必须在 username.expression 或 extra[].valueExpression 或 claimValidationRules[].expression 中使用 'claims.email_verified'。一个与当 username.claim 设置为 'email' 时自动应用的验证相匹配的 Claim 验证规则表达式示例是 'claims.?email_verified.orValue(true)'。

在基于标志的方法中，--oidc-username-claim 和 --oidc-username-prefix 是可选的。如果未设置 --oidc-username-claim，默认值为 "sub"。对于认证配置，Claim 或 Prefix 没有默认值。Claim 和 Prefix 必须显式设置。对于 Claim，如果在使用旧标志方法时未设置 --oidc-username-claim，请在认证配置中配置 username.claim="sub"。对于 Prefix：(1) --oidc-username-prefix="-"，未向用户名添加前缀。对于使用认证配置实现相同的行为，请设置 username.prefix=""。(2) --oidc-username-prefix="" 且 --oidc-username-claim != "email"，前缀为 "<--oidc-issuer-url 的值>#"。对于使用认证配置实现相同的行为，请设置 username.prefix="#"。(3) --oidc-username-prefix=""。对于使用认证配置实现相同的行为，请设置 username.prefix=""。

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

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

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

硬编码的 extra 键/值

• key: "foo" valueExpression: "'bar'" 这将生成一个 extra 属性 - foo: ["bar"]

硬编码的键，值复制 Claim 值

• key: "foo" valueExpression: "claims.some_claim" 这将生成一个 extra 属性 - foo: [some_claim 的值]

硬编码的键，值派生自 Claim 值

• key: "admin" valueExpression: '(has(claims.is_admin) && claims.is_admin) ? "true":""' 这将生成
• 如果 is_admin Claim 存在且为 true，extra 属性 - admin: ["true"]
• 如果 is_admin Claim 存在且为 false，或者 is_admin Claim 不存在，则不会添加 extra 属性

claim 是要使用的 JWT Claim。必须设置 claim 或 expression 之一。与 expression 互斥。

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

CEL 表达式可以访问令牌 Claim 的内容，组织成 CEL 变量

• 'claims' 是一个 Claim 名称到 Claim 值的映射。例如，名为 'sub' 的变量可以通过 'claims.sub' 访问。嵌套 Claim 可以使用点表示法访问，例如 'claims.foo.bar'。

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

与 claim 互斥。

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

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

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

CEL 表达式可以访问令牌 Claim 的内容，组织成 CEL 变量

• 'claims' 是一个 Claim 名称到 Claim 值的映射。例如，名为 'sub' 的变量可以通过 'claims.sub' 访问。嵌套 Claim 可以使用点表示法访问，例如 'claims.foo.bar'。必须返回 true，验证才会通过。

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

与 claim 和 requiredValue 互斥。

message 自定义当 expression 返回 false 时返回的错误消息。message 是字面量字符串。与 claim 和 requiredValue 互斥。

Protocol 是客户端连接到 konnectivity 服务器使用的协议。

Transport 定义了我们用于拨号到 konnectivity 服务器的传输配置。如果 ProxyProtocol 是 HTTPConnect 或 GRPC，则此字段为必需。

name 是出口选择的名称。当前支持的值为 "controlplane", "master", "etcd" 和 "cluster"。已弃用 "master" 出口选择器，推荐使用 "controlplane"。

connection 是用于配置出口选择的精确信息

key 是用作 extra 属性键的字符串。key 必须是域名-前缀路径（例如 example.org/foo）。第一个 "/" 之前的所有字符必须是符合 RFC 1123 定义的有效子域。第一个 "/" 之后的所有字符必须是符合 RFC 3986 定义的有效 HTTP Path 字符。key 必须是小写。必需且唯一。

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

CEL 表达式可以访问令牌 Claim 的内容，组织成 CEL 变量

• 'claims' 是一个 Claim 名称到 Claim 值的映射。例如，名为 'sub' 的变量可以通过 'claims.sub' 访问。嵌套 Claim 可以使用点表示法访问，例如 'claims.foo.bar'。

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

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

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

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

示例：通过 Kubernetes Service 'oidc' 在命名空间 'oidc-namespace' 中暴露的发现 URL，并且发现信息位于 '/.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 包含 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"])' 以要求精确匹配。

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

claimValidationRules 是用于验证令牌 Claim 以认证用户的规则。

claimMappings 指示令牌的 Claim 应被视为用户属性。

userValidationRules 是在完成身份认证之前应用于最终用户的规则。这些规则允许对传入身份应用不变式，例如阻止使用 Kubernetes 组件常用的 system: 前缀。验证规则是逻辑 AND 的，所有规则都必须返回 true，验证才能通过。

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

prefix 添加到 Claim 的值之前，以防止与现有名称冲突。如果设置了 claim，则必须设置 prefix（并且可以是空字符串）。与 expression 互斥。

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

CEL 表达式可以访问令牌 Claim 的内容，组织成 CEL 变量

• 'claims' 是一个 Claim 名称到 Claim 值的映射。例如，名为 'sub' 的变量可以通过 'claims.sub' 访问。嵌套 Claim 可以使用点表示法访问，例如 'claims.foo.bar'。

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

与 claim 和 prefix 互斥。

URL 是要连接的 konnectivity 服务器的位置。例如，它可以是 "https://127.0.0.1:8131"

TLSConfig 是连接到 konnectivity 服务器时使用 TLS 所需的配置

caBundle 是用于确定与 konnectivity 服务器信任关系的 CA 文件位置。如果 TCPTransport.URL 以 http:// 为前缀，则必须缺失/为空。如果缺失而 TCPTransport.URL 以 https:// 为前缀，则默认使用系统信任根证书。

clientKey 是用于与 konnectivity 服务器进行 mtls 握手时使用的客户端私钥的文件位置。如果 TCPTransport.URL 以 http:// 为前缀，则必须缺失/为空。如果 TCPTransport.URL 以 https:// 为前缀，则必须配置。

clientCert 是用于与 konnectivity 服务器进行 mtls 握手时使用的客户端证书的文件位置。如果 TCPTransport.URL 以 http:// 为前缀，则必须缺失/为空。如果 TCPTransport.URL 以 https:// 为前缀，则必须配置。

TCP 是通过 TCP 与 konnectivity 服务器通信的 TCP 配置。目前 TCP 传输不支持 GRPC 的 ProxyProtocol。需要至少设置 TCP 或 UDS 之一。

UDS 是通过 UDS 与 konnectivity 服务器通信的 UDS 配置。需要至少设置 TCP 或 UDS 之一。

UDSName 是连接到 konnectivity 服务器的 Unix 域套接字的名称。这不使用 unix:// 前缀。（例如：/etc/srv/kubernetes/konnectivity-server/konnectivity-server.socket）

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 授权者 'authorized' 响应的持续时间。与设置 --authorization-webhook-cache-authorized-ttl 标志相同。默认值：5m0s。

缓存 Webhook 授权者 'unauthorized' 响应的持续时间。与设置 --authorization-webhook-cache-unauthorized-ttl 标志相同。默认值：30s。

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

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

MatchConditionSubjectAccessReviewVersion 指定 CEL 表达式评估所依据的 SubjectAccessReview 版本。有效值：v1。必需，无默认值。

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

• NoOpinion：继续到后续的授权者，查看其中是否有允许该请求的
• Deny：拒绝请求，不咨询后续授权者。必需，无默认值。

ConnectionInfo 定义了如何与 Webhook 通信

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

具体的匹配逻辑如下（按顺序）：

1. 如果至少一个 matchCondition 评估结果为 FALSE，则跳过 Webhook。
2. 如果所有 matchConditions 评估结果都为 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 评估的表达式。必须评估为 bool。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.ac.cn/docs/reference/using-api/cel/