kube-apiserver 配置 (v1beta1)

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

每百万采样率是每百万个 Span 收集的样本数。建议不设置。如果未设置，则采样器遵循其父 Span 的采样率，但否则从不采样。

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

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

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

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

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

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

用于描述 Webhook 的名称 这在指标的监控机制中明确使用 注意：名称必须是 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="<值>"。对于使用身份验证配置的相同行为，请设置 username.prefix="<值>"

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

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

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

硬编码的额外键/值

• 键："foo" 值表达式："'bar'" 这将导致一个额外的属性 - foo: ["bar"]

硬编码键，值复制声明值

• 键："foo" 值表达式："claims.some_claim" 这将导致一个额外的属性 - foo: [some_claim 的值]

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

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

声明是要使用的 JWT 声明。必须设置声明或表达式。与表达式互斥。

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

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

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

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

与声明互斥。

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

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

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

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

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

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

与 claim 和 requiredValue 互斥。

当表达式返回 false 时，message 自定义返回的错误消息。message 是一个字符串字面量。与 claim 和 requiredValue 互斥。

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

Transport 定义了我们用于连接到 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' 是一个声明名称到声明值的映射。例如，名为 'sub' 的变量可以通过 'claims.sub' 访问。嵌套声明可以使用点符号访问，例如 'claims.foo.bar'。

有关 CEL 的文档：https://kubernetes.ac.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: 前缀。验证规则在逻辑上进行 AND 运算，并且必须全部返回 true 才能通过验证。

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

prefix 被添加到 claim 的值之前，以防止与现有名称冲突。如果设置了 claim，则需要设置 prefix，并且可以为空字符串。与 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:// 开头，则必须为空/不存在。如果 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 是要连接到的 unix 域套接字的名称，用于连接到 konnectivity 服务器。它不使用 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/

当规则返回 false 时，message 自定义返回的错误消息。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. 如果所有 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 的内容。如果 request 变量中 subjectAccessReviewVersion 指定的版本为 v1beta1，则在计算 CEL 表达式之前，内容将转换为 v1 版本。

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