kube-apiserver 配置 (v1beta1)

此组件将跟踪报告到的收集器的端点。连接是不安全的，目前不支持 TLS。推荐的做法是将其设置为空，端点为 otlp grpc 默认值 localhost:4317。

SamplingRatePerMillion 是每百万个 span 收集的样本数。推荐的做法是将其设置为空。如果设置为空，则采样器将尊重其父 span 的采样率，但否则永远不会进行采样。

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 标志类似。必须至少有一个。

connectionServices 包含一组出口选择器客户端配置

嵌入组件配置跟踪结构体

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

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

Type 指示授权器的类型。“Webhook”在通用 API 服务器中受支持。其他 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) == 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="" and --oidc-username-claim != "email"，前缀为 "<--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"]

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

• 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' 是一个声明名称到声明值的映射。例如，名为 'sub' 的变量可以通过 'claims.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' 是一个声明名称到声明值的映射。例如，名为 'sub' 的变量可以通过 'claims.sub' 访问。嵌套的声明可以使用点表示法访问，例如 'claims.foo.bar'。验证必须成功才能通过。

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 路径字符。key 必须是小写的。要求唯一。

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

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

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

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

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

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

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

示例：使用 Kubernetes 服务 'oidc' 在命名空间 'oidc-namespace' 中公开的 discovery 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: 前缀。验证规则在逻辑上是 AND 关系，必须全部返回 true 才能通过验证。

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

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

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

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

• 'claims' 是一个声明名称到声明值的映射。例如，名为 'sub' 的变量可以通过 'claims.sub' 访问。嵌套的声明可以使用点表示法访问，例如 '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:// 开头，则必须 absent/empty。如果 TCPTransport.URL 以 https:// 开头且 absent，则默认为系统信任的根证书。

clientKey 是在与 konnectivity 服务器进行 mtls 握手中使用的客户端密钥的文件位置。如果 TCPTransport.URL 以 http:// 开头，则必须 absent/empty。如果 TCPTransport.URL 以 https:// 开头，则必须配置。

clientCert 是在与 konnectivity 服务器进行 mtls 握手中使用的客户端证书的文件位置。如果 TCPTransport.URL 以 http:// 开头，则必须 absent/empty。如果 TCPTransport.URL 以 https:// 开头，则必须配置。

TCP 是通过 TCP 与 konnectivity 服务器通信的 TCP 配置。目前 GRPC 的 ProxyProtocol 不支持 TCP 传输。要求设置 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 授权器“已授权”响应的时长。与设置 --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 个 match condition。

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

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 表达式可以访问 SubjectAccessReview 的内容，版本为 v1。如果请求变量中指定的 subjectAccessReviewVersion 为 v1beta1，则内容将被转换为 v1 版本后再评估 CEL 表达式。

• '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/