Merge pull request #35383 from shannonxtreme/manage-secrets-file-note

Improve Managing Secrets using a Configuration File

content/en/docs/tasks/configmap-secret/managing-secret-using-config-file.md

@@ -13,65 +13,70 @@ description: Creating Secret objects using resource configuration file.
 
 <!-- steps -->
 
-## Create the Config file
+## Create the Secret {#create-the-config-file}
 
-You can create a Secret in a file first, in JSON or YAML format, and then
-create that object.  The
+You can define the `Secret` object in a manifest first, in JSON or YAML format,
+and then create that object. The
 [Secret](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#secret-v1-core)
 resource contains two maps: `data` and `stringData`.
 The `data` field is used to store arbitrary data, encoded using base64. The
 `stringData` field is provided for convenience, and it allows you to provide
-Secret data as unencoded strings.
+the same data as unencoded strings.
 The keys of `data` and `stringData` must consist of alphanumeric characters,
 `-`, `_` or `.`.
 
-For example, to store two strings in a Secret using the `data` field, convert
-the strings to base64 as follows:
+The following example stores two strings in a Secret using the `data` field.
 
-```shell
-echo -n 'admin' | base64
-```
+1. Convert the strings to base64:
 
-The output is similar to:
+   ```shell
+   echo -n 'admin' | base64
+   echo -n '1f2d1e2e67df' | base64
+   ```
 
-```
-YWRtaW4=
-```
+   {{< note >}}
+   The serialized JSON and YAML values of Secret data are encoded as base64 strings. Newlines are not valid within these strings and must be omitted. When using the `base64` utility on Darwin/macOS, users should avoid 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 the `-w` option is not available.
+   {{< /note >}}
 
-```shell
-echo -n '1f2d1e2e67df' | base64
-```
+   The output is similar to:
 
-The output is similar to:
+   ```
+   YWRtaW4=
+   MWYyZDFlMmU2N2Rm
+   ```
 
-```
-MWYyZDFlMmU2N2Rm
-```
+1. Create the manifest:
 
-Write a Secret config file that looks like this:
+   ```yaml
+   apiVersion: v1
+   kind: Secret
+   metadata:
+     name: mysecret
+   type: Opaque
+   data:
+     username: YWRtaW4=
+     password: MWYyZDFlMmU2N2Rm
+   ```
 
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: mysecret
-type: Opaque
-data:
-  username: YWRtaW4=
-  password: MWYyZDFlMmU2N2Rm
-```
+   Note that the name of a Secret object must be a valid
+   [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
 
-Note that the name of a Secret object must be a valid
-[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
+1. Create the Secret using [`kubectl apply`](/docs/reference/generated/kubectl/kubectl-commands#apply):
 
-{{< note >}}
-The serialized JSON and YAML values of Secret data are encoded as base64
-strings. Newlines are not valid within these strings and must be omitted. When
-using the `base64` utility on Darwin/macOS, users should avoid 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 the `-w`
-option is not available.
-{{< /note >}}
+   ```shell
+   kubectl apply -f ./secret.yaml
+   ```
+
+   The output is similar to:
+
+   ```
+   secret/mysecret created
+   ```
+
+To verify that the Secret was created and to decode the Secret data, refer to
+[Managing Secrets using kubectl](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#verify-the-secret).
+
+### Specify unencoded data when creating a Secret
 
 For certain scenarios, you may wish to use the `stringData` field instead. This
 field allows you to put a non-base64 encoded string directly into the Secret,
@@ -103,25 +108,10 @@ stringData:
     username: <user>
     password: <password>
 ```
+When you retrieve the Secret data, the command returns the encoded values,
+and not the plaintext values you provided in `stringData`.
 
-## Create the Secret object
-
-Now create the Secret using [`kubectl apply`](/docs/reference/generated/kubectl/kubectl-commands#apply):
-
-```shell
-kubectl apply -f ./secret.yaml
-```
-
-The output is similar to:
-
-```
-secret/mysecret created
-```
-
-## Check the Secret
-
-The `stringData` field is a write-only convenience field. It is never output when
-retrieving Secrets. For example, if you run the following command:
+For example, if you run the following command:
 
 ```shell
 kubectl get secret mysecret -o yaml
@@ -143,14 +133,11 @@ metadata:
 type: Opaque
 ```
 
-The commands `kubectl get` and `kubectl describe` avoid showing the contents of a `Secret` by
-default. This is to protect the `Secret` from being exposed accidentally to an onlooker,
-or from being stored in a terminal log.
-To check the actual content of the encoded data, please refer to
-[decoding secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret).
+### Specifying both `data` and `stringData`
 
-If a field, such as `username`, is specified in both `data` and `stringData`,
-the value from `stringData` is used. For example, the following Secret definition:
+If you specify a field in both `data` and `stringData`, the value from `stringData` is used.
+
+For example, if you define the following Secret:
 
 ```yaml
 apiVersion: v1
@@ -164,7 +151,7 @@ stringData:
   username: administrator
 ```
 
-Results in the following Secret:
+The `Secret` object is created as follows:
 
 ```yaml
 apiVersion: v1
@@ -180,7 +167,7 @@ metadata:
 type: Opaque
 ```
 
-Where `YWRtaW5pc3RyYXRvcg==` decodes to `administrator`.
+`YWRtaW5pc3RyYXRvcg==` decodes to `administrator`.
 
 ## Clean Up
 

content/en/docs/tasks/configmap-secret/managing-secret-using-kubectl.md

@@ -113,6 +113,8 @@ The commands `kubectl get` and `kubectl describe` avoid showing the contents
 of a `Secret` by default. This is to protect the `Secret` from being exposed
 accidentally, or from being stored in a terminal log.
 
+To check the actual content of the encoded data, refer to [Decoding the Secret](#decoding-secret).
+
 ## Decoding the Secret  {#decoding-secret}
 
 To view the contents of the Secret you created, run the following command: