Configure Transport Layer Security (TLS)

ZDM Proxy supports proxy-to-cluster and application-to-proxy TLS encryption.

The TLS configuration is an optional part of the initial ZDM Proxy configuration. See the information here in this topic, and then refer to the ZDM Proxy Automation topics that cover:

Introduction

  • All TLS configuration is optional. Enable TLS between the ZDM Proxy and any cluster that requires it, and/or between your client application and the ZDM Proxy if required.

  • Proxy-to-cluster TLS can be configured between the ZDM Proxy and either or both the origin and target clusters, as desired. Each set of configurations is independent of the other. When using proxy-to-cluster TLS, the ZDM Proxy acts as the TLS client and the cluster as the TLS server. One-way TLS and Mutual TLS are both supported and can be enabled depending on each cluster’s requirements.

  • When using application-to-proxy TLS, your client application is the TLS client and the ZDM Proxy is the TLS server. One-way TLS and Mutual TLS are both supported.

  • When the ZDM Proxy connects to Astra DB, it always implicitly uses Mutual TLS. This is done through the Secure Connect Bundle (SCB) and does not require any extra configuration.

Retrieving files from a JKS keystore

If you are already using TLS between your client application and the origin cluster, then the files needed to configure TLS will already be used in the client application’s configuration (TLS client files) and the origin’s configuration (TLS Server files). In some cases, these files may be contained in a JKS keystore.

The ZDM Proxy does not accept a JKS keystore, requiring the raw files instead.

To view the files contained in a JKS keystore and their aliases:

keytool -list -keystore <path_to_keystore.jks>

To extract a file from a JKS keystore:

keytool -exportcert -keystore <path_to_jks_store> -alias <file_alias> -file <path_to_destination_file> -rfc

The -rfc option extracts the files in non-binary PEM format.

For more details, see the keytool syntax documentation.

Proxy to self-managed cluster TLS

Here’s how to configure TLS between the ZDM Proxy and a self-managed cluster (Apache Cassandra or DSE). In this case the ZDM Proxy acts as the TLS client and the cluster acts as the TLS server.

The files required to configure proxy-to-cluster TLS are:

  • Server CA: needed for one-way and Mutual TLS

  • Client certificate: only needed for Mutual TLS

  • Client key: only needed for Mutual TLS

If your origin cluster requires TLS, your client application will already be using these files in its configuration to connect to it.

All files must be in plain-text, non-binary format.

Prepare the TLS files and copy them to the Ansible Control Host container

For each self-managed origin or target cluster that requires TLS, do the following:

  1. If your TLS files are in a JKS keystore, extract them as plain text (see Retrieving files from a JKS keystore).

  2. Upload the following files to the jumphost:

    • For one-way TLS, uploda only the server CA.

    • For Mutual TLS, upload the server CA, the client cert, and the client key.

  3. From a shell on the jumphost, copy the files to the relevant TLS directory into the Ansible Control Host container:

    • For origin clusters, run: docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/origin_tls_files

    • For target clusters, run: docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/target_tls_files

Configure TLS

There are separate TLS configuration variables for origin and target clusters so that you can configure these independently, if needed.

  1. Open a shell to the container:

    docker exec -it zdm-ansible-container bash

  2. Find the custom TLS configuration file at zdm-proxy-automation/ansible/vars/zdm_proxy_custom_tls_config.yml.

  3. Uncomment and set the following variables in the custom TLS configuration file for the proxy-to-origin TLS configuration:

    • origin_tls_user_dir_path: uncomment and leave to its preset value of /home/ubuntu/origin_tls_files.

    • origin_tls_server_ca_filename: filename (without path) of the Server CA.

    • origin_tls_client_cert_filename: filename (without path) of the Client cert. This is for Mutual TLS only, leave unset otherwise.

    • origin_tls_client_key_filename: filename (without path) of the Client key. For Mutual TLS only, leave unset otherwise.

  4. Uncomment and set the variables for the proxy-to-target TLS configuration:

    • target_tls_user_dir_path: uncomment and leave to its preset value of /home/ubuntu/target_tls_files.

    • target_tls_server_ca_filename: filename (without path) of the Server CA.

    • target_tls_client_cert_filename: filename (without path) of the Client cert. This is for Mutual TLS only, leave unset otherwise.

    • target_tls_client_key_filename: filename (without path) of the Client key. For Mutual TLS only, leave unset otherwise.

Application-to-proxy TLS

Here are the steps to enable TLS between your client application and the ZDM Proxy if required. In this case, your client application is the TLS client and the ZDM Proxy is the TLS server.

The files required by the proxy to configure application-to-proxy TLS are:

  • Server CA

  • Server certificate

  • Server key

All these files are required for one-way and Mutual TLS.

If your origin cluster currently requires TLS, it will already be using these files for its own TLS configuration.

All files must be in plain-text, non-binary format.

Here are the steps to configure application-to-proxy TLS:

  • If your TLS files are in a JKS keystore, extract them as plain text (see Retrieving files from a JKS keystore).

  • Upload the required files to the jumphost: Server CA, Server certificate and Server key.

  • From a shell on the jumphost, copy the files to the zdm_proxy_tls_files TLS directory into the Ansible Control Host container: docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/zdm_proxy_tls_files.

  • Ensure that you have a shell open to the container. If you do not, you can open it with docker exec -it zdm-ansible-container bash.

  • From this shell, edit the file zdm-proxy-automation/ansible/vars/zdm_proxy_custom_tls_config.yml, uncommenting and populating the relevant configuration variables. These are in the bottom section of vars/proxy_custom_tls_config_input.yml and are all prefixed with zdm_proxy:

    • zdm_proxy_tls_user_dir_path_name: uncomment and leave to its preset value of /home/ubuntu/zdm_proxy_tls_files.

    • zdm_proxy_tls_server_ca_filename: filename (without path) of the server CA that the proxy must use. Always required.

    • zdm_proxy_tls_server_cert_filename and zdm_proxy_tls_server_key_filename : filenames (without path) of the server certificate and server key that the proxy must use. Both always required.

    • zdm_proxy_tls_require_client_auth: whether you want to enable Mutual TLS between the application and the proxy. Optional: defaults to false ( = one-way TLS ), can be set to true to enable Mutual TLS.

Remember that in this case, the ZDM Proxy is the TLS server; thus the word server in these variable names.

Apply the configuration

This is all that is needed at this point. As part of its normal execution, the proxy deployment playbook will automatically distribute all TLS files and apply the TLS configuration to all ZDM Proxy instances.

Just go back to Optional advanced configuration to finalize the ZDM Proxy configuration and then execute the deployment playbook.

Was this helpful?

Edit this page

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com