From e6a9e38d7b9f70079e22281ee91156bb0bd65f87 Mon Sep 17 00:00:00 2001 From: jennybuckley Date: Tue, 21 Aug 2018 15:16:46 -0700 Subject: [PATCH] Add dry-run to api-concepts --- .../docs/reference/using-api/api-concepts.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index fa86b6fd0cae7..96ca380767ea6 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/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 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. + +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 %}}