For a deployment that uses a load balancer, SSL configuration includes client-side and server-side SSL communication. Client-side SSL covers communication between client applications and the load balancer, while server-side SSL covers communication between the load balancer and server nodes and between individual server nodes. See the following instructions for configuring client-side and server-side SSL.

Important: When TLS/SSL is enabled for communication between an ODBC client application and Hybrid Data Pipeline, the server certificate must be encrypted with an OpenSSL 3.5-compliant cryptographic algorithm.

Configure client-side SSL

Client-side SSL covers communication between client applications and the load balancer with SSL termination happening at the load balancer. An SSL configuration is required to enable communication between the server and clients using the On-Premises Connector, the ODBC driver, and the JDBC driver.

Note: For information on updating client-side SSL certificates, refer to Updating SSL certificates in the Best Practices Guide.

Take the following steps to enable client-side SSL.

  1. Configure the load balancer with the full certificate chain. The full chain should include the private and public keys of the SSL certificate, any intermediate certificates, and the root certificate.
  2. Specify the root certificate during the Docker deployment or Linux installation. The root certificate should be supplied in a Base64 encoding, such as a PEM or DER file format.

    • Docker deployment

      Specify the root certificate with the HDP_LOAD_BALANCER_CERT_FILE property. This property may be specified in the hdpdeploy.properties file, or it may be specified as an environment variable in the docker run command. See Deploying Hybrid Data Pipeline using Docker for details.

    • Linux installation

      Specify the root certificate during installation. See Installing the Hybrid Data Pipeline server for details.

  3. For OData, configure your OData application for SSL.

    Note:
    • OData connectivity is handled by an OData layer within Hybrid Data Pipeline, and therefore does not require the use of a separate component. However, you may need to configure your OData application for SSL.
    • If you are using a well-known certificate, the root CA certificate will be used to validate the server certificate. In this scenario, it is unlikely any special configuration will be required.
    • If you are using a less-well-known certificate, you will need to configure your OData application to use the ddcloud.pem certificate file written to the redist directory during deployment of the Hybrid Data Pipeline server. For load balancer deployments, the ddcloud.pem file is written to the redist directory of the key location (or, for Docker deployments, the shared file location).
  4. For ODBC, JDBC, and on-premises connectivity, install the ODBC driver, JDBC driver, and On-Premises Connector. In addition, for ODBC or JDBC connectivity, configure your application to use the ODBC or JDBC driver. See Installing the Hybrid Data Pipeline Driver for ODBC, Installing the Hybrid Data Pipeline Driver for JDBC, and Installing the Hybrid Data Pipeline On-Premises Connector for details.
    Note: The ODBC driver, JDBC driver, and On-Premises Connector need only the root certificate to verify the trust of the server certificate supplied during the SSL handshake. During installation or deployment of the server, the required certificate files are written to the redist directory. These and other files in the redist directory must be used in the installation of the ODBC driver, JDBC driver, and On-Premises Connector. For load balancer deployments, these files are written to the redist directory of the key location (or, for Docker deployments, the shared file location).

Result:

Client-side SSL has been configured. Communication between your application and the load balancer will be encrypted. If using the On-Premises Connector, communication between the On-Premises Connector and the load balancer will be encrypted as well.

Configure server-side SSL

Server-side SSL involves communication between the load balancer and server nodes and between individual server nodes. Server-side SSL is dependent on each node using the same wildcard certificate. With this configuration, each Hybrid Data Pipeline node must reside in the same domain at the same level. For example, a wildcard certificate with the hostname *.example.com could be used to secure nodes with the following subdomains:

  • hdp-node-1.example.com
  • hdp-node-2.example.com

To establish trust, the wildcard certificate must include the full certificate chain, including the private and public keys of the SSL certificate, any intermediate certificates, and the root certificate. In turn, the load balancer must be configured with the root certificate used in the wildcard certificate chain.

Take the following steps to enable server-side SSL.

Note: These steps may also be used to update server-side SSL certificates.
  1. Generate or purchase a wildcard certificate for the Hybrid Data Pipeline environment.
  2. Create the following certificate files.
    • Wildcard node certificate file. This certificate file must include the private and public keys of the SSL certificate, any intermediate certificates, and the root certificate. The wildcard node certificate file must be supplied in PEM file format. See The PEM file for details.
    • Load balancer certificate file. This certificate must contain the root certificate used in the wildcard certificate chain. The root certificate should be supplied in a Base64 encoding, such as a PEM or DER file format.
  3. Configure the load balancer to use the load balancer certificate file. The certificate must be defined for each server connection. See Access ports for a list of ports that must be accessible to the load balancer.
  4. Configure Hybrid Data Pipeline nodes in the Docker deployment or Linux installation.

    • Docker deployment

      Before executing the docker run command, copy the load balancer certificate file and the wildcard node certificate file to the shared file location. Then, set the following properties in the hdpdeploy.properties file:

      • Set HDP_SSL_ENABLED to Yes.
      • Set HDP_HTTP_ENABLED to No.
      • Set HDP_LOAD_BALANCER_CERT_FILE to the name of the load balancer certificate file you copied to the shared directory.
      • Set HDP_NODE_CERT_FILE to the name of the wildcard node certificate file you copied to the shared directory.
      Note: These properties may also be set as environment variables in the docker run command. For example: -e "HDP_NODE_CERT_FILE=cacert.pem".

      For further details on deploying with Docker, refer to Deploying Hybrid Data Pipeline using Docker.

    • Linux installation
      Important: The server-side SSL configuration on Linux is not saved on upgrade. Therefore, after upgrading Hybrid Data Pipeline, you must rerun the enable_ssl.sh script on each server node to re-enable SSL.

      Take the following steps to enable server-side SSL for a Linux installation.

      1. Copy the load balancer certificate file and the wildcard node certificate file to the key location.
      2. For each node in the deployment, navigate to the enable SSL script: install_dir/ddcloud/enable_ssl.sh. Then, run the following command to enable SSL:
        enable_ssl.sh HDP_INTERNAL_CERT=/key-location/wildcard-node-certificate.pem

        where:

        key-location
        is the key location specified during installation of the server. Also, referred to as the shared file location.
        wildcard-node-certificate
        is the name of the wildcard node certificate file.
        Note: The full path to the wildcard node certificate file must be specified as a key-value pair with the HDP_INTERNAL_CERT property in the command.
      3. If you imported any less-well-known certificates into your JVM truststore to connect to backend data stores, you must reimport these certificates. The enable_ssl script rebuilds the truststore from the wildcard node certificate file you provide, and it does not reintegrate manually imported data store certificates. For details on importing certificates, see Importing data store SSL certificates.

Result:

Server-side SSL has been configured. Communication between the load balancer and server nodes and between individual server nodes will be encrypted. Note that running the enable_ssl.sh script disables the following ports on Linux deployments.

  • Server Access HTTP Port
  • Internal API HTTP Port
  • Notification Server non-SSL TCP Port