VPC peering, Transit Gateway and direct connections¶

Quick overview¶

The common case: every node is reachable at the address it broadcasts, so the driver needs no address translation at all.

• contact points and withLocalDatacenter are the whole of the connectivity configuration.

• covers VPC peering, AWS Transit Gateway and direct connections over the public internet.

• leave advanced.address-translator unset – see when the broadcast addresses are not reachable if the nodes are not reachable at their broadcast addresses.

ScyllaDB Cloud offers three ways to put your application on a network that can route to the cluster. They differ in how the packets travel, not in what the driver does: in all three the node addresses in system.peers are addresses your application can open a socket to, which is what the driver assumes by default.

Setting any of them up is a cluster-side operation, documented under Network Access Options in the ScyllaDB Cloud manual. This page covers only what it means for the driver.

VPC peering¶

A private link between your VPC and the cluster’s VPC, within one cloud provider. Traffic never leaves the provider’s network. Available on AWS and GCP.

Two constraints are worth knowing before you plan an application around it: peering has to be enabled when the cluster is created and cannot be added afterwards, and your VPC’s CIDR must not overlap the cluster’s.

AWS Transit Gateway¶

A TGW VPC attachment connects a cluster datacenter to a Transit Gateway in your AWS account, so several VPCs or accounts reach one cluster through a single hub. Choose it over peering when more than one VPC needs the cluster, or when your topology already has a Transit Gateway.

Direct connection over the public internet¶

Clusters are reachable on the public internet by default, with access limited to the addresses on the cluster’s allowlist. It needs no network setup, which makes it the right choice for local development and for evaluating a trial cluster, and the wrong one for production traffic.

Two things matter more here than on a private network: configure SSL, and remember that ScyllaDB Cloud hands you node hostnames rather than addresses. A hostname contact point is looked up when the session first connects to it, and only the first address the lookup returns is tried, so give the session every hostname from the connect page rather than just one.

Connecting¶

There is nothing connectivity-specific to configure, but the session must use TLS: port 9142 is the TLS port, and 9042 stays open for unencrypted traffic unless the cluster enforces encryption. The cluster certificate is signed by a per-cluster CA, not a public one, so first download it from the cluster’s details page (”Download CA public key”) and import it into a truststore:

keytool -import -v -trustcacerts -alias CARoot -file scylladb_cluster_ca.pem \
    -keystore client.truststore -storepass password123

Choose your own store password; the driver needs the same one to open the truststore. Then give the session the contact points from your cluster’s connect page, the truststore, the local datacenter and your credentials:

CqlSession session = CqlSession.builder()
    .addContactPoint(InetSocketAddress.createUnresolved(
        "node-0.aws-eu-west-1.example.clusters.scylla.cloud", 9142))
    .addContactPoint(InetSocketAddress.createUnresolved(
        "node-1.aws-eu-west-1.example.clusters.scylla.cloud", 9142))
    .addContactPoint(InetSocketAddress.createUnresolved(
        "node-2.aws-eu-west-1.example.clusters.scylla.cloud", 9142))
    .withConfigLoader(DriverConfigLoader.programmaticBuilder()
        .withString(DefaultDriverOption.SSL_ENGINE_FACTORY_CLASS, "DefaultSslEngineFactory")
        .withString(DefaultDriverOption.SSL_TRUSTSTORE_PATH, "/path/to/client.truststore")
        .withString(DefaultDriverOption.SSL_TRUSTSTORE_PASSWORD, "password123")
        .build())
    .withLocalDatacenter("AWS_EU_WEST_1")
    .withAuthCredentials("scylla", "...")
    .build();

The same TLS settings can live in application.conf instead of code:

datastax-java-driver.advanced.ssl-engine-factory {
  class = DefaultSslEngineFactory
  truststore-path = /path/to/client.truststore
  truststore-password = password123
}

createUnresolved defers the hostname lookup until the session connects; new InetSocketAddress(host, port) does it on construction, so the contact point is fixed to whatever that one lookup returned. Either way the name matters only at startup: the driver soon reaches each node at the address the cluster reports for it, so a DNS change after startup is not followed.

SSL covers truststores, hostname validation and client certificates.

The datacenter name has to match the cluster’s exactly; it is shown on the cluster page. Getting it wrong does not fail the build: the driver logs Configured local DC '...' does not match any node's datacenter, carries on, and then has no node it is willing to route to, so every request fails with NoNodeAvailableException. See load balancing for what the local datacenter controls.

When the broadcast addresses are not reachable¶

If connections to the contact points succeed but every other node is unreachable, the cluster is broadcasting addresses your network cannot route to. That is a different deployment shape, and the driver has two answers for it:

• the cluster is behind a cloud private endpoint and publishes a per-node endpoint mapping – AWS PrivateLink, Azure Private Link or GCP Private Service Connect: use client routes;

• everything else – one proxy hostname for the whole cluster, or EC2 multi-region: use an address translator.

Two queries separate the two. The first shows the addresses the driver is being handed, and needs both halves because system.peers never lists the node you are connected to:

cqlsh> select peer, rpc_address from system.peers;
cqlsh> select rpc_address from system.local;

The second decides which answer applies – a row per node means the cluster publishes the mapping client routes reads, and a missing table means it does not:

cqlsh> select * from system.client_routes;