Merge pull request #3410 from replicatedhq/126718

update description of privatecacert template function

Author: paigecalvert

docs/reference/template-functions-static-context.md

@@ -16,14 +16,30 @@ This topic provides a list of the KOTS template functions in the Static context.
 func PrivateCACert() string
 ```
 
-For KOTS installations, PrivateCACert returns the name of a ConfigMap that contains CA certificates provided by the end user with the `--private-ca-configmap` flag for the install command. For Embedded Cluster installations, the ConfigMap returned by PrivateCACert contains the CA trust store from the host. Embedded Cluster determines the CA trust store by first checking for the `SSL_CERT_FILE` environment variable. If `SSL_CERT_FILE` is not set, Embedded Cluster then searches common certificate paths and uses the first valid certificate file found.
+PrivateCACert returns the name of a ConfigMap containing one or more private CA certificates:
 
-You can use this template function to mount the specified ConfigMap so your containers can access the internet through enterprise proxies that issue their own TLS certificates in order to inspect traffic.
+* For Embedded Cluster installations, the ConfigMap returned by PrivateCACert contains the CA trust store from the host. Embedded Cluster determines the CA trust store by first checking the `SSL_CERT_FILE` environment variable. If `SSL_CERT_FILE` is not set, Embedded Cluster then searches common certificate paths and uses the first valid certificate file found.
+
+* For KOTS installations in existing clusters, the end user can optionally create and pass the ConfigMap to the `install` command using the `--private-ca-configmap` flag. For more information, see [install](/reference/kots-cli-install).
 
 :::note
-This function returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, this function returns the empty string.
+PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string.
 :::
 
+KOTS mounts the ConfigMap returned by the PrivateCACert template function as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as the file's contents. KOTS then sets the `SSL_CERT_DIR` environment variable in the kotsadm container to `/certs`. `SSL_CERT_DIR` is a common environment variable that is supported by most tools and languages to override the trust store.
+
+The primary use case for the PrivateCACert template function is to make sure that KOTS trusts the private CA certificates issued by TLS man-in-the-middle (MITM) proxies in the end user's environment and can make outbound internet connects without TLS errors.
+
+<details>
+  <summary>Can the ConfigMap returned by PrivateCACert also be mounted in application containers?</summary>
+
+  You can use the PrivateCACert template function to mount the ConfigMap in your application container. To do so, you can use the same method that is used by KOTS described above. However, note that the `SSL_CERT_DIR` environment variable overrides the trust store in the container. This means that only the CAs included in the ConfigMap will be trusted.
+
+  If you do _not_ want to override the trust store, you should mount the ConfigMap to an alternate directory in the container and append the certificates to the default trust store. For example, for Debian/Ubuntu environments, you could mount the ConfigMap from the PrivateCACert template function in a subpath of the `/usr/local/share/ca-certificates` directory in the container, and run the `update-ca-certificates` command in an init container or the container's entrypoint to update the trust store in the container to include the additional certificates.
+  
+  Replicated recommends that you consider the container OS and the language(s) used by your application to determine the method that you want to use to append certificates to the trust store.
+</details>
+
 ## Cluster Information Functions
 
 ### Distribution