During the installation of the Control Room in a cluster setup, you can upload custom certificates with a trusted Certificate Authority (CA) instead of using the default certificate provided by the product for enhanced security.

Ensure you review the following guidelines and recommendations before you upload custom certificates:
  • Ensure that the certificates have an appropriate validity (duration) so that the installation does not fail.
  • The custom certificate files must have specific names for installation, follow the below naming convention:
    File Expected file naming Expected file format
    Certificate (nodes) elasticsearch-cert.pem .pem
    Key (nodes) elasticsearch-key.pem .pem
    Root (CA certificate) root-ca-cert.pem .pem
    Note:
    • If you have an intermediate certificate, you can rename it to root-ca-cert.pem to use it as the root certificate. The system will then recognize this intermediate certificate as the root after performing a certificate chain validation up to it.
    • The .zip file must contain the certificate, key, and root CA certificate files.
  • Ensure the certificates in the .zip file follow the below guidelines so that they can be easily accessed and processed by the Control Room.
    • Ensure certificates are not encrypted (no password protection)
    • Include only the three required certificate files
    • Folder structure should not contain any sub folders inside the .zip file.

      Example:

      OpenSearch .zip folder structure
  • The certificate must have a common name (CN). We recommend using the hostname as CN. Only one certificate is required regardless of the number of nodes in the cluster.

Debugging common custom certificate upload errors

Custom certificate retrieval might fail due to the following reasons. For detailed information, check msi logs in the temp folder. Example: C:\Users\<Username>\AppData\Local\Temp.
Error code Possible reason Mitigation
java.security.cert.CertificateExpiredException Certificate is invalid error. Ensure the certificate has not expired, and check for any mismatches in the certificate details. Re-upload the certificate after correcting any issues.
java.Lang.RuntimeException: ERROR required certificate does not exist The .zip folder structure is incorrect or the certificate is missing certificate error. Ensure that the certificates are correctly placed in the .zip folder.
ERROR: java.lang.RuntimeException: Elasticsearch root certificate is not a CA The root CA does not match with node certificate. Verify that the certificate is a valid CA certificate. Correct any issues and re-upload the certificate.