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

connectionServices 包含一系列出口选择客户端的配置。

嵌入组件配置跟踪结构体

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

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

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

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

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

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'，则 'claims.email_verified' 必须在 username.expression 或 extra[*].valueExpression 或 claimValidationRules[<*>].expression 中使用。一个示例声明验证规则表达式，该表达式匹配当 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="" 且 --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"]

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

• 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'。必须返回 true 才能使验证通过。

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

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

示例：使用 Kubernetes 服务 'oidc' 在命名空间 'oidc-namespace' 中公开的发现 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: 前缀。验证规则在逻辑上被 ANDed，并且所有规则都必须返回 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 的文件位置。如果 URL 以 http:// 开头，则必须不存在/为空。如果 URL 以 https:// 开头且不存在，则默认为系统信任根。

clientKey 是用于与 konnectivity 服务器进行 mtls 握手的客户端密钥的文件位置。如果 URL 以 http:// 开头，则必须不存在/为空。如果 URL 以 https:// 开头，则必须配置。

clientCert 是用于与 konnectivity 服务器进行 mtls 握手的客户端证书的文件位置。如果 URL 以 http:// 开头，则必须不存在/为空。如果 URL 以 https:// 开头，则必须配置。

TCP 是通过 TCP 与 konnectivity 服务器通信的 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 授权器“已授权”响应的时长。与设置 --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 版本）。如果请求变量中指定的版本是 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/