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.
  • Review the following naming convention for the custom certificate files that must have specific names for installation in Windows:
    File Expected file naming Expected file format
    Root (CA certificate) root-ca-cert.pem .pem
    Certificate/Key (nodes-administrative/intercommunication) elasticsearch-cert.pem .pem
    elasticsearch-key.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.
  • Review the following naming conventions for the custom certificate files in Linux:
    File Expected file naming Expected file format
    Root (CA certificate) root-ca-cert.pem .pem
    Certificate/Key (nodes-administrative) elasticsearch-cert.pem .pem
    elasticsearch-key.pem
    Certificate/Key (nodes-intercommunication) elasticsearch-node-cert.pem .pem
    elasticsearch-node-key.pem
    • Although elasticsearch-cert.pem is for administrative purposes, we recommend that you use the firstnode hostname.
      Note:
      • For Linux, the elasticsearch-node-cert.pem is used to secure inter-node communication. It must include the host names of the second or third node, ensuring encrypted and trusted communication between cluster members.
      • For Windows, elasticsearch-cert.pem is used for both securing inter-node communication as well as for administrative purposes.
    • Ensure that the following certificates are signed by root/intermediate CA certificate:
      • elasticsearch-cert.pem

        Applicable for both Windows and Linux.

      • elasticsearch-node-cert.pem

        Applicable only for Linux.

  • 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 for Windows:

        OpenSearch .zip folder structure

      • Example for Linux:

        OpenSearch CA for Linux

  • The certificate must have a common name (CN). We recommend using the hostname as CN.

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.