Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu

Caution

You're viewing documentation for a previous version of Scylla Java Driver. Switch to the latest stable version.

Scylla Java Driver Manual Core driver Address resolution

Address resolution¶

Quick overview¶

The driver uses system.peers.rpc-address to connect to newly discovered nodes. For special network topologies, an address translation component can be plugged in.

  • advanced.address-translator in the configuration.

  • none by default. Also available: EC2-specific (for deployments that span multiple regions), or write your own.


Each node in the Cassandra cluster is uniquely identified by an IP address that the driver will use to establish connections.

  • for contact points, these are provided as part of configuring the CqlSession object;

  • for other nodes, addresses will be discovered dynamically, either by inspecting system.peers on already connected nodes, or via push notifications received on the control connection when new nodes are discovered by gossip.

Cassandra-side configuration¶

The address that each Cassandra node shares with clients is the broadcast RPC address; it is controlled by various properties in cassandra.yaml:

  • rpc_address or rpc_interface is the address that the Cassandra process binds to. You must set one or the other, not both (for more details, see the inline comments in the default cassandra.yaml that came with your installation);

  • broadcast_rpc_address (introduced in Cassandra 2.1) is the address to share with clients, if it is different than the previous one (the reason for having a separate property is if the bind address is not public to clients, because there is a router in between).

If broadcast_rpc_address is not set, it defaults to rpc_address/rpc_interface. If rpc_address/rpc_interface is 0.0.0.0 (all interfaces), then broadcast_rpc_address must be set.

If you’re not sure which address a Cassandra node is broadcasting, launch cqlsh locally on the node, execute the following query and take node of the result:

cqlsh> select broadcast_address from system.local;

 broadcast_address
-------------------
         172.1.2.3

Then connect to another node in the cluster and run the following query, injecting the previous result:

cqlsh> select rpc_address from system.peers where peer = '172.1.2.3';

 rpc_address
-------------
     1.2.3.4

That last result is the broadcast RPC address. Ensure that it is accessible from the client machine where the driver will run.

Driver-side address translation¶

Sometimes it’s not possible for Cassandra nodes to broadcast addresses that will work for each and every client; for instance, they might broadcast private IPs because most clients are in the same network, but a particular client could be on another network and go through a router.

For such cases, you can register a driver-side component that will perform additional address translation. Write a class that implements AddressTranslator with the following constructor:

public class MyAddressTranslator implements AddressTranslator {

  public PassThroughAddressTranslator(DriverContext context, DriverOption configRoot) {
    // retrieve any required dependency or extra configuration option, otherwise can stay empty
  }

  @Override
  public InetSocketAddress translate(InetSocketAddress address) {
    // your custom translation logic
  }

  @Override
  public void close() {
    // free any resources if needed, otherwise can stay empty
  }
}

Then reference this class from the configuration:

datastax-java-driver.advanced.address-translator.class = com.mycompany.MyAddressTranslator

Note: the contact points provided while creating the CqlSession are not translated, only addresses retrieved from or sent by Cassandra nodes are.

EC2 multi-region¶

If you deploy both Cassandra and client applications on Amazon EC2, and your cluster spans multiple regions, you’ll have to configure your Cassandra nodes to broadcast public RPC addresses.

However, this is not always the most cost-effective: if a client and a node are in the same region, it would be cheaper to connect over the private IP. Ideally, you’d want to pick the best address in each case.

The driver provides Ec2MultiRegionAddressTranslator which does exactly that. To use it, specify the following in the configuration:

datastax-java-driver.advanced.address-translator.class = Ec2MultiRegionAddressTranslator

With this configuration, you keep broadcasting public RPC addresses. But each time the driver connects to a new Cassandra node:

  • if the node is in the same EC2 region, the public IP will be translated to the intra-region private IP;

  • otherwise, it will not be translated.

(To achieve this, Ec2MultiRegionAddressTranslator performs a reverse DNS lookup of the origin address, to find the domain name of the target instance. Then it performs a forward DNS lookup of the domain name; the EC2 DNS does the private/public switch automatically based on location).

PREVIOUS
Core driver
NEXT
Asynchronous programming
  • 4.12.0.x
    • 4.13.0.x
    • 4.12.0.x
    • 4.11.1.x
    • 4.10.0.x
    • 4.7.2.x
    • 3.11.2.x
    • 3.11.0.x
    • 3.10.2.x
    • 3.7.2.x
  • Java Driver for Scylla and Apache Cassandra®
  • API Documentation
  • Manual
    • API conventions
    • Case sensitivity
    • Core driver
      • Address resolution
      • Asynchronous programming
      • Authentication
      • Bill of Materials (BOM)
      • Compression
      • Configuration
        • Reference configuration
      • Control connection
      • Custom codecs
      • Detachable types
      • Query idempotence
      • Integration
      • Load balancing
      • Logging
      • Metadata
        • Node metadata
        • Schema metadata
        • Token metadata
      • Metrics
      • Native protocol
      • Non-blocking programming
      • Paging
      • Performance
      • Connection pooling
      • Query timestamps
      • Reactive Style Programming
      • Reconnection
      • Request tracker
      • Retries
      • Using the shaded JAR
      • Speculative query execution
      • SSL
      • Statements
        • Batch statements
        • Per-query keyspace
        • Prepared statements
        • Simple statements
      • Temporal types
      • Request throttling
      • Query tracing
      • Tuples
      • User-defined types
    • Developer docs
      • Administrative tasks
      • Common infrastructure
        • Concurrency
        • Driver context
        • Event bus
      • Native protocol layer
      • Netty pipeline
      • Request execution
    • Mapper
      • Integration
        • Kotlin
        • Lombok
        • Java 14 Records
        • Scala
      • DAOs
        • Custom result types
        • Delete methods
        • GetEntity methods
        • Increment methods
        • Insert methods
        • Null saving strategy
        • Query methods
        • Query provider methods
        • Select methods
        • SetEntity methods
        • Statement attributes
        • Update methods
      • Entities
      • Mapper interface
    • OSGi
    • Query builder
      • Conditions
      • DELETE
      • Idempotence in the query builder
      • INSERT
      • Relations
      • Schema builder
        • Aggregate
        • Function
        • Index
        • Keyspace
        • Materialized View
        • Table
        • Type
      • SELECT
      • Terms
      • TRUNCATE
      • UPDATE
  • Upgrade guide
  • Frequently asked questions
  • Changelog
  • Create an issue
  • Edit this page

On this page

  • Address resolution
    • Quick overview
    • Cassandra-side configuration
    • Driver-side address translation
    • EC2 multi-region
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 25 May 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2