diff --git a/guides/_subsections/add-a-trusted-certificate.md b/guides/_subsections/add-a-trusted-certificate.md index a52f115b..9adaeba4 100644 --- a/guides/_subsections/add-a-trusted-certificate.md +++ b/guides/_subsections/add-a-trusted-certificate.md @@ -1,40 +1,35 @@ ## [Add a Trusted Certificate](#add-a-trusted-certificate) -If you have Java Management Extensions **(JMX)** over `SSL` enabled on your containerized **JVMs**, you must configure **Cryostat** to trust the `SSL` certificate presented by the containerized **JVM** when **Cryostat** attempts to open a **JMX** connection. If you do not complete this configuration, **Cryostat** cannot open a **JMX** connection for the purposes of performing **JFR** management tasks. - -Here's how to add a trusted `SSL` certificate with the **Cryostat Web** UI. +If you have Java Management Extensions **(JMX)** over `SSL` enabled on your containerized **JVMs**, you must configure **Cryostat** to trust the `SSL/TLS` certificate presented by the containerized **JVM** when **Cryostat** attempts to open a **JMX** connection. If you do not complete this configuration, **Cryostat** cannot open a **JMX** connection for the purposes of performing **JFR** management tasks.
  1. {% include howto_step.html summary="Navigate to the Security Tab" image-name="3.0.0/navigate-to-security.png" - text="Click the Security tab." + text="Click the Security tab. This should initially be in an empty state if you have not yet defined any additional trusted certificates." %}
  2. +
+ +In order to add a trusted certificate to Cryostat's custom truststore you must first determine the directory that Cryostat loads certificates from. +This is controlled by the configuration property `ssl.truststore.dir` and defaults to `/truststore`. If you are deploying Cryostat manually in an +environment like Podman or Docker Compose, you should create a volume containing the certificates and mount it to this location, or bind-mount a host +directory to this location. If you are using the Cryostat Helm Chart then you should create Secrets containing each trusted certificate and mount +each within this location. If you are using the Cryostat Operator, you should use the `.Spec.TrustedCertSecrets` `CR` property. + +Once you have loaded your additional certificates to the truststore you must restart the Cryostat container, since it can only load certificates +into the JVM truststore at startup time. The container may be restarted automatically when you modify the configuration, depending on your deployment +platform. + +After you have loaded the certificates and verified that the Cryostat container has restarted, you can verify that Cryostat correctly found the +certificate(s) within the truststore directory. + +
  1. {% include howto_step.html - summary="Upload the Certificate" - image-name="3.0.0/add-a-trusted-certificate-upload.png" - text=" - Click the Upload button on the Import SSL Certificates card. This action opens a file-upload dialog, where you can choose the certificate that you want to upload to Cryostat. You can repeat this process multiple times to add multiple trusted certificates. - " + summary="Navigate to the Security Tab" + image-name="3.0.0/navigate-to-security-with-certs.png" + text="Click the Security tab. The file paths of any additional trusted certificates you have added should appear in the list." %}
  2. -
  3. - Restart Cryostat to apply the changes. If you do not restart your Cryostat instance, the added certificates are not reloaded. This causes connections to fail because the Cryostat JMX client cannot trust the certificates. Depending on your deployment platform and configuration, restarting Cryostat might require any of the following: - -
diff --git a/images/3.0.0/navigate-to-security-with-certs.png b/images/3.0.0/navigate-to-security-with-certs.png new file mode 100644 index 00000000..d7e78f81 Binary files /dev/null and b/images/3.0.0/navigate-to-security-with-certs.png differ diff --git a/images/3.0.0/navigate-to-security.png b/images/3.0.0/navigate-to-security.png index 33d1a94a..d8ef1691 100644 Binary files a/images/3.0.0/navigate-to-security.png and b/images/3.0.0/navigate-to-security.png differ