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

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 表示 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 属性的选项。声明的值必须是字符串或字符串数组声明。如果设置了 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 声明。必须设置声明或表达式。与表达式互斥。

expression 表示将由 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，则声明必须存在且值设置为空字符串。与表达式和消息互斥。

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

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

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

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

与声明和 requiredValue 互斥。

message 在表达式返回 false 时自定义返回的错误消息。消息是一个文字字符串。与声明和 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 指向发行者 URL，格式为 https://url 或 https://url/path。这必须与提供的 JWT 中的 "iss" claim 以及从发现返回的发行者相匹配。与 --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" claim。这适用于 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" claim 相匹配。与 --oidc-client-id 标志的值相同（尽管此字段支持数组）。不能为空。

audienceMatchPolicy 定义如何使用 "audiences" 字段来匹配提供的 JWT 中的 "aud" claim。允许的值为

1. 指定多个受众时的 "MatchAny" 和
2. 指定单个受众时的空（或未设置）或 "MatchAny"。

• MatchAny：提供的 JWT 中的 "aud" claim 必须至少与 "audiences" 字段中的一个条目相匹配。例如，如果 "audiences" 是 ["foo", "bar"]，则提供的 JWT 中的 "aud" claim 必须包含 "foo" 或 "bar"（并且可以同时包含两者）。

• ""：当 "audiences" 字段中指定了单个受众时，匹配策略可以为空（或未设置）。提供的 JWT 中的 "aud" claim 必须包含单个受众（并且可以包含其他受众）。

有关更细致的受众验证，请使用 claimValidationRules。例如：claimValidationRule[].expression: 'sets.equivalent(claims.aud, ["bar", "foo", "baz"])' 以要求完全匹配。

issuer 包含基本的 OIDC 提供程序连接选项。

claimValidationRules 是用于验证 token claim 以验证用户身份的规则。

claimMappings 指向要被视为用户属性的 token claim。

userValidationRules 是在完成身份验证之前应用于最终用户的规则。这些规则允许将不变量应用于传入的身份，例如防止使用 Kubernetes 组件常用的 system: 前缀。验证规则在逻辑上进行 AND 运算，并且必须全部返回 true 才能通过验证。

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

prefix 将被添加到 claim 值的前面，以防止与现有名称冲突。如果设置了 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 是要连接到的 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 计算的表达式。必须计算结果为 bool。CEL 表达式可以访问 v1 版本的 SubjectAccessReview 的内容。如果 request 变量中 subjectAccessReviewVersion 指定的版本为 v1beta1，则在计算 CEL 表达式之前，内容将转换为 v1 版本。

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