From 529adc5e47dae7710efbfc151c54800cb3d636e9 Mon Sep 17 00:00:00 2001
From: Mariam Fahmy <mariam.fahmy@nirmata.com>
Date: Mon, 14 Oct 2024 14:47:44 +0300
Subject: [PATCH] docs: add warning for the mutateExistingOnPolicyUpdate
 deprecated field

Signed-off-by: Mariam Fahmy <mariam.fahmy@nirmata.com>
---
 content/en/docs/writing-policies/mutate.md          | 10 +++++-----
 content/en/docs/writing-policies/policy-settings.md |  2 +-
 content/en/docs/writing-policies/variables.md       |  3 +--
 3 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/content/en/docs/writing-policies/mutate.md b/content/en/docs/writing-policies/mutate.md
index d242745d4..bfd9e7403 100644
--- a/content/en/docs/writing-policies/mutate.md
+++ b/content/en/docs/writing-policies/mutate.md
@@ -470,7 +470,6 @@ kind: ClusterPolicy
 metadata:
   name: mutate-existing-secret
 spec:
-  mutateExistingOnPolicyUpdate: true
   rules:
     - name: mutate-secret-on-configmap-event
       match:
@@ -483,6 +482,7 @@ spec:
               namespaces:
                 - staging
       mutate:
+        mutateExistingOnPolicyUpdate: true
         # ...
         targets:
           - apiVersion: v1
@@ -508,7 +508,6 @@ kind: ClusterPolicy
 metadata:
   name: refresh-env-var-in-pods
 spec:
-  mutateExistingOnPolicyUpdate: false
   rules:
   - name: refresh-from-secret-env
     match:
@@ -522,6 +521,7 @@ spec:
           operations:
           - UPDATE
     mutate:
+      mutateExistingOnPolicyUpdate: false
       targets:
         - apiVersion: apps/v1
           kind: Deployment
@@ -622,7 +622,6 @@ kind: ClusterPolicy
 metadata:
   name: sync-cms
 spec:
-  mutateExistingOnPolicyUpdate: false
   rules:
   - name: concat-cm
     match:
@@ -635,6 +634,7 @@ spec:
           namespaces:
           - foo
     mutate:
+      mutateExistingOnPolicyUpdate: false
       targets:
         - apiVersion: v1
           kind: ConfigMap
@@ -660,7 +660,6 @@ kind: ClusterPolicy
 metadata:
   name: sync-cms
 spec:
-  mutateExistingOnPolicyUpdate: false
   rules:
   - name: concat-cm
     match:
@@ -673,6 +672,7 @@ spec:
           namespaces:
           - foo
     mutate:
+      mutateExistingOnPolicyUpdate: false
       targets:
         - apiVersion: v1
           kind: ConfigMap
@@ -918,7 +918,6 @@ kind: ClusterPolicy
 metadata:
   name: demo-cluster-policy
 spec:
-  mutateExistingOnPolicyUpdate: false
   rules:
   - name: demo-generate
     match:
@@ -951,6 +950,7 @@ spec:
               matchLabels:
                 custom/related-namespace: "?*"
     mutate:
+      mutateExistingOnPolicyUpdate: false
       targets:
         - apiVersion: v1
           kind: Namespace
diff --git a/content/en/docs/writing-policies/policy-settings.md b/content/en/docs/writing-policies/policy-settings.md
index a42f936b3..0897b33e1 100644
--- a/content/en/docs/writing-policies/policy-settings.md
+++ b/content/en/docs/writing-policies/policy-settings.md
@@ -17,7 +17,7 @@ A [policy](../kyverno-policies) contains one or more rules, and the following co
 
 * **generateExisting**: applicable to generate rules only. Controls whether Kyverno should evaluate the policy the moment it is created.
 
-* **mutateExistingOnPolicyUpdate**: applicable to mutate rules which define targets. Controls whether Kyverno should evaluate the policy when it is updated.
+* **mutateExistingOnPolicyUpdate**: applicable to mutate rules which define targets. Controls whether Kyverno should evaluate the policy when it is updated. This field is deprecated as of 1.13. Scheduled to be removed in a future version. Use `mutateExistingOnPolicyUpdate` under the mutate rule instead.
 
 * **schemaValidation**: controls whether policy validation checks are applied. Defaults to "true". Kyverno will attempt to validate the schema of a policy and fail if it cannot determine it satisfies the OpenAPI schema definition for that resource. Can occur on either validate or mutate policies. Set to "false" to skip schema validation. This field is deprecated as of 1.11 and currently has no effect. Scheduled to be removed in a future version.
 
diff --git a/content/en/docs/writing-policies/variables.md b/content/en/docs/writing-policies/variables.md
index 7c9199ee0..4b1ab639e 100644
--- a/content/en/docs/writing-policies/variables.md
+++ b/content/en/docs/writing-policies/variables.md
@@ -504,9 +504,7 @@ kind: ClusterPolicy
 metadata:
   name: vault-auth-backend
 spec:
-  validationFailureAction: Audit
   background: true
-  mutateExistingOnPolicyUpdate: true
   rules:
   - name: vault-injector-config-blue-to-green-auth-backend
     context:
@@ -523,6 +521,7 @@ spec:
           namespaces:
           - corp-tech-ap-team-ping-ep
     mutate:
+      mutateExistingOnPolicyUpdate: true
       patchStrategicMerge:
         data:
           config: '{{- hcl }}'