MutatingWebhookConfiguration

MutatingWebhookConfiguration описывает конфигурацию вебхука допуска, который принимает или отклоняет объект и может изменять его.

apiVersion: admissionregistration.k8s.io/v1

import "k8s.io/api/admissionregistration/v1"

MutatingWebhookConfiguration

Поле	Описание
`apiVersion` string	APIVersion определяет версионированную схему этого представления объекта. Серверы должны преобразовывать распознанные схемы в последнее внутреннее значение и могут отклонять нераспознанные значения. Дополнительная информация: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`kind` string	Kind — это строковое значение, представляющее ресурс REST, который представляет этот объект. Серверы могут определить его по конечной точке, на которую клиент отправляет запросы. Не может быть обновлено. В CamelCase. Дополнительная информация: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ObjectMeta	metadata — это стандартные метаданные объекта. Дополнительная информация: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata.
`webhooks` MutatingWebhook array patch strategy: merge on key `name`	webhooks — это список вебхуков, а также затрагиваемых ресурсов и операций.

MutatingWebhookConfigurationList

MutatingWebhookConfigurationList — это список MutatingWebhookConfiguration.

Поле	Описание
`apiVersion` string	APIVersion определяет версионированную схему этого представления объекта. Серверы должны преобразовывать распознанные схемы в последнее внутреннее значение и могут отклонять нераспознанные значения. Дополнительная информация: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`items` * MutatingWebhookConfiguration array	Список MutatingWebhookConfiguration.
`kind` string	Kind — это строковое значение, представляющее ресурс REST, который представляет этот объект. Серверы могут определить его по конечной точке, на которую клиент отправляет запросы. Не может быть обновлено. В CamelCase. Дополнительная информация: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ListMeta	metadata — это стандартные метаданные списка. Дополнительная информация: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

MutatingWebhook

MutatingWebhook описывает вебхук допуска, а также ресурсы и операции, к которым он применяется.

Поле	Описание
`admissionReviewVersions` * string array	admissionReviewVersions — упорядоченный список предпочтительных версий `AdmissionReview`, которые ожидает вебхук. Сервер API попытается использовать первую поддерживаемую им версию из списка. Если ни одна из указанных в списке версий не поддерживается сервером API, проверка этого объекта завершится ошибкой. Если в сохраненной конфигурации вебхука указаны разрешенные версии, но среди них нет ни одной известной серверу API, вызовы вебхука завершатся ошибкой, и к ним будет применена политика обработки ошибок.
`clientConfig` * WebhookClientConfig	clientConfig определяет способ взаимодействия с вебхуком. Обязательное поле
`failurePolicy` string	failurePolicy определяет, как обрабатываются нераспознанные ошибки конечной точки допуска. Допустимые значения — Ignore или Fail. По умолчанию — Fail. Возможные значения перечисления: - `"Fail"` означает, что ошибка при вызове вебхука приводит к сбою допуска. - `"Ignore"` означает, что ошибка при вызове вебхука игнорируется.
`matchConditions` MatchCondition array patch strategy: merge on key `name`	matchConditions — это список условий, которые должны быть выполнены, чтобы запрос был отправлен этому вебхуку. Условия сопоставления фильтруют запросы, уже сопоставленные с помощью rules, namespaceSelector и objectSelector. Пустой список matchConditions соответствует всем запросам. Допускается не более 64 условий сопоставления. Точная логика сопоставления (по порядку): 1. Если любое условие matchCondition принимает значение FALSE, вызов вебхука пропускается. 2. Если все условия matchCondition принимают значение TRUE, вебхук вызывается. 3. Если какое-либо условие matchCondition приводит к ошибке (но ни одно не принимает значение FALSE): - Если failurePolicy=Fail, запрос отклоняется. - Если failurePolicy=Ignore, ошибка игнорируется, а вызов вебхука пропускается.
`matchPolicy` string	matchPolicy определяет, как список "rules" используется для сопоставления входящих запросов. Допустимые значения — "Exact" или "Equivalent". - Exact: запрос сопоставляется, только если он в точности соответствует указанному правилу. Например, если развертывания можно изменять через apps/v1, apps/v1beta1 и extensions/v1beta1, но в "rules" указано только `apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]`, запрос к apps/v1beta1 или extensions/v1beta1 не будет отправлен вебхуку. - Equivalent: запрос сопоставляется, если он изменяет ресурс, указанный в rules, даже через другую группу API или версию. Например, если развертывания можно изменять через apps/v1, apps/v1beta1 и extensions/v1beta1, а в "rules" указано только `apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]`, запрос к apps/v1beta1 или extensions/v1beta1 будет преобразован в apps/v1 и отправлен вебхуку. По умолчанию — "Equivalent". Возможные значения перечисления: - `"Equivalent"` означает, что запросы следует отправлять вебхуку, если они изменяют ресурс, указанный в rules, через другую группу API или версию. - `"Exact"` означает, что запросы следует отправлять вебхуку, только если они в точности соответствуют заданному правилу.
`name` * string	name — имя вебхука допуска. Имя должно быть полным, например imagepolicy.kubernetes.io, где "imagepolicy" — имя вебхука, а kubernetes.io — имя организации. Обязательное поле.
`namespaceSelector` LabelSelector	namespaceSelector определяет, следует ли запускать вебхук для объекта, исходя из того, соответствует ли пространство имен этого объекта селектору. Если сам объект является пространством имен, сопоставление выполняется по меткам object.metadata.labels. Если объект является другим ресурсом уровня кластера, вебхук никогда не пропускается. Например, чтобы вебхук запускался для любых объектов, чье пространство имен не связано с "runlevel" со значением "0" или "1", задайте селектор следующим образом: "namespaceSelector": { "matchExpressions": [ { "key": "runlevel", "operator": "NotIn", "values": [ "0", "1" ] } ] } Если вместо этого вы хотите, чтобы вебхук запускался только для объектов, чье пространство имен связано с "environment" со значением "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 проверяется для oldObject и newObject, которые будут отправлены вебхуку; считается, что условие выполнено, если селектору соответствует хотя бы один из объектов. Объект со значением null (oldObject при создании или newObject при удалении) либо объект, у которого не может быть меток (например, DeploymentRollback или объект PodProxyOptions), не считается соответствующим селектору. Используйте селектор объектов только в том случае, если вызов вебхука выполняется по выбору пользователя, поскольку конечные пользователи могут пропустить вебхук допуска, установив метки. По умолчанию используется пустой LabelSelector, которому соответствует всё.
`reinvocationPolicy` string	reinvocationPolicy указывает, следует ли вызывать этот вебхук несколько раз в рамках одной проверки допуска. Допустимые значения — "Never" и "IfNeeded". Never: вебхук будет вызван не более одного раза в рамках одной проверки допуска. IfNeeded: вебхук будет вызван как минимум еще один раз в рамках проверки допуска, если после первоначального вызова вебхука другие плагины допуска изменят проверяемый объект. Вебхуки, для которых указан этот параметр, должны быть идемпотентными и уметь обрабатывать объекты, которые они уже допускали. Примечание: * количество дополнительных вызовов не обязательно будет равно одному. * если дополнительные вызовы приведут к дальнейшим изменениям объекта, повторный вызов вебхуков не гарантируется. * вебхуки, использующие этот параметр, могут быть переупорядочены, чтобы свести к минимуму число дополнительных вызовов. * чтобы проверить объект после завершения всех изменений, используйте вместо этого проверяющий вебхук допуска. По умолчанию — "Never". Возможные значения перечисления: - `"IfNeeded"` означает, что вебхук изменения может быть вызван как минимум еще один раз в рамках проверки допуска, если после первоначального вызова другие плагины допуска изменят проверяемый объект. - `"Never"` означает, что вебхук изменения нельзя вызывать более одного раза в рамках одной проверки допуска.
`rules` RuleWithOperations array	rules описывает операции с ресурсами и подресурсами, которые учитывает вебхук. Вебхук учитывает операцию, если она соответствует _любому_ правилу. Однако, чтобы ValidatingAdmissionWebhooks и MutatingAdmissionWebhooks не переводили кластер в состояние, из которого нельзя восстановиться без полного отключения плагина, ValidatingAdmissionWebhooks и MutatingAdmissionWebhooks никогда не вызываются для запросов допуска к объектам ValidatingWebhookConfiguration и MutatingWebhookConfiguration.
`sideEffects` * string	sideEffects указывает, имеет ли этот вебхук побочные эффекты. Допустимые значения: None, NoneOnDryRun (вебхуки, созданные с помощью v1beta1, также могут указывать Some или Unknown). Вебхуки с побочными эффектами ДОЛЖНЫ реализовывать систему согласования, поскольку запрос может быть отклонен на последующем этапе цепочки допуска, и поэтому побочные эффекты необходимо будет отменить. Запросы с атрибутом dryRun будут автоматически отклонены, если они соответствуют вебхуку с sideEffects == Unknown или Some. Возможные значения перечисления: - `"None"` означает, что вызов вебхука не будет иметь побочных эффектов. - `"NoneOnDryRun"` означает, что вызов вебхука может иметь побочные эффекты, но если проверяемый запрос имеет атрибут dry-run, побочные эффекты будут подавлены. - `"Some"` означает, что вызов вебхука может иметь побочные эффекты. Если запрос с атрибутом dry-run должен привести к вызову этого вебхука, запрос вместо этого завершится ошибкой. - `"Unknown"` означает, что сведения о побочных эффектах вызова вебхука отсутствуют. Если запрос с атрибутом dry-run должен привести к вызову этого вебхука, запрос вместо этого завершится ошибкой.
`timeoutSeconds` integer	timeoutSeconds задает время ожидания для этого вебхука. По истечении этого времени вызов вебхука будет проигнорирован или вызов API завершится ошибкой в зависимости от политики обработки ошибок. Значение тайм-аута должно быть от 1 до 30 секунд. По умолчанию — 10 секунд.

© 2026 The Kubernetes Authors | Documentation Distributed under CC BY 4.0
Copyright © 2026 The Linux Foundation ®. All rights reserved.
https://kubernetes.io/docs/reference/kubernetes-api/admissionregistration/mutating-webhook-configuration-v1/