How to Configure NetworkTopologyStrategy for Multi-Datacenter Replication in Apache Cassandra

Use NetworkTopologyStrategy in your keyspace definition to specify independent replication factors for each data-center, ensuring rack-aware replica placement across geographic regions.

Apache Cassandra distributes data across multiple nodes using configurable replication strategies. For production deployments spanning multiple data-centers, the NetworkTopologyStrategy class provides granular control over replication factors per DC, as implemented in the apache/cassandra repository.

Understanding NetworkTopologyStrategy Configuration

Core Constructor and Validation Logic

When you create a keyspace with NetworkTopologyStrategy, the constructor at src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java (lines 81-105) receives a map of options and builds an immutable map of per-DC ReplicationFactor objects. The validateExpectedOptions method (lines 50-63) ensures at least one data-center is present and validates system keyspace requirements to guarantee all active DCs are covered.

Automatic Option Expansion

If you provide a generic replication_factor without specifying individual DCs, the static prepareOptions method (lines 315-345) automatically expands that value across all known data-centers. This preserves any existing explicit DC entries while ensuring backward compatibility.

Configuring Per-DataCenter Replication Factors

CQL Syntax for CREATE and ALTER KEYSPACE

Specify NetworkTopologyStrategy using the class parameter with data-center specific replication factors:

CREATE KEYSPACE myks
WITH REPLICATION = {
  'class' : 'NetworkTopologyStrategy',
  'DC1'   : 3,
  'DC2'   : 2,
  'DC3'   : 1
};

The same syntax applies to ALTER KEYSPACE operations. As demonstrated in test/unit/org/apache/cassandra/locator/NetworkTopologyStrategyTest.java (lines 95-100), you can programmatically create keyspaces using:

ClusterMetadataTestHelper.createKeyspace(
    "CREATE KEYSPACE ks1 WITH REPLICATION = {"
  + "   'class' : 'NetworkTopologyStrategy',"
  + "   'DC1': 3,"
  + "   'DC2': 2,"
  + "   'DC3': 1"
  + "};");

How NetworkTopologyStrategy Selects Replicas

The calculateNaturalReplicas method (lines 124-170) implements the core replica placement logic. For each token lookup, the algorithm iterates once around the token ring, maintaining a DatacenterEndpoints helper per DC. It first attempts to place replicas on distinct racks; if a data-center lacks enough racks, it tolerates rack repeats up to the acceptableRackRepeats limit. The first endpoint added becomes the primary replica, with subsequent endpoints filling the per-DC replication factor requirement.

Step-by-Step Deployment Configuration

1. Define data-center topology – Configure conf/cassandra-rackdc.properties to set dc and rack values so each node reports its location correctly.

2. Select compatible snitch – Ensure cassandra.yaml specifies an endpoint snitch compatible with NetworkTopologyStrategy, such as GossipingPropertyFileSnitch.

3. Create the keyspace – Execute CREATE KEYSPACE with the NetworkTopologyStrategy class and explicit per-DC replication factors.

4. Verify configuration – Query system_schema.keyspaces or run nodetool describecluster to confirm replication options are stored correctly in org.apache.cassandra.schema.KeyspaceMetadata.

5. Monitor warnings – The maybeWarnOnOptions method (lines 85-102) emits warnings when configured replication factors exceed the number of live nodes in a data-center.

Validation and Safety Mechanisms

The validateExpectedOptions method enforces that at least one data-center is present in the configuration and performs additional validation for system keyspaces. When replication factors exceed available nodes, maybeWarnOnOptions generates alerts through the Cassandra logging system and ClientWarn mechanism, helping operators identify potentially unsafe configurations before they impact availability.

Summary

• NetworkTopologyStrategy enables independent replication factors per data-center through a simple map configuration in CQL.
• The constructor at NetworkTopologyStrategy.java (lines 81-105) validates and builds immutable per-DC ReplicationFactor objects.
• Use prepareOptions (lines 315-345) to automatically apply a default replication factor across all DCs when individual mappings are not specified.
• The replica selection algorithm in calculateNaturalReplicas (lines 124-170) ensures rack diversity while respecting per-DC counts and tolerating rack repeats when necessary.
• Validation methods prevent misconfigurations and warn when replication factors exceed available nodes in any data-center.

Frequently Asked Questions

What happens if I set a replication factor higher than the number of nodes in a data-center?

The maybeWarnOnOptions method detects this condition and emits a warning through the Cassandra logging system and ClientWarn mechanism. While the configuration is accepted, you will see alerts indicating that the replication factor exceeds the available node count in that specific data-center, which could impact write consistency and fault tolerance.

Can I change replication factors after creating a keyspace?

Yes, use ALTER KEYSPACE with the same NetworkTopologyStrategy syntax. The prepareOptions helper processes the new map and can automatically expand a generic replication_factor value across all current data-centers while preserving existing explicit DC entries, making it easy to adjust replication as your cluster grows.

Which snitch should I use with NetworkTopologyStrategy?

You must use a snitch that exposes data-center and rack information, such as GossipingPropertyFileSnitch or PropertyFileSnitch. These read from conf/cassandra-rackdc.properties to provide the topology awareness required by NetworkTopologyStrategy's replica placement algorithm in calculateNaturalReplicas.

How does Cassandra handle rack awareness when selecting replicas?

The calculateNaturalReplicas method prioritizes distinct racks within each data-center to maximize fault isolation. If the replication factor exceeds the number of available racks, the algorithm permits rack repeats up to the acceptableRackRepeats threshold, ensuring the requested replication factor is met while maintaining the best possible distribution across failure domains.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}