第 5 章 ValidatingAdmissionPolicy [admissionregistration.k8s.io/v1]

auditAnnotations

数组

auditAnnotations 包含 CEL 表达式，用于为 API 请求的审计事件生成审计注解。验证和 auditAnnotations 可能并不为空；至少需要一个验证或 auditAnnotations。

auditAnnotations[]

object

AuditAnnotation 描述了如何为 API 请求生成审计注解。

failurePolicy

string

failurePolicy 定义如何处理准入策略失败。CEL 表达式解析错误、类型检查错误、运行时错误和无效或配置的策略定义或绑定可能会出现失败。

如果 spec.paramKind 指向不存在的 Kind，则策略无效。如果 spec.paramRef.name 指的是不存在的资源，则绑定无效。

failurePolicy 不定义如何处理评估为 false 的验证。

当 failurePolicy 设置为 Fail 时，ValidatingAdmissionPolicyBinding validationActions 定义如何强制实施失败。

允许的值是 Ignore 或 Fail。默认为 Fail。

可能枚举值： - "Fail" 表示调用 Webhook 的错误会导致准入失败。- "Ignore" 表示调用 Webhook 的错误会被忽略。

matchConditions

数组

MatchConditions 是验证请求必须满足的条件列表。匹配条件过滤请求，它们已与 rules、namespaceSelector 和 objectSelector 匹配。空 matchConditions 列表与所有请求匹配。允许最多有 64 个匹配条件。

如果提供了参数对象，它可以通过 params 处理，其方式与验证表达式相同。

完全匹配逻辑为（按顺序）：1。如果 ANY matchCondition 评估为 FALSE，则会跳过策略。2.如果 ALL matchConditions 评估为 TRUE，则会评估策略。3.如果任何 matchCondition 评估为错误（但没有是 FALSE）： - 如果 failurePolicy=Fail，拒绝请求 - If failurePolicy=Ignore，则会跳过策略

matchConditions[]

object

MatchCondition 代表一个条件，需要满足该条件才能将请求发送到 webhook。

matchConstraints

object

MatchResources 决定是否根据它是否满足匹配标准在对象上运行准入控制策略。排除规则优先于 include 规则（如果资源同时匹配，则会排除它）

paramKind

object

ParamKind 是 Group Kind 和 Version 的元组。

验证

数组

验证包含用于应用验证的 CEL 表达式。验证和审计注解可能并不为空，至少需要一个 Validations 或 AuditAnnotations。

validations[]

object

validation 指定用来应用验证的 CEL 表达式。

变量

数组

变量包含可用于组成其他表达式的变量的定义。每个变量都定义为命名的 CEL 表达式。这里定义的变量将在策略的其他表达式中的 变量 下提供，但 MatchConditions 除外，因为 MatchConditions 在策略的其余部分之前评估。

变量的表达式可以引用之前在列表中定义的其他变量，但不能引用之后定义的变量。因此，变量必须按照第一个外观和 acyclic 的顺序进行排序。

variables[]

object

变量是变量的定义，用于组成。变量定义为命名表达式。

key

string

key 指定审计注解键。ValidatingAdmissionPolicy 的 audit 注解键必须是唯一的。密钥必须是限定名称([A-Za-z0-9][-A-Za-z0-9_.]*)长度不超过 63 字节。

键与 ValidatingAdmissionPolicy 的资源名称相结合，以构造审计注解键："{ValidatingAdmissionPolicy name}/{key}"。

如果准入 webhook 使用与这个 ValidatingAdmissionPolicy 和相同的审计注解键相同的资源名称，则注解键将相同。在这种情况下，使用密钥编写的第一个注解将包含在审计事件中，所有具有相同键的后续注解都会被丢弃。

必需。

valueExpression

string

valueExpression 代表 CEL 评估的表达式来生成审计注解值。表达式必须评估为字符串或 null 值。如果表达式评估为字符串，则 audit 注解会包含在字符串值中。如果表达式评估为 null 或空字符串，则会省略 audit 注解。值Expression 长度不超过 5kb。如果 valueExpression 的结果长度超过 10kb，它将被截断为 10kb。

如果多个 ValidatingAdmissionPolicyBinding 资源与 API 请求匹配，则会为每个绑定评估 valueExpression。valueExpressions 生成的所有唯一值都将在以逗号分隔的列表中合并。

必需。

expression

string

expression 代表将由 CEL 评估的表达式。必须评估 bool。CEL 表达式可以访问 AdmissionRequest 和 Authorizer 的内容，并组织成 CEL 变量：

'object' - 来自传入请求的对象。对于 DELETE 请求，值为 null。'oldObject' - 现有对象。CREATE 请求的值是 null。'request' - 准入请求的属性(/pkg/apis/admission/types.go:AdmissionRequest)'authorizer' - A CEL Authorizer。可用于对请求的主体（用户或服务帐户）执行授权检查。请参阅 https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz 'authorizer.requestResource' - 从 'authorizer' 构建并使用请求资源配置的 CEL ResourceCheck。有关 CEL 的文档 ：https://kubernetes.io/docs/reference/using-api/cel/

必需。

名称

string

name 是此匹配条件的标识符，用于战略合并 MatchConditions，并提供用于日志记录目的的标识符。相关表达式的描述性应为一个好名称。name 必须是包括字母数字字符、'-'、'' 或 '.' 的合格名称，且必须以字母数字字符开头和结尾（例如。'MyName', 或 'my.name', 或 '123-abc', 用于验证的 regex 为 '([A-Za-z0-9][-A-Za-z0-9.]*)?[A-Za-z0-9]'），带有可选的 DNS 子域前缀和 '/'（如 'example.com/MyName'）

必需。

excludeResourceRules

数组

ExcludeResourceRules 描述了 ValidatingAdmissionPolicy 不应关注哪些资源/子资源的操作。排除规则优先于 include 规则（如果资源同时匹配，则会排除它）

excludeResourceRules[]

object

NamedRuleWithOperations 是 Operations 和 ResourceNames 的元组。

matchPolicy

string

matchPolicy 定义如何使用 "MatchResources" 列表来匹配传入的请求。允许的值是 "Exact" 或 "Equivalent"。

- exact ：仅在与指定规则完全匹配时才匹配请求。例如，如果可通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 修改部署，但 "rules" 仅包含 apiGroups:["apps"], apiVersions:["v1"]，resources: ["deployments"]，对 apps/v1beta1 或 extensions/v1beta1 的请求不会发送到 ValidatingAdmissionPolicy。

- equivalent ：如果修改规则中列出的资源，即使通过另一个 API 组或版本来匹配请求。例如，如果可通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 和 "rules" 修改部署，则只有 apiGroups:["apps"], apiVersions:["v1"]，resources: ["deployments"]，请求 apps/v1beta1 或 extensions/v1beta1 将转换为 apps/v1beta1，并发送到 ValidatingAdmissionPolicy。

默认为 "Equivalent"

可能枚举值：- "Equivalent" 表示如果请求通过另一个 API 组或版本修改规则中列出的资源，则应只将请求发送到 webhook。

namespaceSelector

LabelSelector

namespaceSelector 决定是否根据该对象的命名空间与选择器匹配来在对象上运行准入控制策略。如果对象本身是命名空间，则在 object.metadata.labels 上执行匹配。如果对象是另一个集群范围的资源，则永远不会跳过策略。

例如，要在命名空间没有与 "0" 或 "1" 的 "runlevel" 关联的对象上运行 webhook；您将设置选择器，如下所示： "namespaceSelector": { "matchExpressions": [ { "key": "runlevel", "operator": "NotIn", "values": [ "0", "1" ] } ] }

如果您希望仅在任何命名空间与 "prod" 或 "staging" 关联的对象上运行策略；您将选择器设置为如下所示： "namespaceSelector": { "matchExpressions": [ { "key": "environment", "operator": "In", "values": [ "prod", "staging" ] } ] }

有关标签选择器的更多信息，请参阅 https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/。

默认为空 LabelSelector，它将匹配所有内容。

objectSelector

LabelSelector

objectSelector 决定是否根据对象是否匹配标签运行验证。objectSelector 针对发送到 cel 验证的 oldObject 和 newObject 评估，如果任何一个对象与选择器匹配，则被视为匹配。一个 null 对象（如果是 create, 或 newObject in the delete 时），或没有标签（如 DeploymentRollback 或 PodProxyOptions 对象）的对象不会被认为匹配。只有在 webhook 是 opt-in 时才使用对象选择器，因为最终用户可以通过设置标签来跳过准入 Webhook。默认为空 LabelSelector，它将匹配所有内容。

resourceRules

数组

resourceRules 描述了 ValidatingAdmissionPolicy 匹配的资源/资源什么操作。如果某个操作 与任何 规则匹配，则策略会监视它。

resourceRules[]

object

NamedRuleWithOperations 是 Operations 和 ResourceNames 的元组。

apiGroups

数组（字符串）

apiGroups 是资源所属的 API 组。'' 是所有组。如果存在 ''，则片段的长度必须是一。必需。

apiVersions

数组（字符串）

APIVersions 是资源所属的 API 版本。'' 是所有版本。如果存在 ''，则片段的长度必须是一。必需。

操作

数组（字符串）

操作是准入 hook 为所有操作以及添加的任何准入操作( CREATE、UPDATE、DELETE、CONNECT 或 *)的操作。如果 '*' 存在，则片段的长度必须是一。必需。

resourceNames

数组（字符串）

resourceNames 是一个可选的规则应用到的名称白名单。空集表示所有都会被允许。

resources

数组（字符串）

resources 是一组这个规则应用到的资源列表。

例如： 'pods' 表示 pod。'pods/log' 表示 pod 的日志子资源。' ' 表示所有资源，但不是子资源。'pods/' 表示所有 pod 子资源。'/scale' 表示所有 scale 子资源。'Suffix' 表示所有资源及其子资源。

如果存在通配符，验证规则将确保资源不会相互重叠。

根据封闭对象，可能无法允许子资源。必需。

scope

字符串

scope 指定此规则的范围。有效值为 "Cluster", "Namespaced", 和 "" "Cluster" 表示只有集群范围的资源与此规则匹配。命名空间 API 对象是集群范围的。"namespaced" 表示只有命名空间的资源将与此规则匹配。"" 表示没有范围限制。子资源与其父资源的范围匹配。默认为 "*"。

apiGroups

数组（字符串）

apiGroups 是资源所属的 API 组。'' 是所有组。如果存在 ''，则片段的长度必须是一。必需。

apiVersions

数组（字符串）

APIVersions 是资源所属的 API 版本。'' 是所有版本。如果存在 ''，则片段的长度必须是一。必需。

操作

数组（字符串）

操作是准入 hook 为所有操作以及添加的任何准入操作( CREATE、UPDATE、DELETE、CONNECT 或 *)的操作。如果 '*' 存在，则片段的长度必须是一。必需。

resourceNames

数组（字符串）

resourceNames 是一个可选的规则应用到的名称白名单。空集表示所有都会被允许。

resources

数组（字符串）

resources 是一组这个规则应用到的资源列表。

例如： 'pods' 表示 pod。'pods/log' 表示 pod 的日志子资源。' ' 表示所有资源，但不是子资源。'pods/' 表示所有 pod 子资源。'/scale' 表示所有 scale 子资源。'Suffix' 表示所有资源及其子资源。

如果存在通配符，验证规则将确保资源不会相互重叠。

根据封闭对象，可能无法允许子资源。必需。

scope

字符串

scope 指定此规则的范围。有效值为 "Cluster", "Namespaced", 和 "" "Cluster" 表示只有集群范围的资源与此规则匹配。命名空间 API 对象是集群范围的。"namespaced" 表示只有命名空间的资源将与此规则匹配。"" 表示没有范围限制。子资源与其父资源的范围匹配。默认为 "*"。

apiVersion

string

apiVersion 是资源所属的 API 组版本。格式为 "group/version"。必需。

kind

string

kind 是资源所属的 API 类型。必需。

expression

string

expression 代表 CEL 评估的表达式。https://github.com/google/cel-spec CEL 表达式可以访问 API 请求/响应的内容，并被组织到 CEL 变量中，以及其他一些有用的变量：

- 'object' - 来自传入请求的对象。对于 DELETE 请求，值为 null。- 'oldObject' - 现有对象。对于 CREATE 请求，值为 null。- 'request' - API 请求的属性([ref](/pkg/apis/admission/types.goReactAdmissionRequest))。- 'params' - Parameter resource 引用由策略绑定被评估。只有策略有一个 ParamKind. - 'namespaceObject' - 传入对象所属命名空间对象时填充。对于集群范围的资源，值为 null。- 'variables' - 组合变量的映射，从其名称到 lazily 评估的值。例如，名为 'foo' 的变量可作为 'variables.foo'. - 'authorizer' - A CEL Authorizer 访问。可用于对请求的主体（用户或服务帐户）执行授权检查。请参阅 https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz - 'authorizer.requestResource' - 从 'authorizer' 构建并使用请求资源配置的 CEL ResourceCheck。

apiVersion、kind、metadata.name 和 metadata.generateName 始终可从对象的根目录访问。无法访问其他元数据属性。

只有 [a-zA-Z_.-/][a-zA-Z0-9_.-/]* 的属性名称才可以访问。在表达式中访问时，访问的属性名称会按照以下规则进行转义： - 'scaps to 'underscores' - '.' escapes to'dot' - '-' escapes to 'dash' - '/' escapes to 'slash' - Property name that exactly match a CEL RESERVED keyword escape to '{keyword}''.关键字有："true", "false", "null", "in", "as", "break", "const", "continue", "else", "for", "function", "if", "import", "let", "loop", "package", "namespace", "return"。示例： - 表达式访问名为 "namespace": {"Expression": "object.namespace > 0"} 的属性 - Expression 访问名为 "x-prop": {"Expression": "object.xdashprop > 0"} - Expression access a attribute named "redactd": {"Expression": "object.redactunderscoresd > 0"}

等于列表类型为 'set' 或 'map' 的数组，即 [1, 2] == [2, 1]。与 x-kubernetes-list-type 的数组连接会使用列表类型的语义： - 'set': X + Y 会执行联合，其中 X + Y 将保留所有元素的数组位置，并在 Y 中附加非交集元素，保留其部分顺序。- 'map': X + Y 执行合并，其中保留所有键的阵列位置，但在 Y 中保留值，保留其部分顺序。带有非交集键的 Y 中的元素会附加，保留其部分顺序。必需。

message

string

Message 代表验证失败时显示的消息。如果 Expression 包含换行符，则需要消息。消息不得包含换行符。如果未设置，则消息为 "failed rule: {Rule}"。例如，如果 Expression 包含换行符，则必须是一个与 spec.host 匹配的主机的 URL。需要消息。消息不得包含换行符。如果未设置，则消息为 "failed Expression: {Expression}"。

messageExpression

string

messageExpression 声明了一个 CEL 表达式，它评估到此规则失败时返回的验证失败消息。由于 messageExpression 用作失败消息，它必须评估为字符串。如果验证中同时存在 message 和 messageExpression，则在验证失败时将使用 messageExpression。如果 messageExpression 导致运行时错误，则会记录运行时错误，并且生成验证失败消息，就像 messageExpression 字段未设置一样。如果 messageExpression 评估为空字符串、仅包含空格的字符串，或者包含换行符的字符串，则也会生成验证失败消息，就如 messageExpression 字段未设置，并且消息Expression 生成一个空字符串/字符串，且只有有换行符的空格/字符串会被记录。messageExpression 可以访问与 'authorizer' 和 'authorizer.request' 以外的 表达式 以外的所有相同的变量。示例："object.x 必须小于 max ("string (params.max) ") "

reason

string

reason 表示此验证失败的原因的机器可读描述。如果这是列表中的第一个验证失败，这个原因以及相应的 HTTP 响应代码将在 HTTP 响应中用于客户端。目前支持的原因包括："Unauthorized", "Forbidden", "Invalid", "RequestEntityTooLarge"。如果没有设置，则对客户端的响应将使用 StatusReasonInvalid。

expression

string

expression 是将评估为 变量的值的表达式。CEL 表达式可以访问与 Validation 中的 CEL 表达式相同的标识符。

名称

string

name 是变量的名称。名称必须是有效的 CEL 标识符，且在所有变量中是唯一的。变量可以通过变量访问其他表达式中，例如，如果 name 是 "foo"，则变量将作为 variables.foo提供

conditions

数组（条件）

条件代表策略当前状态的最新可用影响。

observedGeneration

整数

控制器观察到的生成。

typeChecking

object

TypeChecking 包含在 ValidatingAdmissionPolicy 中检查表达式的类型结果

expressionWarnings

数组

每个表达式的类型检查警告。

expressionWarnings[]

object

ExpressionWarning 是一个以特定表达式为目标的警告信息。

fieldRef

string

引用表达式的字段的路径。例如，引用验证的第一个项的表达式为 "spec.validations[0].expression"

warning

string

以人类可读形式检查信息的类型内容。警告的每一行包含表达式被检查的类型，后跟编译器中的类型检查错误。