Add dry-run to api-concepts

content/en/docs/reference/using-api/api-concepts.md

@@ -284,6 +284,37 @@ An encoded Protobuf message with the following IDL:
 
 Clients that receive a response in `application/vnd.kubernetes.protobuf` that does not match the expected prefix should reject the response, as future versions may need to alter the serialization format in an incompatible way and will do so by changing the prefix.
 
+
+## Dry Run
+
+In version 1.12, if the ServerSideDryRun alpha feature is enabled, the modifying verbs (`POST`, `PUT`, `PATCH`, and `DELETE`) can accept requests in a dry-run mode, which allows users to see if the request would have succeeded (admission chain, validation, merge conflicts, ...) and/or what would have happened without having it actually happen. The response body for the request is as close as possible to a non dry-run response.
+
+Dry-run is triggered by setting the `dryRun` parameter. This parameter is an array of strings, working as an array of enums, to allow for future extensibility. Accepted values are:
+* All: Every step runs as normal, except for the final storage step. Admission controllers are run to check that the request is valid, mutating controllers mutate the request, merge is performed on `PATCH`, fields are defaulted, and schema validation occurs. The changes are not persisted to the underlying storage, but the final object which would have been persisted is still returned to the user, along with the normal status code.
+* Leave the value empty, or don't specify the parameter at all to keep the default modifying behavior.
+
+No other values are supported in 1.12, but this allows for a finer-grained mechanism to be introduced later, if necessary.
+
+For example:
+
+        POST /api/v1/namespaces/test/pods?dryRun=All
+        Content-Type: application/json
+        Accept: application/json
+
+The response would look the same as for non dry-run request, but the values of some generated fields may differ.
+
+
+### Generated Values
+
+Some values of an object are typically generated before the object is persisted:
+
+* generateName can be used to assign a unique random name to the object,
+* creationTimestamp/deletionTimestamp records the time of creation/deletion,
+* UID uniquely identifies the object and is randomly generated (non-deterministic),
+* resourceVersion tracks the persisted version of the object.
+
+The values of these fields will likely be set differently in a dry-run and non-dry-run creation, because they are not genereated deterministically. It is important not to rely upon the values of these fields being set correctly by a dry-run request.
+
 {{% /capture %}}