more context on the doc on override values (#2381)

* more context on the doc on override values

Signed-off-by: dmesser <[email protected]>

* Update doc/helm/user-guide.md

Co-Authored-By: Joe Lanford <[email protected]>

* Update doc/helm/user-guide.md

Co-Authored-By: Joe Lanford <[email protected]>

* give context on helm releases

Signed-off-by: dmesser <[email protected]>

Co-authored-by: Joe Lanford <[email protected]>

Author: dmesser

doc/helm/user-guide.md

@@ -310,13 +310,29 @@ kubectl delete -f deploy/crds/example.com_nginxes_crd.yaml
 
 ## Advanced features
 
-### Override Helm chart values
-
-As an operator developer, it is sometimes necessary to enforce that certain values
-provided by the chart's default `values.yaml` or by a CR spec are always overridden
-when templating the chart. An example of when this is useful is when your operator
-is being deployed in a disconnected environment where access to the chart's default
-image references is unavailable.
+## Passing environment variables to the Helm chart
+
+Sometimes it is useful to pass down environment variables from the Operators `Deployment`
+all the way to the helm charts templates. This allows the Operator to be configured at a global
+level at runtime. This is new compared to dealing with the helm CLI
+as they usually don't have access to any environment variables in the context of Tiller (helm v2)
+or the helm binary (helm v3) for security reasons.
+
+With the helm Operator this becomes possible by override values. This enforces that certain
+template values provided by the chart's default `values.yaml` or by a CR spec are always set
+when rendering the chart. If the value is set by a CR it gets overridden by the global override value.
+The override value can be static but can also refer to an environment variable. To pass down environment
+variables to the chart override values is currently the only way.
+
+An example use case of this is when your helm chart references container images by chart variables,
+which is a good practice.
+If your Operator is deployed in a disconnected environment (no network access to the default images
+location) you can use this mechanism to set them globally at the Operator level using environment variables
+versus individually per CR / chart release.
+
+> Note that it is strongly recommended to reference container images in your chart by helm variables
+> and then also associate these with an environment variable of your Operator like shown below.
+> This allows your Operator to be mirrored for offline usage when packaged for OLM.
 
 To configure your operator with override values, add an `overrideValues` map to your
 `watches.yaml` file for the GVK and chart you need to override. For example, to change
@@ -337,15 +353,15 @@ By setting `image.repository` to `quay.io/mycustomrepo` you are ensuring that
 `quay.io/mycustomrepo` will always be used instead of the chart's default repository
 (`nginx`). If the CR attempts to set this value, it will be ignored.
 
-It is also possible to reference environment variables in the `overrideValues` section:
+It is now possible to reference environment variables in the `overrideValues` section:
 
 ```yaml
   overrideValues:
     image.repository: $IMAGE_REPOSITORY # or ${IMAGE_REPOSITORY}
 ```
 
-By using an environment variable reference in `overrideValues` you make it possible to
-set these override values at runtime by setting the environment variable on the
+By using an environment variable reference in `overrideValues` you enable these override
+values to be set at runtime by configuring the environment variable on the
 operator deployment. For example, in `deploy/operator.yaml` you could add the
 following snippet to the container spec: