Merge pull request #30348 from afirth/2021-11-03-docs-for-kustomize-env-vars

[DOCS] Document the environment variable substitution feature of kustomize configMapGenerator

content/en/docs/tasks/manage-kubernetes-objects/kustomization.md

@@ -86,12 +86,20 @@ metadata:
   name: example-configmap-1-8mbdf7882g
 ```
 
-To generate a ConfigMap from an env file, add an entry to the `envs` list in `configMapGenerator`. Here is an example of generating a ConfigMap with a data item from a `.env` file:
+To generate a ConfigMap from an env file, add an entry to the `envs` list in `configMapGenerator`. This can also be used to set values from local environment variables by omitting the `=` and the value.
+
+{{< note >}}
+It's recommended to use the local environment variable population functionality sparingly - an overlay with a patch is often more maintainable. Setting values from the environment may be useful when they cannot easily be predicted, such as a git SHA.
+{{< /note >}}
+
+Here is an example of generating a ConfigMap with a data item from a `.env` file:
 
 ```shell
 # Create a .env file
+# BAZ will be populated from the local environment variable $BAZ
 cat <<EOF >.env
 FOO=Bar
+BAZ
 EOF
 
 cat <<EOF >./kustomization.yaml
@@ -105,7 +113,7 @@ EOF
 The generated ConfigMap can be examined with the following command:
 
 ```shell
-kubectl kustomize ./
+BAZ=Qux kubectl kustomize ./
 ```
 
 The generated ConfigMap is:
@@ -113,10 +121,11 @@ The generated ConfigMap is:
 ```yaml
 apiVersion: v1
 data:
+  BAZ: Qux
   FOO: Bar
 kind: ConfigMap
 metadata:
-  name: example-configmap-1-42cfbf598f
+  name: example-configmap-1-892ghb99c8
 ```
 
 {{< note >}}