• Glossary
  • Support
  • Downloads
  • DataStax Home
Get Live Help
Expand All
Collapse All

DataStax Astra DB Serverless Documentation

    • Overview
      • Release notes
      • Astra DB FAQs
      • Astra DB glossary
      • Get support
    • Getting Started
      • Grant a user access
      • Load and retrieve data
        • Use DSBulk to load data
        • Use Data Loader in Astra Portal
      • Connect a driver
      • Build sample apps
      • Use integrations
    • Planning
      • Plan options
      • Database regions
    • Securing
      • Security highlights
      • Security guidelines
      • Default user permissions
      • Change your password
      • Reset your password
      • Authentication and Authorization
      • Astra DB Plugin for HashiCorp Vault
    • Connecting
      • Connecting private endpoints
        • AWS Private Link
        • Azure Private Link
        • GCP Private Endpoints
        • Connecting custom DNS
      • Connecting Change Data Capture (CDC)
      • Connecting CQL console
      • Connect the Spark Cassandra Connector to Astra
      • Drivers for Astra DB
        • Connecting C++ driver
        • Connecting C# driver
        • Connecting Java driver
        • Connecting Node.js driver
        • Connecting Python driver
        • Drivers retry policies
      • Connecting Legacy drivers
      • Get Secure Connect Bundle
    • Migrating
      • Components
      • FAQs
      • Preliminary steps
        • Feasibility checks
        • Deployment and infrastructure considerations
        • Create target environment for migration
        • Understand rollback options
      • Phase 1: Deploy ZDM Proxy and connect client applications
        • Set up the ZDM Proxy Automation with ZDM Utility
        • Deploy the ZDM Proxy and monitoring
        • Configure Transport Layer Security
        • Connect client applications to ZDM Proxy
        • Leverage metrics provided by ZDM Proxy
        • Manage your ZDM Proxy instances
      • Phase 2: Migrate and validate data
      • Phase 3: Enable asynchronous dual reads
      • Phase 4: Change read routing to Target
      • Phase 5: Connect client applications directly to Target
      • Troubleshooting
        • Troubleshooting tips
        • Troubleshooting scenarios
      • Glossary
      • Contribution guidelines
      • Release Notes
    • Managing
      • Managing your organization
        • User permissions
        • Pricing and billing
        • Audit Logs
        • Bring Your Own Key
          • BYOK AWS Astra DB console
          • BYOK GCP Astra DB console
          • BYOK AWS DevOps API
          • BYOK GCP DevOps API
        • Configuring SSO
          • Configure SSO for Microsoft Azure AD
          • Configure SSO for Okta
          • Configure SSO for OneLogin
      • Managing your database
        • Create your database
        • View your databases
        • Database statuses
        • Use DSBulk to load data
        • Use Data Loader in Astra Portal
        • Monitor your databases
        • Export metrics to third party
          • Export metrics via Astra Portal
          • Export metrics via DevOps API
        • Manage access lists
        • Manage multiple keyspaces
        • Using multiple regions
        • Terminate your database
      • Managing with DevOps API
        • Managing database lifecycle
        • Managing roles
        • Managing users
        • Managing tokens
        • Managing BYOK AWS
        • Managing BYOK GCP
        • Managing access list
        • Managing multiple regions
        • Get private endpoints
        • AWS PrivateLink
        • Azure PrivateLink
        • GCP Private Service
    • Astra CLI
    • Astra Block
      • Quickstart
      • FAQ
      • Data model
      • About NFTs
    • Developing with Stargate APIs
      • Develop with REST
      • Develop with Document
      • Develop with GraphQL
        • Develop with GraphQL (CQL-first)
        • Develop with GraphQL (Schema-first)
      • Develop with gRPC
        • gRPC Rust client
        • gRPC Go client
        • gRPC Node.js client
        • gRPC Java client
      • Develop with CQL
      • Tooling Resources
      • Node.js Document API client
      • Node.js REST API client
    • Stargate QuickStarts
      • Document API QuickStart
      • REST API QuickStart
      • GraphQL API CQL-first QuickStart
    • API References
      • DevOps REST API v2
      • Stargate Document API v2
      • Stargate REST API v2
  • DataStax Astra DB Serverless Documentation
  • Migrating
  • Phase 1: Deploy ZDM Proxy and connect client applications
  • Configure Transport Layer Security

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:

  • Set up the ZDM Proxy Automation with ZDM Utility

  • Deploy the ZDM Proxy and monitoring

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 Origin/Target (either or both) 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 clusters, 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 Origin, the files needed to configure TLS will already be used in the client application’s configuration (TLS client files) and 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

Please note the -rfc option, which 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 (non-Astra DB) cluster. 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 cluster requiring TLS (Origin and/or Target), execute the following steps:

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

  • Upload the following files to the jumphost:

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

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

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

    • For Origin: docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/origin_tls_files

    • For Target: docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/target_tls_files

There is a set of TLS configuration variables for Origin and a separate set for Target, so that they can be configured independently as desired.

Configure TLS

Here is how to do it:

  • 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, uncomment the relevant variables and edit their values in the configuration file zdm-proxy-automation/ansible/vars/zdm_proxy_custom_tls_config.yml as follows.

    • For 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.

    • The configuration for proxy-to-Target TLS is done in the same way but using the Target-specific configuration variables (target_tls_*).

Application-to-proxy TLS

Here are the steps to enable TLS between your client application and the ZDM Proxy if required. Please bear in mind that 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.

Deploy the ZDM Proxy and monitoring Connect client applications to ZDM Proxy

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

© DataStax | Privacy policy | Terms of use

DataStax, Titan, and TitanDB are registered trademarks of DataStax, Inc. and its subsidiaries in the United States and/or other countries.

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.

landing_page landingpage