Add dry-run to api-concepts

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

@@ -284,6 +284,36 @@ 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
+
+{{< feature-state for_k8s_version="v1.12" state="alpha" >}} In version 1.12, if the DryRun alpha feature is enabled, the modifying verbs (`POST`, `PUT`, `PATCH`, and `DELETE`) can accept requests in a dry run mode. Dry run mode helps to evaluate a request through the typical request stages (admission chain, validation, merge conflicts) up until persisting objects to storage. 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 the possibility for a finer-grained mechanism, where the user can specify which request stages to run, to be introduced later. In 1.12 the only accepted values are:
+
+* `All`: If present, this must be the only element of the array. Every stage runs as normal, except for the final storage stage. 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 array empty, which is also the default: Keep the default modifying behavior.
+
+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 different in dry run mode from when the real request is made, because they are not generated deterministically. It is important not to rely upon the values of these fields set by a dry run request.
+
 {{% /capture %}}