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 contact point added with createUnresolved is looked up again every time the driver 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. The example below connects to 9142, the TLS port, so it also configures TLS; on VPC peering or Transit Gateway, 9042 accepts unencrypted connections 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. Keep it in single quotes on the command line, and in double quotes in application.conf, where an unquoted # starts a comment. 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();

createUnresolved is what keeps the contact point a name: the driver looks it up again every time it connects to that node, so a hostname that later points somewhere else is followed. new InetSocketAddress(host, port) resolves on construction, so the contact point is fixed to whatever that one lookup returned. Contact points given in the configuration are resolved once, when the session is built, and every address a name returns becomes a contact point, unless advanced.resolve-contact-points is false, which keeps them names – see the reference configuration.

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"
}

In 4.18.1, a session with a truststore but no keystore logs an Error while closing warning for its JdkSslHandlerFactory, with a NullPointerException, when it closes. The warning is harmless, and driver 4.19.0 no longer logs it.

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 You specified ... as the local DC, but some contact points are from a different DC, 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:

• 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: that needs client routes, which this version does not have;

• everything else – one proxy hostname for the whole cluster, or EC2 multi-region: use an address translator that gives each node its own address and port.

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;

rpc_address is the one clients connect to; peer is the address the nodes use among themselves.

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;