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 resolved afresh each time the control connection falls back to it, and the driver will try several of the addresses it resolves to – see contact points given as hostnames.

Connecting¶

There is nothing connectivity-specific to configure. Give the session the contact points from your cluster’s connect page, name the local datacenter, and add 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))
    .withLocalDatacenter("AWS_EU_WEST_1")
    .withAuthCredentials("scylla", "...")
    .build();

createUnresolved is what keeps the contact point a name. new InetSocketAddress(host, port) resolves on construction, so the session is frozen to the one address that lookup returned, and a hostname that later points somewhere else is never followed – see contact points given as hostnames.

Port 9142 is the TLS port; 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: 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

Then point the engine factory at that truststore:

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

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, a proxy per subnet, 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;