kube-apiserver 配置 (v1alpha1)

采集器的端点，此组件将向其报告跟踪信息。 连接不安全，目前不支持 TLS。 推荐不设置，端点为 otlp grpc 默认值 localhost:4317。

SamplingRatePerMillion 是每百万 span 中采集的样本数。 推荐不设置。如果不设置，采集器将继承其父级 span 的采样率，否则不进行采样。

plugins 允许用户为每个准入控制插件指定设置。

jwt 是一个身份认证器列表，用于对使用符合 JWT 的令牌的 Kubernetes 用户进行身份认证。 身份认证器将尝试解析原始 ID 令牌，验证其是否由配置的发放者签名。用于验证签名的公钥是通过 OIDC 发现从颁发者的公开端点获取的。对于传入的令牌，将按照此列表中指定的顺序尝试每个 JWT 身份认证器。但是请注意，其他身份认证器可能会在 JWT 身份认证器之前或之后运行。JWT 身份认证器相对于其他身份认证器的具体位置在不同版本中既未定义也不稳定。由于每个 JWT 身份认证器必须具有唯一的颁发者 URL，因此最多只有一个 JWT 身份认证器会尝试基于密码学方法对对令牌进行合法性检查。

最小有效 JWT 负载必须包含以下声明：

{
    "iss": "https://issuer.example.com",
    "aud": ["audience"],
    "exp": 1234567890,
    "<username claim>": "username"
}

如果设置了此字段，则不得设置 --anonymous-auth。

authorizers 是一个有序的鉴权器列表，用于对请求进行鉴权。 这类似于 kube-apiserver --authorization-modes 标志。 此列表不能为空。

connectionServices 包含一组 Egress 选择算符客户端配置选项。

嵌入组件配置中的跟踪配置结构体。

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

path 为指向包含插件配置数据的配置文件的路径。

configuration 是一个嵌入的配置对象，用作插件的配置数据来源。 如果设置了此字段，则使用此字段而不是指向配置文件的路径。

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

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

type 指的是鉴权器的类型。 通用 API 服务器支持 "Webhook"。 其他 API 服务器可能支持其他授权者类型，如 Node、RBAC、ABAC 等。

name 是用于描述 webhook 的名称。 此字段专为监控机制中的指标提供。 注意：name 值必须是 DNS1123 标签，如 myauthorizername， 或子域名，如 myauthorizer.example.domain。 必需，没有默认值。

webhook 定义 Webhook 鉴权器的配置。 当 type=Webhook 时必须定义。 当 type!=Webhook 时不得定义。

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"。 对于身份认证配置，声明或前缀都没有默认值。声明和前缀必须显式设置。 对于声明，如果在传统标志方法中未设置 --oidc-username-claim， 请在身份认证配置中配置 username.claim="sub"。 对于前缀： (1) --oidc-username-prefix="-", 未添加前缀到用户名。要实现相同的行为，请在身份认证配置中设置 username.prefix="" (2) --oidc-username-prefix="" 并且 --oidc-username-claim != "email"， 前缀为 "<--oidc-issuer-url 的值>#"。要实现相同的行为，请在身份认证配置中设置 username.prefix="<issuer.url 的值>#"。 (3) --oidc-username-prefix="<value>"。要实现相同的行为，请在身份认证配置中设置 username.prefix="<value>"。

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

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

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

硬编码的额外 key/value

- key: "foo"
   valueExpression: "'bar'"

硬编码 key，value 从声明的值复制

 - key: "foo"
   valueExpression: "claims.some_claim"

结果会是一个 extra 属性 - foo: [some_claim 的值]

硬编码 key，value 从声明的值派生

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

与 claim 互斥。

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

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

expression 表示将由 CEL 求值的表达式。 必须生成一个布尔值。

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

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

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

与 claim 和 requiredValue 互斥。

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

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

transport 定义的是传输层的配置。我们使用这个配置来联系 konnectivity 服务器。 当 proxyProtocol 是 HTTPConnect 或 GRPC 时需要设置此字段。

name 是 Egress 选择器的名称。当前支持的取值有 "controlplane"， "master"，"etcd" 和 "cluster"。 "master" Egress 选择器已被弃用，推荐使用 "controlplane"。

connection 是用来配置 Egress 选择器的配置信息。

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

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

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

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

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

url 指向颁发者 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 端点托管在与颁发者不同的位置（例如在集群中本地托管）的场景。

示例： 发现 URL 是通过 Kubernetes 在命名空间 'oidc-namespace' 中的服务 'oidc' 公布的， 而访问 '/.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.io/zh-cn/docs/reference/using-api/cel/

与 claim 和 prefix 互斥。

url 是要连接的 konnectivity 服务器的位置。例如 "https://127.0.0.1:8131"。

tlsConfig 是使用 TLS 来连接 konnectivity 服务器时需要的信息。

caBundle 是指向用来确定与 konnectivity 服务器间信任欢喜的 CA 证书包的文件位置。 当 tcpTransport.url 前缀为 "http://" 时必须不设置，或者设置为空。 如果 tcpTransport.url 前缀为 "https://" 并且此字段未设置，则默认使用系统的信任根。

clientKey 是与 konnectivity 服务器进行 mTLS 握手时使用的客户端秘钥文件位置。 如果 `tcp.url` 前缀为 http://，必须不指定或者为空； 如果 `tcp.url` 前缀为 https://，必须设置。

clientCert 是与 konnectivity 服务器进行 mTLS 握手时使用的客户端证书文件位置。 如果 `tcp.url` 前缀为 http://，必须不指定或者为空； 如果 `tcp.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 对象 关于 UserInfo 的定义，参阅 https://github.com/kubernetes/api/blob/release-1.28/authentication/v1/types.go#L105-L122。 API 文档：https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#userinfo-v1-authentication-k8s-io

关于 CEL 的文档：https://kubernetes.io/zh-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 请求超时时间。允许的最大时间为 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. 如果所有 matchConditions 计算结果为 TRUE，则调用 Webhook。
3. 如果至少一个 matchCondition 计算结果为错误（但没有一个为 FALSE）：
   • 如果 FailurePolicy=Deny，则 Webhook 拒绝请求
   • 如果 FailurePolicy=NoOpinion，则忽略错误并跳过 Webhook

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

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

包含连接信息的 KubeConfig 文件的路径。 如果 connectionInfo.type 是 KubeConfig，则为必需项。

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

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