update kubectl documentation

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

@@ -132,10 +132,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 +171,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 +241,69 @@ 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
+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 Secert object.
+```shell
+$ kubectl apply -k .
+secret/db-user-pass-dddghtt9b5 created
+```
+Note that 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.
+
 #### 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 +646,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 +706,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 +764,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:

content/en/docs/concepts/containers/images.md

@@ -205,7 +205,7 @@ example, run these on your desktop/laptop:
 Verify by creating a pod that uses a private image, e.g.:
 
 ```yaml
-kubectl create -f - <<EOF
+kubectl apply -f - <<EOF
 apiVersion: v1
 kind: Pod
 metadata:
@@ -279,8 +279,19 @@ Kubernetes supports specifying registry keys on a pod.
 Run the following command, substituting the appropriate uppercase values:
 
 ```shell
-kubectl create secret docker-registry myregistrykey --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL
-secret/myregistrykey created.
+$ cat <<EOF > ./kustomization.yaml
+secretGenerator:
+- name: myregistrykey
+  type: docker-registry
+  literals:
+  - docker-server=DOCKER_REGISTRY_SERVER
+  - docker-username=DOCKER_USER
+  - docker-password=DOCKER_PASSWORD
+  - docker-email=DOCKER_EMAIL
+EOF
+
+$ kubectl apply -k .
+secret/myregistrykey-66h7d4d986 created
 ```
 
 If you need access to multiple registries, you can create one secret for each registry.
@@ -290,42 +301,13 @@ when pulling images for your Pods.
 Pods can only reference image pull secrets in their own namespace,
 so this process needs to be done one time per namespace.
 
-##### Bypassing kubectl create secrets
-
-If for some reason you need multiple items in a single `.docker/config.json` or need
-control not given by the above command, then you can [create a secret using
-json or yaml](/docs/user-guide/secrets/#creating-a-secret-manually).
-
-Be sure to:
-
-- set the name of the data item to `.dockerconfigjson`
-- base64 encode the docker file and paste that string, unbroken
-  as the value for field `data[".dockerconfigjson"]`
-- set `type` to `kubernetes.io/dockerconfigjson`
-
-Example:
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: myregistrykey
-  namespace: awesomeapps
-data:
-  .dockerconfigjson: UmVhbGx5IHJlYWxseSByZWVlZWVlZWVlZWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGx5eXl5eXl5eXl5eXl5eXl5eXl5eSBsbGxsbGxsbGxsbGxsbG9vb29vb29vb29vb29vb29vb29vb29vb29vb25ubm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg==
-type: kubernetes.io/dockerconfigjson
-```
-
-If you get the error message `error: no objects passed to create`, it may mean the base64 encoded string is invalid.
-If you get an error message like `Secret "myregistrykey" is invalid: data[.dockerconfigjson]: invalid value ...`, it means
-the data was successfully un-base64 encoded, but could not be parsed as a `.docker/config.json` file.
-
 #### Referring to an imagePullSecrets on a Pod
 
 Now, you can create pods which reference that secret by adding an `imagePullSecrets`
 section to a pod definition.
 
-```yaml
+```shell
+$ cat <<EOF > pod.yaml
 apiVersion: v1
 kind: Pod
 metadata:
@@ -337,6 +319,12 @@ spec:
       image: janedoe/awesomeapp:v1
   imagePullSecrets:
     - name: myregistrykey
+EOF
+
+$ cat <<EOF >> ./kustomization.yaml
+resources:
+- pod.yaml
+EOF
 ```
 
 This needs to be done for each pod that is using a private registry.