PR for diff docs

content/en/docs/concepts/overview/object-management-kubectl/declarative-config.md

@@ -9,7 +9,8 @@ Kubernetes objects can be created, updated, and deleted by storing multiple
 object configuration files in a directory and using `kubectl apply` to
 recursively create and update those objects as needed. This method
 retains writes made to live objects without merging the changes
-back into the object configuration files.
+back into the object configuration files. `kubectl diff` also gives you a
+preview of what changes `apply` will make.
 {{% /capture %}}
 
 {{% capture body %}}
@@ -67,6 +68,14 @@ Here's an example of an object configuration file:
 
 {{< codenew file="application/simple_deployment.yaml" >}}
 
+Run `kubectl diff` to print the object that will be created:
+```shell
+kubectl diff -f https://k8s.io/examples/application/simple_deployment.yaml
+```
+{{< note >}}
+**Note:** `diff` uses [server-side dry-run](/docs/reference/using-api/api-concepts/#dry-run), which needs to be enabled on `kube-apiserver`.
+{{< /note >}}
+
 Create the object using `kubectl apply`:
 
 ```shell
@@ -130,6 +139,7 @@ if those objects already exist. This approach accomplishes the following:
 2. Clears fields removed from the configuration file in the live configuration.
 
 ```shell
+kubectl diff -f <directory>/
 kubectl apply -f <directory>/
 ```
 
@@ -262,6 +272,7 @@ Update the `simple_deployment.yaml` configuration file to change the image from
 Apply the changes made to the configuration file:
 
 ```shell
+kubectl diff -f https://k8s.io/examples/application/update_deployment.yaml
 kubectl apply -f https://k8s.io/examples/application/update_deployment.yaml
 ```
 
@@ -976,5 +987,3 @@ template:
 - [Kubectl Command Reference](/docs/reference/generated/kubectl/kubectl/)
 - [Kubernetes API Reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
 {{% /capture %}}
-
-

content/en/docs/concepts/overview/object-management-kubectl/overview.md

@@ -144,16 +144,19 @@ API operation to replace the entire object configuration.
 
 ### Examples
 
-Process all object configuration files in the `configs` directory, and
-create or patch the live objects:
+Process all object configuration files in the `configs` directory, and create or
+patch the live objects. You can first `diff` to see what changes are going to be
+made, and then apply:
 
 ```sh
+kubectl diff -f configs/
 kubectl apply -f configs/
 ```
 
 Recursively process directories:
 
 ```sh
+kubectl diff -R -f configs/
 kubectl apply -R -f configs/
 ```
 
@@ -181,5 +184,3 @@ Disadvantages compared to imperative object configuration:
 {{< comment >}}
 {{< /comment >}}
 {{% /capture %}}
-
-

content/en/docs/reference/kubectl/overview.md

@@ -30,17 +30,17 @@ where `command`, `TYPE`, `NAME`, and `flags` are:
 * `NAME`: Specifies the name of the resource. Names are case-sensitive. If the name is omitted, details for all resources are displayed, for example `$ kubectl get pods`.
 
    When performing an operation on multiple resources, you can specify each resource by type and name or specify one or more files:
-   
+
    * To specify resources by type and name:
-   
+
       * To group resources if they are all the same type:  `TYPE1 name1 name2 name<#>`.<br/>
       Example: `$ kubectl get pod example-pod1 example-pod2`
-        
+
       * To specify multiple resource types individually:  `TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>`.<br/>
       Example: `$ kubectl get pod/example-pod1 replicationcontroller/example-rc1`
-        
+
    * To specify resources with one or more files:  `-f file1 -f file2 -f file<#>`
-   
+
       * [Use YAML rather than JSON](/docs/concepts/configuration/overview/#general-config-tips) since YAML tends to be more user-friendly, especially for configuration files.<br/>
      Example: `$ kubectl get pod -f ./pod.yaml`
 
@@ -65,6 +65,7 @@ Operation       | Syntax    |       Description
 `create`        | `kubectl create -f FILENAME [flags]` | Create one or more resources from a file or stdin.
 `delete`        | `kubectl delete (-f FILENAME \| TYPE [NAME \| /NAME \| -l label \| --all]) [flags]` | Delete resources either from a file, stdin, or specifying label selectors, names, resource selectors, or resources.
 `describe`    | `kubectl describe (-f FILENAME \| TYPE [NAME_PREFIX \| /NAME \| -l label]) [flags]` | Display the detailed state of one or more resources.
+`diff`        | `kubectl diff -f FILENAME [flags]`| Diff file or stdin against live configuration (**BETA**)
 `edit`        | `kubectl edit (-f FILENAME \| TYPE NAME \| TYPE/NAME) [flags]` | Edit and update the definition of one or more resources on the server by using the default editor.
 `exec`        | `kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]` | Execute a command against a container in a pod,
 `explain`    | `kubectl explain [--include-extended-apis=true] [--recursive=false] [flags]` | Get documentation of various resources. For instance pods, nodes, services, etc.