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" }

如果存在 --anonymous-auth 则必须不设置

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

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

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

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

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

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

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

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

Type 指的是授权器的类型。“Webhook”在通用 API 服务器中受支持。其他 API 服务器可能支持其他授权器类型，例如 Node、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"。对于身份验证配置，声明（claim）或前缀（prefix）没有默认值。必须显式设置声明和前缀。对于声明，如果在使用旧的标志方法时未设置 `--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="#"`。(3) `--oidc-username-prefix=""`。要使用身份验证配置实现相同的行为，请设置 `username.prefix=""`。

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

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

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

硬编码的额外键/值

• key: "foo" valueExpression: "'bar'" 这将导致一个额外的属性 - foo: ["bar"]

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

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

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

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

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'。必须返回 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` 标志的值相同。发现信息是从 "{url}/.well-known/openid-configuration" 获取的，除非被 discoveryURL 覆盖。在所有 JWT 身份验证器中必须是唯一的。请注意，出口选择配置不用于此网络连接。

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

获取的发现信息中的 "issuer" 字段必须与 AuthenticationConfiguration 中的 "issuer.url" 字段匹配，并且将用于验证提供的 JWT 中的 "iss" 声明。这适用于已知端点和 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`，则需要设置 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:// 为前缀，则必须不存在/为空。如果当 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 请求的超时时间。允许的最大值为 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 不允许此模式。

用于连接信息的 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.ac.cn/docs/reference/using-api/cel/