From 8a1f5523ea6986ee7dca94abb0bf8b1a24f8840a Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 30 Jul 2025 16:13:50 -0600 Subject: [PATCH 01/12] update description of privatecacert template function --- .../template-functions-static-context.md | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index 0177fa080f..c464b6cf34 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -16,12 +16,28 @@ 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 any private CA certificates issued by TLS proxies that intercept outbound traffic in your end customers' environments. -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. +When the ConfigMap returned by PrivateCACert is mounted, your application containers trust the private CA certificates issued by TLS proxies. This allows your application to make outbound internet connections in customer environments without getting TLS errors. + +For Replicated Embedded Cluster installations on VMs or bare metal servers, you must manually mount the ConfigMap. Some examples of how to mount the ConfigMap include: +* Set the `NODE_EXTRA_CA_CERTS` environment variable to append the CAs from the ConfigMap to any existing CAs in the container +* Mount the CAs at `certs` and set the `SSL_CERT_DIR` environment variable to `/certs` + +For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as 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 append certificates to the trust store. + +
+ Where does the ConfigMap returned by the PrivateCACert template function come from? + + The ConfigMap returned by the PrivateCACert template function has a different source depending on if the user is installing with Replicated Embedded Cluster on a VM or bare metal server, or with KOTS in an existing cluster: + + * 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. Embedded Cluster than adds + + * For KOTS installations in existing clusters, the end user passes 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. ::: ## Cluster Information Functions From e6cb4bdfe5ab7f6fa10c46fdcfd53487a9e9dbc6 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 30 Jul 2025 16:16:02 -0600 Subject: [PATCH 02/12] copy edits --- docs/reference/template-functions-static-context.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index c464b6cf34..95f42ab5c8 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -16,13 +16,13 @@ This topic provides a list of the KOTS template functions in the Static context. func PrivateCACert() string ``` -PrivateCACert returns the name of a ConfigMap containing any private CA certificates issued by TLS proxies that intercept outbound traffic in your end customers' environments. +PrivateCACert returns the name of a ConfigMap containing any private CA certificates issued by TLS proxies that intercept outbound traffic in an end customer's environment. -When the ConfigMap returned by PrivateCACert is mounted, your application containers trust the private CA certificates issued by TLS proxies. This allows your application to make outbound internet connections in customer environments without getting TLS errors. +When the ConfigMap returned by PrivateCACert is mounted, your application containers can then trust the private CA certificates issued by TLS proxies. This allows your application to make outbound internet connections in customer environments without getting TLS errors. -For Replicated Embedded Cluster installations on VMs or bare metal servers, you must manually mount the ConfigMap. Some examples of how to mount the ConfigMap include: +For Replicated Embedded Cluster installations on VMs or bare metal servers, you must manually mount the ConfigMap returned by the PrivateCACert template function to ensure that your application trusts the private TLS certificates. Some examples of how to mount the ConfigMap include: * Set the `NODE_EXTRA_CA_CERTS` environment variable to append the CAs from the ConfigMap to any existing CAs in the container -* Mount the CAs at `certs` and set the `SSL_CERT_DIR` environment variable to `/certs` +* Mount the CAs at `/certs` and set the `SSL_CERT_DIR` environment variable to `/certs` For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as 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 append certificates to the trust store. From 4ceb4d5c17bef663186db8336af8dc8bd3a6848d Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 09:16:51 -0600 Subject: [PATCH 03/12] Update docs/reference/template-functions-static-context.md Co-authored-by: Ethan Mosbaugh --- docs/reference/template-functions-static-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index 95f42ab5c8..81264bf573 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -24,7 +24,7 @@ For Replicated Embedded Cluster installations on VMs or bare metal servers, you * Set the `NODE_EXTRA_CA_CERTS` environment variable to append the CAs from the ConfigMap to any existing CAs in the container * Mount the CAs at `/certs` and set the `SSL_CERT_DIR` environment variable to `/certs` -For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as 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 append certificates to the trust store. +For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as 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.
Where does the ConfigMap returned by the PrivateCACert template function come from? From 25148fb4f6da0818f88516f4dc1712bfebed94e9 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 10:31:18 -0600 Subject: [PATCH 04/12] edits --- .../template-functions-static-context.md | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index 81264bf573..c388a71814 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -16,29 +16,31 @@ This topic provides a list of the KOTS template functions in the Static context. func PrivateCACert() string ``` -PrivateCACert returns the name of a ConfigMap containing any private CA certificates issued by TLS proxies that intercept outbound traffic in an end customer's environment. +PrivateCACert returns the name of a ConfigMap containing one or more private CA certificates. The CA certificates included in the ConfigMap differ depending on if the user is installing with Replicated Embedded Cluster on a VM or bare metal server, or with KOTS in an existing cluster: -When the ConfigMap returned by PrivateCACert is mounted, your application containers can then trust the private CA certificates issued by TLS proxies. This allows your application to make outbound internet connections in customer environments without getting TLS errors. +* 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 Replicated Embedded Cluster installations on VMs or bare metal servers, you must manually mount the ConfigMap returned by the PrivateCACert template function to ensure that your application trusts the private TLS certificates. Some examples of how to mount the ConfigMap include: -* Set the `NODE_EXTRA_CA_CERTS` environment variable to append the CAs from the ConfigMap to any existing CAs in the container -* Mount the CAs at `/certs` and set the `SSL_CERT_DIR` environment variable to `/certs` +* For KOTS installations in existing clusters, the end user passes the ConfigMap to the `install` command using the `--private-ca-configmap` flag. For more information, see [install](/reference/kots-cli-install). -For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as 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. +:::note +PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string. +::: -
- Where does the ConfigMap returned by the PrivateCACert template function come from? +You can use the PrivateCACert template function to mount this ConfigMap so that your application containers trust the private CA certificates issued by TLS proxies that intercept outbound traffic in end customer environments. This allows your application to make outbound internet connections in customer environments without getting TLS errors. - The ConfigMap returned by the PrivateCACert template function has a different source depending on if the user is installing with Replicated Embedded Cluster on a VM or bare metal server, or with KOTS in an existing cluster: +The steps to mount the ConfigMap returned by PrivateCACert vary depending on the installation type: - * 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. Embedded Cluster than adds +* For Replicated Embedded Cluster installations on VMs or bare metal servers, you must manually mount the ConfigMap returned by the PrivateCACert template function to ensure that your application trusts the private TLS certificates. For example: + * Use an init container to append the custom CAs into the system trust store (which is usually located at `/etc/ssl/certs/ca-certificates.crt`) before the application is deployed + * For applications that use Node.js, set the `NODE_EXTRA_CA_CERTS` environment variable to append the CAs from the ConfigMap to any existing CAs in the container. For more information, see [Environment Variables](https://nodejs.org/docs/latest-v4.x/api/cli.html#cli_node_extra_ca_certs_file) in the Node.js documentation. - * For KOTS installations in existing clusters, the end user passes the ConfigMap to the `install` command using the `--private-ca-configmap` flag. For more information, see [install](/reference/kots-cli-install). -
+* For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as 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. -:::note -PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string. -::: + :::note + If you must not override the trust store on the host (such as if your application needs to trust the default CAs as well as any CAs set by the end user during existing cluster KOTS installations), you can mount the CAs that KOTS adds in a subpath in the `SSL_CERT_DIR` and then modify the containers to update the trusted CAs during deployment. + + For Debian/Ubuntu installations, Replicated recommends that you do this by mounting the directory as a subpath under `/usr/local/share/ca-certificates` and using the Ubuntu `update-ca-certificates` command to generate a concatenated single-file list of certificates. For more information, see [update-ca-certificates](https://manpages.ubuntu.com/manpages/focal/man8/update-ca-certificates.8.html) in the Ubuntu documentation. + ::: ## Cluster Information Functions From 315b6f860b0d47291b42b012baf8a5654bda6320 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 14:13:03 -0600 Subject: [PATCH 05/12] edits --- .../template-functions-static-context.md | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index c388a71814..3b1889dceb 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -16,31 +16,29 @@ This topic provides a list of the KOTS template functions in the Static context. func PrivateCACert() string ``` -PrivateCACert returns the name of a ConfigMap containing one or more private CA certificates. The CA certificates included in the ConfigMap differ depending on if the user is installing with Replicated Embedded Cluster on a VM or bare metal server, or with KOTS in an existing cluster: +PrivateCACert returns the name of a ConfigMap containing one or more private CA certificates: * 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 passes the ConfigMap to the `install` command using the `--private-ca-configmap` flag. For more information, see [install](/reference/kots-cli-install). +* For KOTS installations in existing clusters, the end user creates and passes the ConfigMap to the `install` command using the `--private-ca-configmap` flag. For more information, see [install](/reference/kots-cli-install). :::note PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string. ::: -You can use the PrivateCACert template function to mount this ConfigMap so that your application containers trust the private CA certificates issued by TLS proxies that intercept outbound traffic in end customer environments. This allows your application to make outbound internet connections in customer environments without getting TLS errors. +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 in the container. -The steps to mount the ConfigMap returned by PrivateCACert vary depending on the installation type: +When the ConfigMap contains the private CA certificates issued by TLS proxies in end user environments and is mounted in the kotsadm container, KOTS trusts these private certificates and can make outbound internet connects without getting TLS errors. -* For Replicated Embedded Cluster installations on VMs or bare metal servers, you must manually mount the ConfigMap returned by the PrivateCACert template function to ensure that your application trusts the private TLS certificates. For example: - * Use an init container to append the custom CAs into the system trust store (which is usually located at `/etc/ssl/certs/ca-certificates.crt`) before the application is deployed - * For applications that use Node.js, set the `NODE_EXTRA_CA_CERTS` environment variable to append the CAs from the ConfigMap to any existing CAs in the container. For more information, see [Environment Variables](https://nodejs.org/docs/latest-v4.x/api/cli.html#cli_node_extra_ca_certs_file) in the Node.js documentation. +
+ Can the ConfigMap returned by PrivateCACert be mounted in application containers? -* For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at `/certs`. Each key in the ConfigMap is created as a file, with its value as 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. + 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. - :::note - If you must not override the trust store on the host (such as if your application needs to trust the default CAs as well as any CAs set by the end user during existing cluster KOTS installations), you can mount the CAs that KOTS adds in a subpath in the `SSL_CERT_DIR` and then modify the containers to update the trusted CAs during deployment. + If you do _not_ want to override the trust store, you can mount the CAs that KOTS adds in a subpath in the `SSL_CERT_DIR` and then modify the containers to update the trusted CAs during deployment. For example, you could mount the CAs that KOTS adds in a subpath of the `/usr/local/share/ca-certificates` directory in the container, and run the Ubuntu `update-ca-certificates` command in an init container or entrypoint to generate a concatenated single-file list of certificates. - For Debian/Ubuntu installations, Replicated recommends that you do this by mounting the directory as a subpath under `/usr/local/share/ca-certificates` and using the Ubuntu `update-ca-certificates` command to generate a concatenated single-file list of certificates. For more information, see [update-ca-certificates](https://manpages.ubuntu.com/manpages/focal/man8/update-ca-certificates.8.html) in the Ubuntu documentation. - ::: + 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. +
## Cluster Information Functions From d349be955457c11806a8a7432a3518d5623dee45 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 14:50:03 -0600 Subject: [PATCH 06/12] edits --- docs/reference/template-functions-static-context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index 3b1889dceb..a83516e245 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -28,10 +28,10 @@ PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no ent 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 in the container. -When the ConfigMap contains the private CA certificates issued by TLS proxies in end user environments and is mounted in the kotsadm container, KOTS trusts these private certificates and can make outbound internet connects without getting TLS errors. +The primary use case for the PrivateCACert template function is to make sure that KOTS trusts the private CA certificates issued by TLS proxies in the end user's environment and can make outbound internet connects without TLS errors.
- Can the ConfigMap returned by PrivateCACert be mounted in application containers? + Can the ConfigMap returned by PrivateCACert also be mounted in application containers? 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. From 73c08f9bc0eaa770802573511b12bda9b75245fd Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 15:16:09 -0600 Subject: [PATCH 07/12] small edit --- docs/reference/template-functions-static-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index a83516e245..f06d8b2595 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -35,7 +35,7 @@ The primary use case for the PrivateCACert template function is to make sure tha 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 can mount the CAs that KOTS adds in a subpath in the `SSL_CERT_DIR` and then modify the containers to update the trusted CAs during deployment. For example, you could mount the CAs that KOTS adds in a subpath of the `/usr/local/share/ca-certificates` directory in the container, and run the Ubuntu `update-ca-certificates` command in an init container or entrypoint to generate a concatenated single-file list of certificates. + If you do _not_ want to override the trust store, you can mount the CAs that KOTS adds in a subpath in the `SSL_CERT_DIR` and then modify the containers to update the trusted CAs during deployment. For example, for Debian/Ubuntu environments, you could mount the CAs that KOTS adds in a subpath of the `/usr/local/share/ca-certificates` directory in the container, and run the Ubuntu `update-ca-certificates` command in an init container or entrypoint to generate a concatenated single-file list of 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.
From 45b65c29332e43e8d81cdbfbe42edc17b8203c2e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 16:07:39 -0600 Subject: [PATCH 08/12] Update docs/reference/template-functions-static-context.md Co-authored-by: Ethan Mosbaugh --- docs/reference/template-functions-static-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index f06d8b2595..0248efe609 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -20,7 +20,7 @@ PrivateCACert returns the name of a ConfigMap containing one or more private CA * 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 creates and passes the ConfigMap to the `install` command using the `--private-ca-configmap` flag. For more information, see [install](/reference/kots-cli-install). +* For KOTS installations in existing clusters, the end user may 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 PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string. From 1d3f2adcab7f03b4b76a8333e2436239d8719b93 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 16:07:51 -0600 Subject: [PATCH 09/12] Update docs/reference/template-functions-static-context.md Co-authored-by: Ethan Mosbaugh --- docs/reference/template-functions-static-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index 0248efe609..baf38b9ec2 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -26,7 +26,7 @@ PrivateCACert returns the name of a ConfigMap containing one or more private CA 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 in the container. +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 proxies in the end user's environment and can make outbound internet connects without TLS errors. From 8b13a47b69d9d68c1087d72cec62c6c73fbfb374 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 16:08:00 -0600 Subject: [PATCH 10/12] Update docs/reference/template-functions-static-context.md Co-authored-by: Ethan Mosbaugh --- docs/reference/template-functions-static-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index baf38b9ec2..066963f474 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -28,7 +28,7 @@ PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no ent 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 proxies in the end user's environment and can make outbound internet connects without TLS errors. +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 proxies in the end user's environment and can make outbound internet connects without TLS errors.
Can the ConfigMap returned by PrivateCACert also be mounted in application containers? From d8bc50c98b0f0cec8a56f11076d7297b11271b03 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 16:08:44 -0600 Subject: [PATCH 11/12] Update docs/reference/template-functions-static-context.md Co-authored-by: Ethan Mosbaugh --- docs/reference/template-functions-static-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index 066963f474..09a005a23e 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -35,7 +35,7 @@ The primary use case for the PrivateCACert template function is to make sure tha 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 can mount the CAs that KOTS adds in a subpath in the `SSL_CERT_DIR` and then modify the containers to update the trusted CAs during deployment. For example, for Debian/Ubuntu environments, you could mount the CAs that KOTS adds in a subpath of the `/usr/local/share/ca-certificates` directory in the container, and run the Ubuntu `update-ca-certificates` command in an init container or entrypoint to generate a concatenated single-file list of certificates. + 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.
From b8bd9aa91ee3b74abab1c4bbda6a3f1cf2296245 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 16:11:57 -0600 Subject: [PATCH 12/12] copy edits --- docs/reference/template-functions-static-context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/template-functions-static-context.md b/docs/reference/template-functions-static-context.md index 09a005a23e..0916ae089e 100644 --- a/docs/reference/template-functions-static-context.md +++ b/docs/reference/template-functions-static-context.md @@ -20,7 +20,7 @@ PrivateCACert returns the name of a ConfigMap containing one or more private CA * 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 may 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). +* 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 PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string. @@ -28,7 +28,7 @@ PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no ent 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 proxies in the end user's environment and can make outbound internet connects without TLS errors. +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.
Can the ConfigMap returned by PrivateCACert also be mounted in application containers?