From fd21062b894c63057136e46914c14da056cc1453 Mon Sep 17 00:00:00 2001 From: jennybuckley Date: Wed, 22 Aug 2018 11:24:06 -0700 Subject: [PATCH] Address comments --- .../en/docs/reference/using-api/api-concepts.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index 96ca380767ea6..8f2bf3dcab574 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -287,13 +287,11 @@ Clients that receive a response in `application/vnd.kubernetes.protobuf` that do ## Dry Run -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, 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. +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. Making a request in dry run mode 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 mode helps to evaluate a request through the typical request stages (admission chain, validation, merge conflicts) up until persisting objects to storage. -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. +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: @@ -301,7 +299,7 @@ For example: 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. +The response would look the same as for non dry run request, but the values of some generated fields may differ. ### Generated Values @@ -313,7 +311,7 @@ Some values of an object are typically generated before the object is persisted: * 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. +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 %}}