update kubectl documentation (#12867)

* update kubectl documentation

* add document for Secret/ConfigMap generators

* replace `kubectl create -f` by `kubectl apply -f`

* Add page for kustomization support in kubectl

* fix spelling errors and address comments

content/en/docs/concepts/cluster-administration/logging.md

@@ -35,7 +35,7 @@ a container that writes some text to standard output once per second.
 To run this pod, use the following command:
 
 ```shell
-$ kubectl create -f https://k8s.io/examples/debug/counter-pod.yaml
+kubectl apply -f https://k8s.io/examples/debug/counter-pod.yaml
 pod/counter created
 ```
 

content/en/docs/concepts/cluster-administration/manage-deployment.md

@@ -26,23 +26,23 @@ Many applications require multiple resources to be created, such as a Deployment
 Multiple resources can be created the same way as a single resource:
 
 ```shell
-$ kubectl create -f https://k8s.io/examples/application/nginx-app.yaml
+$ kubectl apply -f https://k8s.io/examples/application/nginx-app.yaml
 service/my-nginx-svc created
 deployment.apps/my-nginx created
 ```
 
 The resources will be created in the order they appear in the file. Therefore, it's best to specify the service first, since that will ensure the scheduler can spread the pods associated with the service as they are created by the controller(s), such as Deployment.
 
-`kubectl create` also accepts multiple `-f` arguments:
+`kubectl apply` also accepts multiple `-f` arguments:
 
 ```shell
-$ kubectl create -f https://k8s.io/examples/application/nginx/nginx-svc.yaml -f https://k8s.io/examples/application/nginx/nginx-deployment.yaml
+kubectl apply -f https://k8s.io/examples/application/nginx/nginx-svc.yaml -f https://k8s.io/examples/application/nginx/nginx-deployment.yaml
 ```
 
 And a directory can be specified rather than or in addition to individual files:
 
 ```shell
-$ kubectl create -f https://k8s.io/examples/application/nginx/
+kubectl apply -f https://k8s.io/examples/application/nginx/
 ```
 
 `kubectl` will read any files with suffixes `.yaml`, `.yml`, or `.json`.
@@ -52,7 +52,7 @@ It is a recommended practice to put resources related to the same microservice o
 A URL can also be specified as a configuration source, which is handy for deploying directly from configuration files checked into github:
 
 ```shell
-$ kubectl create -f https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/application/nginx/nginx-deployment.yaml
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/application/nginx/nginx-deployment.yaml
 deployment.apps/my-nginx created
 ```
 
@@ -83,7 +83,7 @@ service "my-nginx-svc" deleted
 Because `kubectl` outputs resource names in the same syntax it accepts, it's easy to chain operations using `$()` or `xargs`:
 
 ```shell
-$ kubectl get $(kubectl create -f docs/concepts/cluster-administration/nginx/ -o name | grep service)
+kubectl get $(kubectl apply -f docs/concepts/cluster-administration/nginx/ -o name | grep service)
 NAME           TYPE           CLUSTER-IP   EXTERNAL-IP   PORT(S)      AGE
 my-nginx-svc   LoadBalancer   10.0.0.208   <pending>     80/TCP       0s
 ```
@@ -108,14 +108,14 @@ project/k8s/development
 By default, performing a bulk operation on `project/k8s/development` will stop at the first level of the directory, not processing any subdirectories. If we had tried to create the resources in this directory using the following command, we would have encountered an error:
 
 ```shell
-$ kubectl create -f project/k8s/development
+kubectl apply -f project/k8s/development
 error: you must provide one or more resources by argument or filename (.json|.yaml|.yml|stdin)
 ```
 
 Instead, specify the `--recursive` or `-R` flag with the `--filename,-f` flag as such:
 
 ```shell
-$ kubectl create -f project/k8s/development --recursive
+kubectl apply -f project/k8s/development --recursive
 configmap/my-config created
 deployment.apps/my-deployment created
 persistentvolumeclaim/my-pvc created
@@ -126,7 +126,7 @@ The `--recursive` flag works with any operation that accepts the `--filename,-f`
 The `--recursive` flag also works when multiple `-f` arguments are provided:
 
 ```shell
-$ kubectl create -f project/k8s/namespaces -f project/k8s/development --recursive
+$ kubectl apply -f project/k8s/namespaces -f project/k8s/development --recursive
 namespace/development created
 namespace/staging created
 configmap/my-config created
@@ -169,7 +169,7 @@ and
 The labels allow us to slice and dice our resources along any dimension specified by a label:
 
 ```shell
-$ kubectl create -f examples/guestbook/all-in-one/guestbook-all-in-one.yaml
+$ kubectl apply -f examples/guestbook/all-in-one/guestbook-all-in-one.yaml
 $ kubectl get pods -Lapp -Ltier -Lrole
 NAME                           READY     STATUS    RESTARTS   AGE       APP         TIER       ROLE
 guestbook-fe-4nlpb             1/1       Running   0          1m        guestbook   frontend   <none>
@@ -320,7 +320,7 @@ Then, you can use [`kubectl apply`](/docs/reference/generated/kubectl/kubectl-co
 This command will compare the version of the configuration that you're pushing with the previous version and apply the changes you've made, without overwriting any automated changes to properties you haven't specified.
 
 ```shell
-$ kubectl apply -f https://k8s.io/examples/application/nginx/nginx-deployment.yaml
+kubectl apply -f https://k8s.io/examples/application/nginx/nginx-deployment.yaml
 deployment.apps/my-nginx configured
 ```
 
@@ -330,10 +330,6 @@ Currently, resources are created without this annotation, so the first invocatio
 
 All subsequent calls to `kubectl apply`, and other commands that modify the configuration, such as `kubectl replace` and `kubectl edit`, will update the annotation, allowing subsequent calls to `kubectl apply` to detect and perform deletions using a three-way diff.
 
-{{< note >}}
-To use apply, always create resource initially with either `kubectl apply` or `kubectl create --save-config`.
-{{< /note >}}
-
 ### kubectl edit
 
 Alternatively, you may also update resources with `kubectl edit`:
@@ -379,8 +375,7 @@ deployment.apps/my-nginx replaced
 
 At some point, you'll eventually need to update your deployed application, typically by specifying a new image or image tag, as in the canary deployment scenario above. `kubectl` supports several update operations, each of which is applicable to different scenarios.
 
-We'll guide you through how to create and update applications with Deployments. If your deployed application is managed by Replication Controllers,
-you should read [how to use `kubectl rolling-update`](/docs/tasks/run-application/rolling-update-replication-controller/) instead.
+We'll guide you through how to create and update applications with Deployments.
 
 Let's say you were running version 1.7.9 of nginx:
 

content/en/docs/concepts/configuration/assign-pod-node.md

@@ -69,7 +69,7 @@ Then add a nodeSelector like so:
 
 {{< codenew file="pods/pod-nginx.yaml" >}}
 
-When you then run `kubectl create -f https://k8s.io/examples/pods/pod-nginx.yaml`,
+When you then run `kubectl apply -f https://k8s.io/examples/pods/pod-nginx.yaml`,
 the Pod will get scheduled on the node that you attached the label to. You can
 verify that it worked by running `kubectl get pods -o wide` and looking at the
 "NODE" that the Pod was assigned to.

content/en/docs/concepts/configuration/overview.md

@@ -23,7 +23,7 @@ This is a living document. If you think of something that is not on this list bu
 
 - Group related objects into a single file whenever it makes sense. One file is often easier to manage than several. See the [guestbook-all-in-one.yaml](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/guestbook/all-in-one/guestbook-all-in-one.yaml) file as an example of this syntax.
 
-- Note also that many `kubectl` commands can be called on a directory. For example, you can call `kubectl create` on a directory of config files.
+- Note also that many `kubectl` commands can be called on a directory. For example, you can call `kubectl apply` on a directory of config files.
 
 - Don't specify default values unnecessarily: simple, minimal configuration will make errors less likely.
 
@@ -97,7 +97,7 @@ The caching semantics of the underlying image provider make even `imagePullPolic
 
 ## Using kubectl
 
-- Use `kubectl apply -f <directory>` or `kubectl create -f <directory>`. This looks for Kubernetes configuration in all `.yaml`, `.yml`, and `.json` files in `<directory>` and passes it to `apply` or `create`.
+- Use `kubectl apply -f <directory>`. This looks for Kubernetes configuration in all `.yaml`, `.yml`, and `.json` files in `<directory>` and passes it to `apply`.
 
 - Use label selectors for `get` and `delete` operations instead of specific object names. See the sections on [label selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors) and [using labels effectively](/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively).
 

content/en/docs/concepts/configuration/secret.md

@@ -72,6 +72,12 @@ the object on the Apiserver.
 $ kubectl create secret generic db-user-pass --from-file=./username.txt --from-file=./password.txt
 secret "db-user-pass" created
 ```
+{{< note >}}	
+Special characters such as `$`, `\*`, and `!` require escaping.	
+If the password you are using has special characters, you need to escape them using the `\\` character. For example, if your actual password is `S!B\*d$zDsb`, you should execute the command this way:	
+     kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password=S\\!B\\\*d\\$zDsb	
+ You do not need to escape special characters in passwords from files (`--from-file`).	
+{{< /note >}}
 
 You can check that the secret was created like this:
 
@@ -132,10 +138,10 @@ data:
   password: MWYyZDFlMmU2N2Rm
 ```
 
-Now create the Secret using [`kubectl create`](/docs/reference/generated/kubectl/kubectl-commands#create):
+Now create the Secret using [`kubectl apply`](/docs/reference/generated/kubectl/kubectl-commands#apply):
 
 ```shell
-$ kubectl create -f ./secret.yaml
+kubectl apply -f ./secret.yaml
 secret "mysecret" created
 ```
 
@@ -171,7 +177,7 @@ stringData:
 ```
 
 Your deployment tool could then replace the `{{username}}` and `{{password}}`
-template variables before running `kubectl create`.
+template variables before running `kubectl apply`.
 
 stringData is a write-only convenience field. It is never output when
 retrieving Secrets. For example, if you run the following command:
@@ -241,6 +247,73 @@ using the `-b` option to split long lines.  Conversely Linux users *should* add
 the option `-w 0` to `base64` commands or the pipeline `base64 | tr -d '\n'` if
 `-w` option is not available.
 
+#### Creating a Secret from Generator
+Kubectl supports [managing objects using Kustomize](/docs/concepts/overview/object-management-kubectl/kustomization/)
+since 1.14. With this new feature,
+you can also create a Secret from generators and then apply it to create the object on 
+the Apiserver. The generators
+should be specified in a `kustomization.yaml` inside a directory.
+
+For example, to generate a Secret from files `./username.txt` and `./password.txt`
+```shell
+# Create a kustomization.yaml file with SecretGenerator
+cat <<EOF >./kustomization.yaml
+secretGenerator:
+- name: db-user-pass
+  files:
+  - username.txt
+  - password.txt
+EOF
+```
+Apply the kustomization directory to create the Secret object.
+```shell
+$ kubectl apply -k .
+secret/db-user-pass-96mffmfh4k created
+```
+
+You can check that the secret was created like this:
+
+```shell
+$ kubectl get secrets
+NAME                             TYPE                                  DATA      AGE
+db-user-pass-96mffmfh4k          Opaque                                2         51s
+
+$ kubectl describe secrets/db-user-pass-96mffmfh4k
+Name:            db-user-pass
+Namespace:       default
+Labels:          <none>
+Annotations:     <none>
+
+Type:            Opaque
+
+Data
+====
+password.txt:    12 bytes
+username.txt:    5 bytes
+```
+
+For example, to generate a Secret from literals `username=admin` and `password=secret`,
+you can specify the secret generator in `kusotmization.yaml` as
+```shell
+# Create a kustomization.yaml file with SecretGenerator
+$ cat <<EOF >./kustomization.yaml
+secretGenerator:
+- name: db-user-pass
+  literals:
+  - username=admin
+  - password=secret
+EOF
+```
+Apply the kustomization directory to create the Secret object.
+```shell
+$ kubectl apply -k .
+secret/db-user-pass-dddghtt9b5 created
+```
+{{< note >}}
+The generated Secrets name has a suffix appended by hashing the contents. This ensures that a new
+Secret is generated each time the contents is modified.
+{{< /note >}}
+
 #### Decoding a Secret
 
 Secrets can be retrieved via the `kubectl get secret` command. For example, to retrieve the secret created in the previous section:
@@ -583,10 +656,20 @@ start until all the pod's volumes are mounted.
 
 ### Use-Case: Pod with ssh keys
 
-Create a secret containing some ssh keys:
-
+Create a kustomization.yaml with SecretGenerator containing some ssh keys:
+```shell
+$ cp /path/to/.ssh/id_rsa ./id_rsa
+$ cp /path/to/.ssh/id_rsa.pub ./id_rsa.pub
+$ cat <<EOF >./kustomization.yaml
+SecretGenerator:
+- name: ssh-key-secret
+  files:
+  - id_rsa
+  - id_rsa.pub
+```
+Create the SecretObject on Apiserver:
 ```shell
-$ kubectl create secret generic ssh-key-secret --from-file=ssh-privatekey=/path/to/.ssh/id_rsa --from-file=ssh-publickey=/path/to/.ssh/id_rsa.pub
+$ kubectl apply -k .
 ```
 
 {{< caution >}}
@@ -633,26 +716,25 @@ This example illustrates a pod which consumes a secret containing prod
 credentials and another pod which consumes a secret with test environment
 credentials.
 
-Make the secrets:
-
+Make the kustomization.yaml with SecretGenerator
 ```shell
-$ kubectl create secret generic prod-db-secret --from-literal=username=produser --from-literal=password=Y4nys7f11
-secret "prod-db-secret" created
-$ kubectl create secret generic test-db-secret --from-literal=username=testuser --from-literal=password=iluvtests
-secret "test-db-secret" created
+$ cat <<EOF > kustomization.yaml
+secretGenerator:
+- name: prod-db-secret
+  literals:
+  - username=produser
+  - password=Y4nys7f11
+- name: test-db-secret
+  literals:
+  - username=testuser
+  - password=iluvtests
+EOF
 ```
-{{< note >}}
-Special characters such as `$`, `\*`, and `!` require escaping.
-If the password you are using has special characters, you need to escape them using the `\\` character. For example, if your actual password is `S!B\*d$zDsb`, you should execute the command this way:
-
-    kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password=S\\!B\\\*d\\$zDsb
-
-You do not need to escape special characters in passwords from files (`--from-file`).
-{{< /note >}}
 
 Now make the pods:
 
-```yaml
+```shell
+$ cat <<EOF > pod.yaml
 apiVersion: v1
 kind: List
 items:
@@ -692,6 +774,21 @@ items:
       - name: secret-volume
         readOnly: true
         mountPath: "/etc/secret-volume"
+EOF
+```
+
+Add the pods to the same kustomization.yaml
+```shell
+$ cat <<EOF >> kustomization.yaml
+resources:
+- pod.yaml
+EOF
+```
+
+Apply all those objects on the Apiserver by
+
+```shell
+kubectl apply --k .
 ```
 
 Both containers will have the following files present on their filesystems with the values for each container's environment: