review comments

keps/sig-api-machinery/00xx-admission-webhooks-to-ga.md

@@ -256,23 +256,41 @@ there is any change made by a mutating webhook on the first pass.
   1. Run all in-tree mutating admission plugins
   2. Run all applicable webhook mutating admission plugins that indicate they should be re-called
 
-Mutating plugins that are re-called must be able to successfully admit an object they have already 
+Mutating plugins that are re-called must be idempotent, able to successfully process an object they have already 
 admitted and potentially modified. This will be clearly documented in admission webhook documentation,
 examples, and test guidelines. Mutating admission webhooks *should* already support this (since any 
 change they can make in an object could already exist in the user-provided object), and any webhooks
-that do not are broken for some set of user input, but for compatibility, the re-call behavior will be 
-opt-in for `v1beta1`. In `v1`, mutating webhooks must be safe to recall.
+that do not are broken for some set of user input.
+
+Note that idempotence (whether a webhook can successfully operate on its own output) is distinct from
+the `sideEffects` indicator, which describes whether a webhook can safely be called in `dryRun` mode.
+
+For compatibility, the re-call behavior will be opt-in for `v1beta1`, so `idempotent` will default to `false`.
+
+In `v1`, newly registered mutating webhooks must be safe to re-call, so the `idempotent` field will be dropped.
+`idempotent: false` in a `v1beta1` object will convert to a `deprecated.kubernetes.io/idempotent: "false"` annotation in `v1`.
+Any annotation value other than `"false"` in a `v1` object (including a missing annotation) will convert to `idempotent: true` in `v1beta1`.
+An annotation value of `deprecated.kubernetes.io/idempotent: "false"` will not be allowed when creating `v1` webhooks.
 
 ```golang
 type MutatingWebhookConfiguration struct {
     ...
-    // unsafeToRecall indicates whether these mutating webhooks can be called again 
-    // if the object being admitted is modified by other admission plugins.
-    // If true, the webhooks will not be called again.
-    // If false, the webhooks will be called again, and must be able to admit objects they have already admitted.
-    // Defaults to true in v1beta1. Deprecated and required to be false in v1.
+    // idempotent indicates whether these webhooks can successfully process their own output
+    // as part of a single admission evaluation. All webhooks *should* be idempotent, to be 
+    // able to successfully handle arbitrary user input.
+    //
+    // If false, the webhooks will not be called more than once in a single admission evaluation.
+    //
+    // If true, the webhooks may be called again as part of the admission evaluation (for example,
+    // if the object being admitted is modified by other admission plugins). Note that the number
+    // of re-invocations is not guaranteed to be exactly one. Also note that if the second round of 
+    // evaluations results in modifications to the object being admitted, webhooks are not guaranteed
+    // to be invoked again. To validate an object after all mutations are completed, use a validating
+    // admission webhook.
+    //
+    // Defaults to false in v1beta1 to avoid breaking existing non-idempotent admission webhooks.
     // +optional
-    UnsafeToRecall *bool `json:"unsafeToRecall,omitempty"`
+    Idempotent *bool `json:"idempotent,omitempty"`
 }
 ```