update description of privatecacert template function #3410
Conversation
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
replicated-ci
added
type::docs
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
||
| 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` |
There was a problem hiding this comment.
- Set the
NODE_EXTRA_CA_CERTSenvironment variable to append the CAs from the ConfigMap to any existing CAs in the container- Mount the CAs at
/certsand set theSSL_CERT_DIRenvironment variable to/certs
I wasn't sure how useful these examples were and/or if this is something we'd want to go into greater detail on. Do you think they are good to mention? Anything you'd add? We could also do a follow up story to expand if you think it requires more in-depth docs
There was a problem hiding this comment.
The issue carto ran into is that they wanted to trust the default certs as well as the ones set by the end user for kots existing installs. Setting SSL_CERT_DIR will override the defaults and when the user provides the private cert with the flag, this is the only cert that will be included in the configmap. There are probably more complex alternatives if they want to trust this in addition to the defaults but it is likely they would have to run a script when the pod starts before the application with an init container and this would likely be specific to the os in the container.
For example, if this is debian/ubuntu, they could mount the dir as a subpath under /usr/local/share/ca- certificates and run the command update-ca-certificates.
https://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu
| 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 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 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: |
There was a problem hiding this comment.
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.
This is my own interpretation after reading the current docs on this template function and also reading through the support issue you had sent me https://github.com/replicated-collab/carto-replicated/issues/67. It seemed like it got mounted automatically for kots existing cluster, but that you'd need to manually mount it for embedded cluster. not really sure if that's true
| * 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. |
There was a problem hiding this comment.
For existing cluster installations with KOTS, KOTS automatically mounts the ConfigMap as a volume in the kotsadm container at
/certs.
Pulled this paragraph from the support issue https://github.com/replicated-collab/carto-replicated/issues/67
Same as the comment above, not 100% sure that this only happens in existing cluster installations
| * 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). | ||
| </details> |
There was a problem hiding this comment.
^ added a dropdown with more info about the source of the configmap. Ie, for existing cluster, the user provides it themselves using the --private-ca-configmap flag and for embedded cluster (I think) the configmap gets generated based on the CA trust store for the host
| * 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. |
There was a problem hiding this comment.
| 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. |
| 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 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 |
|
|
||
| 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` |
There was a problem hiding this comment.
The issue carto ran into is that they wanted to trust the default certs as well as the ones set by the end user for kots existing installs. Setting SSL_CERT_DIR will override the defaults and when the user provides the private cert with the flag, this is the only cert that will be included in the configmap. There are probably more complex alternatives if they want to trust this in addition to the defaults but it is likely they would have to run a script when the pod starts before the application with an init container and this would likely be specific to the os in the container.
For example, if this is debian/ubuntu, they could mount the dir as a subpath under /usr/local/share/ca- certificates and run the command update-ca-certificates.
https://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu
|
|
||
| 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 |
There was a problem hiding this comment.
the last sentence is incomplete
| @@ -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 an end customer's environment. | |||
There was a problem hiding this comment.
This isnt necessarily true. It really contains what it says in your bullets below, the file provided by the end user in kots installs or the host ca trust store in EC installs.
preview: https://deploy-preview-3410--replicated-docs.netlify.app/reference/template-functions-static-context#privatecacert