此文档中的信息可能已过时
此文档的更新日期比原文晚,因此其中的信息可能已过时。如果能阅读英文,请查看英文版本以获取最新信息: ValidatingWebhookConfiguration
ValidatingWebhookConfiguration
apiVersion: admissionregistration.k8s.io/v1
import "k8s.io/api/admissionregistration/v1"
ValidatingWebhookConfiguration
ValidatingWebhookConfiguration 描述准入 Webhook 的配置,该 Webhook 可在不更改对象的情况下接受或拒绝对象请求。
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata (ObjectMeta)
标准的对象元数据,更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata。
webhooks ([]ValidatingWebhook)
补丁策略:根据
name
键执行合并操作webhooks 是 Webhook 以及受影响的资源和操作的列表。
ValidatingWebhook 描述了一个准入 Webhook 及其适用的资源和操作。
webhooks.admissionReviewVersions ([]string), 必需
admissionReviewVersions 是 Webhook 期望的首选
AdmissionReview
版本的有序列表。 API 服务器将尝试使用它支持的列表中的第一个版本。如果 API 服务器不支持此列表中指定的版本,则此对象将验证失败。 如果持久化的 Webhook 配置指定了允许的版本,并且不包括 API 服务器已知的任何版本,则对 Webhook 的调用将失败并受失败策略的约束。
webhooks.clientConfig (WebhookClientConfig), 必需
clientConfig 定义了如何与 Webhook 通信。必需。
WebhookClientConfig 包含与 Webhook 建立 TLS 连接的信息
webhooks.clientConfig.caBundle ([]byte)
caBundle
是一个 PEM 编码的 CA 包,将用于验证 Webhook 的服务证书。如果未指定,则使用 apiserver 上的系统信任根。
webhooks.clientConfig.service (ServiceReference)
service
是对此 Webhook 服务的引用。必须指定service
或url
。如果 Webhook 在集群中运行,那么你应该使用
service
。ServiceReference 持有对 Service.legacy.k8s.io 的引用
webhooks.clientConfig.service.name (string), 必需
name
是服务的名称。必需。
webhooks.clientConfig.service.namespace (string), 必需
namespace
是服务的命名空间。必需。
webhooks.clientConfig.service.path (string)
path
是一个可选的 URL 路径,它将发送任何请求到此服务。
webhooks.clientConfig.service.port (int32)
如果指定,则为托管 Webhook 的服务上的端口。默认为 443 以实现向后兼容性。
port
应该是一个有效的端口号(包括 1-65535)。
webhooks.clientConfig.url (string)
url
以标准 URL 形式(scheme://host:port/path
)给出了 Webhook 的位置。必须指定url
或service
中的一个。host
不应指代在集群中运行的服务;请改用service
字段。在某些 apiserver 中,可能会通过外部 DNS 解析host
。 (例如,kube-apiserver
无法解析集群内 DNS,因为这会违反分层原理)。host
也可以是 IP 地址。请注意,使用
localhost
或127.0.0.1
作为host
是有风险的,除非你非常小心地在运行 apiserver 的所有主机上运行此 Webhook, 而这些 API 服务器可能需要调用此 Webhook。此类部署可能是不可移植的,即不容易在新集群中重复安装。该方案必须是 “https”;URL 必须以 “https://” 开头。
路径是可选的,如果存在,可以是 URL 中允许的任何字符串。你可以使用路径将任意字符串传递给 Webhook,例如集群标识符。
不允许使用用户或基本身份验证,例如不允许使用 “user:password@”。 不允许使用片段(“#...”)和查询参数(“?...”)。
webhooks.name (string), 必需
准入 Webhook 的名称。应该是完全限定的名称,例如 imagepolicy.kubernetes.io,其中 “imagepolicy” 是 Webhook 的名称, kubernetes.io 是组织的名称。必需。
- webhooks.sideEffects (string), 必需
sideEffects 说明此 Webhook 是否有副作用。可接受的值为:None、NoneOnDryRun(通过 v1beta1 创建的 Webhook 也可以指定 Some 或 Unknown)。 具有副作用的 Webhook 必须实现协调系统,因为请求可能会被准入链中的未来步骤拒绝,因此需要能够撤消副作用。 如果请求与带有 sideEffects == Unknown 或 Some 的 Webhook 匹配,则带有 dryRun 属性的请求将被自动拒绝。
- webhooks.failurePolicy (string)
failurePolicy 定义了如何处理来自准入端点的无法识别的错误 - 允许的值是 Ignore 或 Fail。默认为 Fail。
- webhooks.matchConditions ([]MatchCondition)
补丁策略:根据
name
键的取值合并Map:name 键的唯一值将在合并期间保留
matchConditions 是将请求发送到此 webhook 之前必须满足的条件列表。 匹配条件过滤已经被 rules、namespaceSelector、objectSelector 匹配的请求。 matchConditions 取值为空列表时匹配所有请求。最多允许 64 个匹配条件。
精确匹配逻辑是(按顺序):
- 如果任一 matchCondition 的计算结果为 FALSE,则跳过该 webhook。
- 如果所有 matchConditions 的计算结果为 TRUE,则调用该 webhook。
- 如果任一 matchCondition 的计算结果为错误(但都不是 FALSE):
- 如果 failurePolicy=Fail,拒绝该请求;
- 如果 failurePolicy=Ignore,忽略错误并跳过该 webhook。
这是一个 Beta 功能特性,由 AdmissionWebhookMatchConditions 特性门控管理。
MatchCondition 表示将请求发送到 Webhook 之前必须满足的条件。
- webhooks.matchConditions.expression (string), 必需
expression 表示将由 CEL 求值的表达式。求值结果必须是 bool 值。CEL 表达式可以访问 以 CEL 变量的形式给出的 AdmissionRequest 和 Authorizer 的内容:
'object' - 来自传入请求的对象。对于 DELETE 请求,该值为 null。
'oldObject' - 现有对象。对于 CREATE 请求,该值为 null。
'request' - 准入请求的属性(/pkg/apis/admission/types.go#AdmissionRequest)。
'authorizer' - CEL 授权者。可用于对请求的主体(用户或服务帐户)执行授权检查。
参阅:https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz
- 'authorizer.requestResource' - CEL ResourceCheck 从"授权方"构建并配置请求资源。
CEL 文档:https://kubernetes.io/zh-cn/docs/reference/using-api/cel/
此字段为必需字段。
- webhooks.matchConditions.name (string), 必需
name 是此匹配条件的标识符,用于 MatchConditions 的策略性合并, 以及提供用于日志目的的标识符。一个好的 name 应该是对相关表达式的描述。 name 必须是由字母数字字符
-
、_
或.
组成的限定名称, 并且必须以字母、数字字符开头和结尾(例如MyName
、my.name
或123-abc
, 用于验证 name 的正则表达式是([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]
)。 带有可选的 DNS 子域前缀和/
(例如example.com/MyName
)此字段为必需字段。
webhooks.matchPolicy (string)
matchPolicy 定义了如何使用 "rules" 列表来匹配传入的请求。允许的值为 "Exact" 或 "Equivalent"。
Exact: 仅当请求与指定规则完全匹配时才匹配请求。 例如,如果可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 修改 deployments 资源, 但 “rules” 仅包含
apiGroups:["apps"]、apiVersions:["v1"]、resources:["deployments "]
, 对 apps/v1beta1 或 extensions/v1beta1 的请求不会被发送到 Webhook。Equivalent: 如果针对的资源包含在 “rules” 中,即使是通过另一个 API 组或版本,也视作匹配请求。 例如,如果可以通过 apps/v1、apps/v1beta1 和 extensions/v1beta1 修改 deployments 资源, 并且 “rules” 仅包含
apiGroups:["apps"]、apiVersions:["v1"]、resources:["deployments "]
, 对 apps/v1beta1 或 extensions/v1beta1 的请求将被转换为 apps/v1 并发送到 Webhook。
默认为 “Equivalent”。
webhooks.namespaceSelector (LabelSelector)
namespaceSelector 根据对象的命名空间是否与 selector 匹配来决定是否在该对象上运行 Webhook。
如果对象本身是命名空间,则在 object.metadata.labels 上执行匹配。 如果对象是另一个集群范围的资源,则永远不会跳过 Webhook 执行匹配。
例如,在命名空间与 “0” 或 “1” 的 “runlevel” 不关联的任何对象上运行 Webhook; 你可以按如下方式设置 selector :
"namespaceSelector": { "matchExpressions": [ { "key": "runlevel", "operator": "NotIn", "values": [ "0", "1" ] } ] }
相反,如果你只想在命名空间与 “prod” 或 “staging” 的 “environment” 相关联的对象上运行 Webhook;
你可以按如下方式设置 selector:
"namespaceSelector": { "matchExpressions": [ { "key": "environment", "operator": "In", "values": [ "prod", "staging" ] } ] }
有关标签选择算符的更多示例,请参阅
https://kubernetes.io/zh-cn/docs/concepts/overview/working-with-objects/labels。
默认为空的 LabelSelector,匹配所有对象。
webhooks.objectSelector (LabelSelector)
objectSelector 根据对象是否具有匹配的标签来决定是否运行 Webhook。 objectSelector 针对将被发送到 Webhook 的 oldObject 和 newObject 进行评估,如果任一对象与选择器匹配,则视为匹配。 空对象(create 时为 oldObject,delete 时为 newObject)或不能有标签的对象(如 DeploymentRollback 或 PodProxyOptions 对象) 认为是不匹配的。 仅当 Webhook 支持时才能使用对象选择器,因为最终用户可以通过设置标签来跳过准入 webhook。 默认为空的 LabelSelector,匹配所有内容。
webhooks.rules ([]RuleWithOperations)
rules 描述了 Webhook 关心的资源/子资源上有哪些操作。Webhook 关心操作是否匹配任何rules。 但是,为了防止 ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 将集群置于只能完全禁用插件才能恢复的状态, ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 永远不会在处理 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 对象的准入请求被调用。
RuleWithOperations 是操作和资源的元组。建议确保所有元组组合都是有效的。
webhooks.rules.apiGroups ([]string)
原子性: 合并期间会被替换
apiGroups 是资源所属的 API 组列表。'' 是所有组。 如果存在 '',则列表的长度必须为 1。必需。
webhooks.rules.apiVersions ([]string)
原子性: 合并期间会被替换
apiVersions 是资源所属的 API 版本列表。'' 是所有版本。 如果存在 '',则列表的长度必须为 1。必需。
webhooks.rules.operations ([]string)
原子性: 合并期间会被替换
operations 是准入 Webhook 所关心的操作 —— CREATE、UPDATE、DELETE、CONNECT 或用来指代所有已知操作以及将来可能添加的准入操作的
*
。 如果存在 '*',则列表的长度必须为 1。必需。
webhooks.rules.resources ([]string)
原子性: 合并期间会被替换
resources 是此规则适用的资源列表。
- 'pods' 表示 pods,'pods/log' 表示 pods 的日志子资源。'*' 表示所有资源,但不是子资源。
- 'pods/*' 表示 pods 的所有子资源,
- '*/scale' 表示所有 scale 子资源,
- '/' 表示所有资源及其子资源。
如果存在通配符,则验证规则将确保资源不会相互重叠。
根据所指定的对象,可能不允许使用子资源。必需。
webhooks.rules.scope (string)
scope 指定此规则的范围。有效值为 "Cluster", "Namespaced" 和 ""。 "Cluster" 表示只有集群范围的资源才会匹配此规则。 Namespace API 对象是集群范围的。 "Namespaced" 意味着只有命名空间作用域的资源会匹配此规则。 "" 表示没有范围限制。 子资源与其父资源的作用域相同。默认为 "*"。
webhooks.timeoutSeconds (int32)
timeoutSeconds 指定此 Webhook 的超时时间。超时后,Webhook 的调用将被忽略或 API 调用将根据失败策略失败。 超时值必须在 1 到 30 秒之间。默认为 10 秒。
ValidatingWebhookConfigurationList
ValidatingWebhookConfigurationList 是 ValidatingWebhookConfiguration 的列表。
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfigurationList
metadata (ListMeta)
标准的对象元数据,更多信息: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds。
items ([]ValidatingWebhookConfiguration), 必需
ValidatingWebhookConfiguration 列表。
操作
get
读取指定的 ValidatingWebhookConfiguration
HTTP 请求
GET /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}
参数
name (路径参数): string, 必需
ValidatingWebhookConfiguration 的名称。
pretty (查询参数): string
响应
200 (ValidatingWebhookConfiguration): OK
401: Unauthorized
list
列出或观察 ValidatingWebhookConfiguration 类型的对象
HTTP 请求
GET /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations
参数
allowWatchBookmarks (查询参数): boolean
continue (查询参数): string
fieldSelector (查询参数): string
fieldSelector (查询参数): string
limit (查询参数): integer
pretty (查询参数): string
resourceVersion (查询参数): string
resourceVersionMatch (查询参数): string
sendInitialEvents (查询参数): boolean
timeoutSeconds (查询参数): integer
watch (查询参数): boolean
响应
200 (ValidatingWebhookConfigurationList): OK
401: Unauthorized
create
创建一个 ValidatingWebhookConfiguration
HTTP 请求
POST /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations
参数
- body: ValidatingWebhookConfiguration, 必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
pretty (查询参数): string
响应
200 (ValidatingWebhookConfiguration): OK
201 (ValidatingWebhookConfiguration): Created
202 (ValidatingWebhookConfiguration): Accepted
401: Unauthorized
update
替换指定的 ValidatingWebhookConfiguration
HTTP 请求
PUT /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}
参数
name (路径参数): string, 必需
ValidatingWebhookConfiguration 的名称。
- body: ValidatingWebhookConfiguration, 必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
pretty (查询参数): string
响应
200 (ValidatingWebhookConfiguration): OK
201 (ValidatingWebhookConfiguration): Created
401: Unauthorized
patch
部分更新指定的 ValidatingWebhookConfiguration
HTTP 请求
PATCH /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}
参数
name (路径参数): string, 必需
ValidatingWebhookConfiguration 的名称。
- body: Patch, 必需
dryRun (查询参数): string
fieldManager (查询参数): string
fieldValidation (查询参数): string
force (查询参数): boolean
pretty (查询参数): string
响应
200 (ValidatingWebhookConfiguration): OK
201 (ValidatingWebhookConfiguration): Created
401: Unauthorized
delete
删除 ValidatingWebhookConfiguration
HTTP 请求
DELETE /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}
参数
name (路径参数): string, 必需
ValidatingWebhookConfiguration 的名称。
body: DeleteOptions
dryRun (查询参数): string
gracePeriodSeconds (查询参数): integer
pretty (查询参数): string
propagationPolicy (查询参数): string
响应
200 (Status): OK
202 (Status): Accepted
401: Unauthorized
deletecollection
删除 ValidatingWebhookConfiguration 的集合
HTTP 请求
DELETE /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations
参数
- body: DeleteOptions
continue (查询参数): string
dryRun (查询参数): string
fieldSelector (查询参数): string
gracePeriodSeconds (查询参数): integer
labelSelector (查询参数): string
limit (查询参数): integer
pretty (查询参数): string
propagationPolicy (查询参数): string
resourceVersion (查询参数): string
resourceVersionMatch (查询参数): string
sendInitialEvents (查询参数): boolean
timeoutSeconds (查询参数): integer
响应
200 (Status): OK
401: Unauthorized