From 601b104f9bca0e9f0e6137aec47198b5194a2a0b Mon Sep 17 00:00:00 2001 From: "Julian V. Modesto" Date: Thu, 12 Mar 2020 16:02:39 -0400 Subject: [PATCH] Document server-side dry-run is GA in 1.18 (#19549) * Update dry-run docs. * Promote server-side dry-run feature state to stable in 1.18 * Replace --dry-run with --dry-run=server|client|none accordingly * Update server-side dry-run blog post * Update content/en/docs/reference/using-api/api-concepts.md Co-Authored-By: Tim Bannister * Address comments * Add note at end of server-side dry-run blogpost Co-authored-by: Tim Bannister --- .../2019-01-14-apiserver-dry-run-and-kubectl-diff.md | 8 ++++++++ content/en/docs/reference/access-authn-authz/rbac.md | 2 +- content/en/docs/reference/kubectl/overview.md | 2 +- content/en/docs/reference/using-api/api-concepts.md | 6 ++++-- .../docs/tasks/configure-pod-container/configure-gmsa.md | 2 +- content/en/docs/tasks/manage-daemon/update-daemon-set.md | 2 +- .../tasks/manage-kubernetes-objects/imperative-command.md | 6 +++--- 7 files changed, 19 insertions(+), 9 deletions(-) diff --git a/content/en/blog/_posts/2019-01-14-apiserver-dry-run-and-kubectl-diff.md b/content/en/blog/_posts/2019-01-14-apiserver-dry-run-and-kubectl-diff.md index 7853218a0c..87792b00c3 100644 --- a/content/en/blog/_posts/2019-01-14-apiserver-dry-run-and-kubectl-diff.md +++ b/content/en/blog/_posts/2019-01-14-apiserver-dry-run-and-kubectl-diff.md @@ -97,3 +97,11 @@ semantics to fields! It's also going to improve support for CRDs and unions! - Some kubectl apply features are missing from diff and could be useful, like the ability to filter by label, or to display pruned resources. - Eventually, kubectl diff will use server-side apply! + +{{< note >}} + +The flag `kubectl apply --server-dry-run` is deprecated in v1.18. +Use the flag `--dry-run=server` for using server-side dry-run in +`kubectl apply` and other subcommands. + +{{< /note >}} diff --git a/content/en/docs/reference/access-authn-authz/rbac.md b/content/en/docs/reference/access-authn-authz/rbac.md index 852e73fd79..3e5fb351df 100644 --- a/content/en/docs/reference/access-authn-authz/rbac.md +++ b/content/en/docs/reference/access-authn-authz/rbac.md @@ -894,7 +894,7 @@ Examples: * Test applying a manifest file of RBAC objects, displaying changes that would be made: ``` - kubectl auth reconcile -f my-rbac-rules.yaml --dry-run + kubectl auth reconcile -f my-rbac-rules.yaml --dry-run=client ``` * Apply a manifest file of RBAC objects, preserving any extra permissions (in roles) and any extra subjects (in bindings): diff --git a/content/en/docs/reference/kubectl/overview.md b/content/en/docs/reference/kubectl/overview.md index 0b30adcbcc..769476c089 100644 --- a/content/en/docs/reference/kubectl/overview.md +++ b/content/en/docs/reference/kubectl/overview.md @@ -92,7 +92,7 @@ Operation | Syntax | Description `proxy` | `kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]` | Run a proxy to the Kubernetes API server. `replace` | `kubectl replace -f FILENAME` | Replace a resource from a file or stdin. `rolling-update` | kubectl rolling-update OLD_CONTROLLER_NAME ([NEW_CONTROLLER_NAME] --image=NEW_CONTAINER_IMAGE | -f NEW_CONTROLLER_SPEC) [flags] | Perform a rolling update by gradually replacing the specified replication controller and its pods. -`run` | `kubectl run NAME --image=image [--env="key=value"] [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json] [flags]` | Run a specified image on the cluster. +`run` | `kubectl run NAME --image=image [--env="key=value"] [--port=port] [--replicas=replicas] [--dry-run=server|client|none] [--overrides=inline-json] [flags]` | Run a specified image on the cluster. `scale` | kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags] | Update the size of the specified replication controller. `version` | `kubectl version [--client] [flags]` | Display the Kubernetes version running on the client and server. diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index 8c7464d694..4561de6ed5 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -336,12 +336,14 @@ Once the last finalizer is removed, the resource is actually removed from etcd. ## Dry-run -{{< feature-state for_k8s_version="v1.13" state="beta" >}} In version 1.13, the dry-run beta feature is enabled by default. The modifying verbs (`POST`, `PUT`, `PATCH`, and `DELETE`) can accept requests in a dry-run mode. DryRun 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. The system guarantees that dry-run requests will not be persisted in storage or have any other side effects. + {{< feature-state for_k8s_version="v1.18" state="stable" >}} + +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. The system guarantees that dry-run requests will not be persisted in storage or have any other side effects. ### Make a dry-run request -Dry-run is triggered by setting the `dryRun` query parameter. This parameter is a string, working as an enum, and in 1.13 the only accepted values are: +Dry-run is triggered by setting the `dryRun` query parameter. This parameter is a string, working as an enum, and the only accepted values are: * `All`: 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. If the request would trigger an admission controller which would have side effects, the request will be failed rather than risk an unwanted side effect. All built in admission control plugins support dry-run. Additionally, admission webhooks can declare in their [configuration object](/docs/reference/generated/kubernetes-api/v1.13/#webhook-v1beta1-admissionregistration-k8s-io) that they do not have side effects by setting the sideEffects field to "None". If a webhook actually does have side effects, then the sideEffects field should be set to "NoneOnDryRun", and the webhook should also be modified to understand the `DryRun` field in AdmissionReview, and prevent side effects on dry-run requests. * Leave the value empty, which is also the default: Keep the default modifying behavior. diff --git a/content/en/docs/tasks/configure-pod-container/configure-gmsa.md b/content/en/docs/tasks/configure-pod-container/configure-gmsa.md index ff47a7dd8c..847a4bc8b3 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-gmsa.md +++ b/content/en/docs/tasks/configure-pod-container/configure-gmsa.md @@ -42,7 +42,7 @@ Installing the above webhooks and associated objects require the steps below: 1. Create the validating and mutating webhook configurations referring to the deployment. -A [script](https://github.com/kubernetes-sigs/windows-gmsa/blob/master/admission-webhook/deploy/deploy-gmsa-webhook.sh) can be used to deploy and configure the GMSA webhooks and associated objects mentioned above. The script can be run with a ```--dry-run``` option to allow you to review the changes that would be made to your cluster. +A [script](https://github.com/kubernetes-sigs/windows-gmsa/blob/master/admission-webhook/deploy/deploy-gmsa-webhook.sh) can be used to deploy and configure the GMSA webhooks and associated objects mentioned above. The script can be run with a ```--dry-run=server``` option to allow you to review the changes that would be made to your cluster. The [YAML template](https://github.com/kubernetes-sigs/windows-gmsa/blob/master/admission-webhook/deploy/gmsa-webhook.yml.tpl) used by the script may also be used to deploy the webhooks and associated objects manually (with appropriate substitutions for the parameters) diff --git a/content/en/docs/tasks/manage-daemon/update-daemon-set.md b/content/en/docs/tasks/manage-daemon/update-daemon-set.md index ab98f2ea4e..8eec3c1781 100644 --- a/content/en/docs/tasks/manage-daemon/update-daemon-set.md +++ b/content/en/docs/tasks/manage-daemon/update-daemon-set.md @@ -57,7 +57,7 @@ If you haven't created the DaemonSet in the system, check your DaemonSet manifest with the following command instead: ```shell -kubectl apply -f ds.yaml --dry-run -o go-template='{{.spec.updateStrategy.type}}{{"\n"}}' +kubectl apply -f ds.yaml --dry-run=client -o go-template='{{.spec.updateStrategy.type}}{{"\n"}}' ``` The output from both commands should be: diff --git a/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md b/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md index 835bf75faf..6b1357a133 100644 --- a/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md +++ b/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md @@ -139,10 +139,10 @@ creation. This is done by piping the output of the `create` command to the `set` command, and then back to the `create` command. Here's an example: ```sh -kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run | kubectl set selector --local -f - 'environment=qa' -o yaml | kubectl create -f - +kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run=client | kubectl set selector --local -f - 'environment=qa' -o yaml | kubectl create -f - ``` -1. The `kubectl create service -o yaml --dry-run` command creates the configuration for the Service, but prints it to stdout as YAML instead of sending it to the Kubernetes API server. +1. The `kubectl create service -o yaml --dry-run=client` command creates the configuration for the Service, but prints it to stdout as YAML instead of sending it to the Kubernetes API server. 1. The `kubectl set selector --local -f - -o yaml` command reads the configuration from stdin, and writes the updated configuration to stdout as YAML. 1. The `kubectl create -f -` command creates the object using the configuration provided via stdin. @@ -152,7 +152,7 @@ You can use `kubectl create --edit` to make arbitrary changes to an object before it is created. Here's an example: ```sh -kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run > /tmp/srv.yaml +kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run=client > /tmp/srv.yaml kubectl create --edit -f /tmp/srv.yaml ```