Kyverno マスタークラス: YAML を調理する2つの方法、パッチ方式の違いと実践 🧩

6月 4, 2026

—

こんにちは！Kubernetes 運用の魔法使い、Kyverno マスターシリーズの第8回目です。🧙‍♂️

前回までは、誤ったリクエストを「ブロック」する盾（Validation）について学びましたが、今回はユーザーのリクエストをより完璧に「整える」魔法の杖、mutate ルールについて深く掘り下げていきます。

「すべての Pod にセキュリティラベルをいちいち入れるのは面倒だから自動で入ってほしい」、「開発者がうっかり忘れたサイドカーコンテナを自動で入れてくれないかな？」といった悩みをお持ちでしたら、今日の投稿がその答えとなるでしょう。15分間でリソース変形（Mutation）の真髄を味わいましょう！🚀

🏗️ 1. mutate ルールとは何ですか？

mutate ルールは、Kubernetes リソースが API サーバーに保存される直前に、データを自動的に修正または追加する機能です。

デフォルト値の設定: 必須設定が欠落している場合に自動的に補完します。
セキュリティ強化: 推奨されるセキュリティ設定を強制的に注入します。
自動化: サイドカーの注入、ラベリングなど、反復的な作業を自動化します。

🛠️ 2. リソースを修正する2つの技術: Strategic Merge vs JSONPatch

Kyverno でリソースを変形する方法は大きく分けて2つあります。状況に応じた適切なツールを選択することが、上級者の秘訣です。

① patchStrategicMerge (直感的な方法) 🧩

Kubernetes リソースの構造をそのまま踏襲し、値を上書きまたは追加する方法です。最もよく使われ、非常に読みやすいです。

特徴: YAML 構造をそのままコピーして貼り付けるだけです。リストの場合、特定のキー（例: name）を基準にマージされます。
比喩: レゴブロックの上に新しいブロックを重ねるようなものです。

② patchesJson6902 (精密な方法) 📍

一般的にJSONPatchと呼ばれ、特定のパスを指定して修正、削除、追加のコマンドを実行する方法です。

特徴: 配列の特定のインデックスに値を挿入したり、フィールドを削除したりするなど、非常にきめ細やかな操作が可能です。
比喩: 手術室でメスを使い、特定の部位だけを精密に手術するようなものです。

💻 3. 実践 1: patchStrategicMerge でデフォルトラベルを注入する

すべての Pod が作成される際に、`managed-by: kyverno` というラベルが自動的に付与されるようにしてみましょう。

YAML

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: add-default-labels
spec:
  rules:
  - name: add-labels
    match:
      any:
      - resources:
          kinds:
          - Pod
    mutate:
      patchStrategicMerge:
        metadata:
          labels:
            managed-by: kyverno
            env: "{{request.namespace}}" # 変数も利用可能！

分析: このポリシーは、ユーザーがラベルを指定しなくても、Kyverno がそれを傍受し、`metadata.labels` 内に該当する値を挿入します。

📍 4. 実践 2: JSONPatch でコンテナ設定を精密に修正する

今回はもう少し難しく、最初のコンテナのイメージプルポリシー（imagePullPolicy）を常に `Always` に強制変更してみましょう。

YAML

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: force-image-pull-policy
spec:
  rules:
  - name: set-always
    match:
      any:
      - resources:
          kinds:
          - Pod
    mutate:
      patchesJson6902: |-
        - op: replace
          path: "/spec/containers/0/imagePullPolicy"
          value: "Always"

分析: `op: replace` コマンドを使用して、`/spec/containers/0/` パスにある値を強制的に変更します。もしそのパスに値がない場合、エラーが発生する可能性があるため注意が必要です。

📊 5. 一目でわかる違い


区分	patchStrategicMerge	patchesJson6902 (JSONPatch)

—	—	—
可読性	非常に高い (YAML 構造と同じ)	低い (パスベースの表記法)
複雑度	単純な追加/修正に適している	削除、特定のインデックス修正など、精密な作業に適している
動作原理	マップベースのマージ	RFC 6902 標準コマンドの実行
主な使用箇所	ラベルの追加、アノテーションの注入	コンテナリストの特定要素の修正

—

🚀 6. 運用者のための実務ヒント (ベストプラクティス)

可能な限り Strategic Merge を使用してください: メンテナンスがはるかに簡単です。JSONPatch は、本当に必要な場合（例: 特定のリストの途中に値を挿入する必要がある場合）にのみ使用してください。
mutate 後の validate 連鎖作用: Kyverno はリソースを変形した後、その結果が他のセキュリティポリシー（validate）を通過するかどうかも再確認します。したがって、変形ポリシーはセキュリティを損なわないように設計する必要があります。
既存値の保護: リソースにすでに値がある場合、上書きするかどうかを決定できます。Strategic Merge で `+(field)` 構文を使用すると、既存の値を保持できます。
冪等性 (Idempotency): ポリシーが複数回適用されても結果が同じである必要があります。特にリストにアイテムを追加する際、重複して追加されないかテストが必要です。

🌟 終わりに

今日は、ユーザーのミスを修正し、クラスターの標準を自動的に合わせるmutate ルールについて学びました。

Strategic Merge で簡単かつ迅速にデフォルト値を埋め、
JSONPatch でリソースを精密に加工する方法を習得しました。🛠️

この mutate 機能は、特にPlatform Engineering チームが開発者の体験（DevX）を改善する上で非常に強力なツールとなります。「ダメだ」とブロックするだけの管理者ではなく、「足りない部分は私が補ってあげるよ」と言うスマートな管理者になってみてください！💪

次回は、「サイドカーコンテナの自動注入と共通ラベルの付与」というテーマで、今日学んだ mutate を実務で最大限に活用する例を取り上げます。ご質問があればコメントに残してください！😊