MutatingWebhookConfiguration

MutatingWebhookConfiguration 描述了一個可變的准入 webhook 的配置，該 webhook 可以接受或拒絕請求，並可能更改物件。

apiVersion: admissionregistration.k8s.io/v1

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

MutatingWebhookConfiguration

MutatingWebhookConfiguration 描述了一個可變的准入 webhook 的配置，該 webhook 可以接受或拒絕請求，並可能更改物件。

  • apiVersion: admissionregistration.k8s.io/v1

  • kind: MutatingWebhookConfiguration

  • metadata (ObjectMeta)

    標準物件元資料；更多資訊： https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata。

  • webhooks ([]MutatingWebhook)

    補丁策略：在鍵 name 上合併

    對映：合併時將保留鍵名上的唯一值

    Webhooks 是 webhook 及其受影響的資源和操作的列表。

    MutatingWebhook 描述了一個准入 webhook 以及它適用的資源和操作。

    • webhooks.admissionReviewVersions ([]string), required

      原子性：在合併期間將被替換

      AdmissionReviewVersions 是 webhook 期望的 AdmissionReview 版本的有序列表。API 伺服器將嘗試使用列表中它支援的第一個版本。如果 API 伺服器不支援此列表中指定的任何版本，則此物件的驗證將失敗。如果持久化的 webhook 配置指定了允許的版本，並且不包含 API 伺服器已知的任何版本，則對 webhook 的呼叫將失敗，並受失敗策略的影響。

    • webhooks.clientConfig (WebhookClientConfig), required

      ClientConfig 定義瞭如何與 hook 通訊。必需

      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), required

          name 是服務的名稱。必需

        • webhooks.clientConfig.service.namespace (string), required

          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 中，host 可能透過外部 DNS 解析（例如，kube-apiserver 無法解析叢集內 DNS，因為這將是一個層級違規）。host 也可能是一個 IP 地址。

        請注意，使用 localhost 或 127.0.0.1 作為 host 是有風險的，除非您非常小心地在執行可能需要呼叫此 webhook 的所有 apiserver 的主機上執行此 webhook。此類安裝可能不具有可移植性，即在新的叢集中不容易啟用。

        方案必須是“https”；URL 必須以“https://”開頭。

        path 是可選的，如果存在，可以是 URL 中允許的任何字串。您可以使用 path 向 Webhook 傳遞任意字串，例如叢集識別符號。

        不允許嘗試使用使用者或基本身份驗證，例如 "user:password@"。片段 ("#...") 和查詢引數 ("?...") 也不允許。

    • webhooks.name (string), required

      准入 webhook 的名稱。名稱應完全限定，例如，imagepolicy.kubernetes.io，其中 "imagepolicy" 是 webhook 的名稱，kubernetes.io 是組織的名稱。必需。

    • webhooks.sideEffects (string), required

      SideEffects 說明此 webhook 是否具有副作用。可接受的值為：None、NoneOnDryRun（透過 v1beta1 建立的 webhook 也可以指定 Some 或 Unknown）。具有副作用的 Webhook 必須實現一個協調系統，因為一個請求可能會被准入鏈中的後續步驟拒絕，因此需要撤銷副作用。對於副作用等於 Unknown 或 Some 的 webhook，帶有 dryRun 屬性的請求將被自動拒絕。

    • webhooks.failurePolicy (string)

      FailurePolicy 定義瞭如何處理來自准入端點的無法識別的錯誤 - 允許值為 Ignore 或 Fail。預設為 Fail。

    • webhooks.matchConditions ([]MatchCondition)

      補丁策略：在鍵 name 上合併

      對映：合併時將保留鍵名上的唯一值

      MatchConditions 是傳送請求到此 webhook 必須滿足的條件列表。匹配條件過濾已由 rules、namespaceSelector 和 objectSelector 匹配的請求。一個空的 matchConditions 列表匹配所有請求。最多允許 64 個匹配條件。

      確切的匹配邏輯是（按順序）

      1. 如果 *任何* matchCondition 求值為 FALSE，則跳過 webhook。
      2. 如果 *所有* matchConditions 都求值為 TRUE，則呼叫 webhook。
      3. 如果任何 matchCondition 評估為錯誤（但沒有一個為 FALSE）
        • 如果 failurePolicy=Fail，則拒絕請求
        • 如果 failurePolicy=Ignore，則忽略錯誤並跳過 webhook

      MatchCondition 表示 Webhook 必須滿足才能傳送請求的條件。

      • webhooks.matchConditions.expression (string), required

        Expression 表示將由 CEL 評估的表示式。必須評估為布林值。CEL 表示式可以訪問 AdmissionRequest 和 Authorizer 的內容，這些內容組織成 CEL 變數

        'object' - 來自入站請求的物件。對於 DELETE 請求，值為 null。'oldObject' - 現有物件。對於 CREATE 請求，值為 null。'request' - 准入請求的屬性(/pkg/apis/admission/types.go#AdmissionRequest)。'authorizer' - CEL 授權器。可用於執行請求的principal（使用者或服務帳戶）的授權檢查。請參閱 https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz 'authorizer.requestResource' - 一個 CEL ResourceCheck，由 'authorizer' 構建並配置了請求資源。有關 CEL 的文件：https://kubernetes.club.tw/docs/reference/using-api/cel/

        必需。

      • webhooks.matchConditions.name (string), required

        Name 是此匹配條件的識別符號，用於 MatchConditions 的戰略合併，以及提供日誌記錄識別符號。一個好的名稱應該能夠描述相關的表示式。名稱必須是包含字母數字字元、'-'、'_' 或 '.' 的限定名稱，並且必須以字母數字字元開頭和結尾（例如，'MyName'、'my.name' 或 '123-abc'，用於驗證的正則表示式是 '([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]'），並帶有可選的 DNS 子域字首和 '/'（例如，'example.com/MyName'）。

        必需。

    • webhooks.matchPolicy (string)

      matchPolicy 定義瞭如何使用 "rules" 列表來匹配入站請求。允許值為 "Exact" 或 "Equivalent"。

      • Exact: 僅當請求完全匹配指定的規則時才匹配。例如，如果 deployments 可以透過 apps/v1、apps/v1beta1 和 extensions/v1beta1 進行修改，但 "rules" 只包含 apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]，那麼對 apps/v1beta1 或 extensions/v1beta1 的請求將不會發送到 webhook。

      • Equivalent: 如果請求修改了規則中列出的資源，即使是透過另一個 API 組或版本，也會匹配。例如，如果 deployments 可以透過 apps/v1、apps/v1beta1 和 extensions/v1beta1 進行修改，並且 "rules" 只包含 apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]，那麼對 apps/v1beta1 或 extensions/v1beta1 的請求將被轉換為 apps/v1 併發送到 webhook。

      預設為 "Equivalent"

    • webhooks.namespaceSelector (LabelSelector)

      NamespaceSelector 根據物件的名稱空間是否匹配選擇器來決定是否在物件上執行 webhook。如果物件本身是名稱空間，則匹配在 object.metadata.labels 上執行。如果物件是另一個叢集範圍的資源，它永遠不會跳過 webhook。

      例如，要在任何名稱空間不與 "runlevel" 的 "0" 或 "1" 關聯的物件上執行 webhook；您將設定選擇器如下："namespaceSelector": { "matchExpressions": [ { "key": "runlevel", "operator": "NotIn", "values": [ "0", "1" ] } ] }

      如果相反，您只想在任何與 "environment" 的 "prod" 或 "staging" 關聯的名稱空間中的物件上執行 webhook；您將設定選擇器如下："namespaceSelector": { "matchExpressions": [ { "key": "environment", "operator": "In", "values": [ "prod", "staging" ] } ] }

      有關標籤選擇器的更多示例，請參閱 https://kubernetes.club.tw/docs/concepts/overview/working-with-objects/labels/。

      預設為空 LabelSelector，它匹配所有內容。

    • webhooks.objectSelector (LabelSelector)

      ObjectSelector 根據物件是否具有匹配的標籤來決定是否執行 webhook。objectSelector 會針對將傳送到 webhook 的 oldObject 和 newObject 進行評估，如果任一物件匹配選擇器，則認為匹配。空物件（建立時的 oldObject，或刪除時的 newObject）或無法具有標籤的物件（如 DeploymentRollback 或 PodProxyOptions 物件）不被視為匹配。僅當 webhook 是選擇加入的（opt-in）時才使用物件選擇器，因為終端使用者可以透過設定標籤來跳過准入 webhook。預設為空的 LabelSelector，它匹配所有內容。

    • webhooks.reinvocationPolicy (string)

      reinvocationPolicy 指示此 webhook 在單個准入評估中是否應被呼叫多次。允許值為 "Never" 和 "IfNeeded"。

      Never: 在單個准入評估中，webhook 不會被呼叫超過一次。

      IfNeeded: 如果被准入的物件在初始 webhook 呼叫後被其他准入外掛修改，則 webhook 在本次准入評估中至少會再呼叫一次。指定此選項的 webhook 必須是冪等的，能夠處理它們之前已准入的物件。注意：* 其他呼叫的次數不保證正好為一次。* 如果額外的呼叫導致物件進一步修改，則不保證會再次呼叫 webhook。* 使用此選項的 webhook 可能會被重新排序以最小化額外呼叫的次數。* 在所有修改都保證完成後驗證一個物件，請改用驗證准入 webhook。

      預設為 "Never"。

    • webhooks.rules ([]RuleWithOperations)

      原子性：在合併期間將被替換

      Rules 描述了 webhook 關注的對哪些資源/子資源的操作。如果操作匹配 *任何* Rule，則 webhook 關注該操作。但是，為了防止 ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks 將叢集置於無法恢復的狀態（除非完全停用外掛），永遠不會在對 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 物件的准入請求上呼叫 ValidatingAdmissionWebhooks 和 MutatingAdmissionWebhooks。

      RuleWithOperations 是 Operations 和 Resources 的元組。建議確保所有元組的展開都是有效的。

      • webhooks.rules.apiGroups ([]string)

        原子性：在合併期間將被替換

        APIGroups 是資源所屬的 API 組。'' 表示所有組。如果存在 ''，則切片的長度必須為 1。必需。

      • webhooks.rules.apiVersions ([]string)

        原子性：在合併期間將被替換

        APIVersions 是資源所屬的 API 版本。'' 表示所有版本。如果存在 ''，則切片的長度必須為 1。必需。

      • webhooks.rules.operations ([]string)

        原子性：在合併期間將被替換

        Operations 是准入鉤子關心的操作 - CREATE、UPDATE、DELETE、CONNECT 或 * 表示所有這些操作以及將來新增的任何准入操作。如果存在 '*'，則切片的長度必須為 1。必需。

      • webhooks.rules.resources ([]string)

        原子性：在合併期間將被替換

        Resources 是此規則適用的資源列表。

        例如：'pods' 表示 pods。'pods/log' 表示 pods 的 log 子資源。'*' 表示所有資源，但不包括子資源。'pods/*' 表示 pods 的所有子資源。'*/*' 表示所有資源及其子資源。

        如果存在萬用字元，則驗證規則將確保資源彼此不重疊。

        根據包圍物件，可能不允許子資源。必需。

      • webhooks.rules.scope (string)

        scope 指定此規則的範圍。有效值為 "Cluster"、"Namespaced" 和 "*"。"Cluster" 意味著只有叢集範圍的資源將匹配此規則。Namespace API 物件是叢集範圍的。"Namespaced" 意味著只有名稱空間範圍的資源將匹配此規則。"*" 意味著沒有範圍限制。子資源匹配其父資源的範圍。預設為 "*"。

    • webhooks.timeoutSeconds (int32)

      TimeoutSeconds 指定此 webhook 的超時時間。超時後，將根據失敗策略忽略 webhook 呼叫或 API 呼叫將失敗。超時值必須在 1 到 30 秒之間。預設為 10 秒。

MutatingWebhookConfigurationList

MutatingWebhookConfigurationList 是 MutatingWebhookConfiguration 的列表。

操作

get 讀取指定的 MutatingWebhookConfiguration

HTTP 請求

GET /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

引數

  • name (在路徑中): string，必填

    MutatingWebhookConfiguration 的名稱

  • pretty (在查詢中): string

    pretty

響應

200 (MutatingWebhookConfiguration): OK

401: 未授權

list 列出或監視 MutatingWebhookConfiguration 型別的物件

HTTP 請求

GET /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

引數

響應

200 (MutatingWebhookConfigurationList): OK

401: 未授權

create 建立一個 MutatingWebhookConfiguration

HTTP 請求

POST /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

引數

響應

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

202 (MutatingWebhookConfiguration): Accepted

401: 未授權

update 替換指定的 MutatingWebhookConfiguration

HTTP 請求

PUT /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

引數

響應

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

401: 未授權

patch 部分更新指定的 MutatingWebhookConfiguration

HTTP 請求

PATCH /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

引數

  • name (在路徑中): string，必填

    MutatingWebhookConfiguration 的名稱

  • body: Patch，必需

  • dryRun (在查詢中): string

    dryRun

  • fieldManager (在查詢中): string

    fieldManager

  • fieldValidation (在查詢中): string

    fieldValidation

  • force (在查詢中): boolean

    force

  • pretty (在查詢中): string

    pretty

響應

200 (MutatingWebhookConfiguration): OK

201 (MutatingWebhookConfiguration): Created

401: 未授權

delete 刪除一個 MutatingWebhookConfiguration

HTTP 請求

DELETE /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}

引數

響應

200 (Status): OK

202 (Status): 已接受

401: 未授權

deletecollection 刪除 MutatingWebhookConfiguration 的集合

HTTP 請求

DELETE /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations

引數

響應

200 (Status): OK

401: 未授權

本頁面是自動生成的。

如果你打算報告此頁面存在的問題，請在問題描述中提及此頁面是自動生成的。修復可能需要在 Kubernetes 專案的其他地方進行。

上次修改時間：2025 年 4 月 9 日太平洋標準時間下午 6:36：更新 v1.32 的 API 參考文件 (a3b579d035)