kube-apiserver 配置（v1beta1）

此组件将向其报告跟踪的收集器的端点。连接是不安全的，并且当前不支持 TLS。建议不设置，并且端点是 otlp grpc 默认值，localhost:4317。

SamplingRatePerMillion 是每百万个跨度收集的样本数。建议不设置。如果未设置，采样器将遵循其父跨度的采样率，否则永远不会采样。

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 是授权请求的授权器有序列表。这类似于 --authorization-modes kube-apiserver 标志。必须至少有一个。

connectionServices 包含出口选择客户端配置的列表

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

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

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

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

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

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'。当 username.claim 设置为 'email' 时，与自动应用的验证匹配的示例声明验证规则表达式是 '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"，prefix 是“<--oidc-issuer-url 的值>#”。对于使用身份验证配置的相同行为，设置 username.prefix="#" (3) --oidc-username-prefix=""。对于使用身份验证配置的相同行为，设置 username.prefix=""

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

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

extra 表示 extra 属性的选项。expression 必须生成字符串或字符串数组值。如果值为空，则不会显示 extra 映射。

硬编码的 extra 键/值

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

硬编码的键，值复制声明值

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

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

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

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

expression 表示将由 CEL 计算的表达式。

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

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

有关 CEL 的文档：https://kubernetes.top/zh-cn/docs/reference/using-api/cel/

与 claim 互斥。

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

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

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

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

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

有关 CEL 的文档：https://kubernetes.top/zh-cn/docs/reference/using-api/cel/

与 claim 和 requiredValue 互斥。

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

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

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

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

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

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.top/zh-cn/docs/reference/using-api/cel/

url 指向格式为 https://url 或 https://url/path 的颁发者 URL。这必须与所提供的 JWT 中的 “iss” 声明以及从发现返回的颁发者相匹配。与 --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” 声明。这适用于 well-known 和 jwks 端点托管在与颁发者不同的位置（例如在集群本地）的场景。

示例：使用命名空间 “oidc-namespace” 中的 kubernetes 服务 “oidc” 公开的发现 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” 声明匹配。与 --oidc-client-id 标志的值相同（尽管此字段支持数组）。必须为非空。

audienceMatchPolicy 定义了如何使用 “audiences” 字段来匹配所提供的 JWT 中的 “aud” 声明。允许的值为

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

• MatchAny：所提供的 JWT 中的 “aud” 声明必须与 “audiences” 字段中的至少一个条目匹配。例如，如果 “audiences” 是 [“foo”, “bar”]，则所提供的 JWT 中的 “aud” 声明必须包含 “foo” 或 “bar”（并且可能同时包含两者）。

• ""：当 “audiences” 字段中指定单个受众时，匹配策略可以为空（或未设置）。所提供的 JWT 中的 “aud” 声明必须包含单个受众（并且可能包含其他受众）。

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

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

claimValidationRules 是用于验证令牌声明以对用户进行身份验证的规则。

claimMappings 指向要被视为用户属性的令牌声明。

userValidationRules 是在完成身份验证之前应用于最终用户的规则。这些规则允许将不变量应用于传入的身份，例如防止使用 Kubernetes 组件常用的 system: 前缀。验证规则在逻辑上与在一起，并且必须全部返回 true 才能通过验证。

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

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

expression 表示将由 CEL 计算的表达式。

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

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

有关 CEL 的文档：https://kubernetes.top/zh-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.top/docs/reference/generated/kubernetes-api/v1.28/#userinfo-v1-authentication-k8s-io

有关 CEL 的文档：https://kubernetes.top/zh-cn/docs/reference/using-api/cel/

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

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

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

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

要发送到 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. 如果所有 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' 对应于身份验证器中的 user.Info.GetExtra() 方法。
• 'uid' 是关于请求用户的的信息。例如：request.uid == '1'

有关 CEL 的文档：https://kubernetes.top/zh-cn/docs/reference/using-api/cel/