Skip to content

Commit

Permalink
Address comments
Browse files Browse the repository at this point in the history
  • Loading branch information
jennybuckley committed Aug 22, 2018
1 parent e6a9e38 commit fd21062
Showing 1 changed file with 6 additions and 8 deletions.
14 changes: 6 additions & 8 deletions content/en/docs/reference/using-api/api-concepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -287,21 +287,19 @@ 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.

This comment has been minimized.

Sign in to view

Copy link
@kbhawkey

kbhawkey Aug 28, 2018

Contributor
  • Feel free to take out the last sentence as it does not seem to add more than what you have already said in the previous sentences.
  • Nit: would label the feature as alpha or follow the convention used to introduce other alpha features. Including in the sentence gets somewhat lost.
  • Nit: would remove the ... as it does not add anything. If there is a list of stages, perhaps refer to them explicitly.

This comment has been minimized.

Sign in to view

Copy link
@jennybuckley

jennybuckley Aug 28, 2018 •
edited
Loading

I think I addressed 1 and 3 in the next commit, but for 2, what do you mean by "label the feature as alpha follow the convention used to introduce other alpha features"?

This comment has been minimized.

Sign in to view

Copy link
@kbhawkey

kbhawkey Aug 28, 2018

Contributor

There are labels that can be added for associating a version and feature as stable, beta, alpha in the docs. Not sure if there is a formal rule or convention. There is a doc template that can be used to label the version and feature, such as:
{{< feature-state for_k8s_version="v1.12" state="alpha" >}}.

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.

This comment has been minimized.

Sign in to view

Copy link
@kbhawkey

kbhawkey Aug 28, 2018

Contributor

Nit: Why would a user pass in an empty string versus not setting the dryRun parameter? I guess I would need more info about the default modifying behaviour.
Nit: Currently, does the dryRun parameter accept a list of strings? Just questioning what the format is today.

This comment has been minimized.

Sign in to view

Copy link
@jennybuckley

jennybuckley Aug 28, 2018

Good question. Currently the only accepted values are ...?dryRun=All and ...?dryRun= and just making the query without the dryRun flag all together. I think it is important to mention that it is an array of strings though, since we want to preserve backwards compatibility if we decide to accept more values eventually. I don't know why someone would specify ...?dryRun= instead of just leaving the parameter off, but I think that's how all of the other query parameters work as well

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:

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.
The response would look the same as for non dry run request, but the values of some generated fields may differ.


### Generated Values
Expand All @@ -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 %}}

Expand Down

0 comments on commit fd21062

Please sign in to comment.