Cassandra Adding Nodes

One of Cassandra's strongest features is the ability to add nodes to a running cluster without taking any downtime. Reads and writes continue normally while the new node joins and streams data from existing nodes. This live expansion is what makes Cassandra the right choice for applications that need to scale smoothly as traffic grows.

When to Add a Node

Signal                                Action
──────────────────────────────────────────────────────────────
Disk usage exceeds 60–70% per node    Add nodes before disks fill
Read/write latency trending up        Add nodes to reduce per-node load
CPU usage consistently above 70%      Add nodes to share the work
Preparing for a known traffic spike   Add nodes proactively
nodetool status shows load imbalance  Add and rebalance

Pre-requisites Before Adding a Node

Before starting a new node, confirm the following on the new machine.

✓ Java is installed (same version as cluster)
✓ Cassandra is installed (same version as cluster)
✓ cassandra.yaml is configured with:
    cluster_name — must match the existing cluster name
    seeds        — list at least one running node's IP
    listen_address — this node's own IP
    rpc_address    — this node's own IP (or 0.0.0.0)
✓ Firewall allows ports 7000 (inter-node) and 9042 (CQL)
✓ NTP is running (clock skew causes issues in Cassandra)

cassandra.yaml Configuration for the New Node

cluster_name: 'ProductionCluster'

seed_provider:
  - class_name: org.apache.cassandra.locator.SimpleSeedProvider
    parameters:
      - seeds: "10.0.0.1,10.0.0.2"  # existing stable nodes

listen_address: 10.0.0.5   # new node's IP
rpc_address: 10.0.0.5
native_transport_port: 9042

num_tokens: 256
endpoint_snitch: GossipingPropertyFileSnitch

Starting the New Node

sudo systemctl start cassandra

Cassandra starts and automatically contacts the seed nodes. It bootstraps by announcing its token ranges to the cluster through gossip, then begins streaming the data it is now responsible for from existing nodes.

Monitoring the Bootstrap Process

# Check node status (new node appears as UJ = Up Joining):
nodetool status

--  Address    ...  Tokens  Owns     Status
UN  10.0.0.1   ...  256     20.0%    Normal
UN  10.0.0.2   ...  256     20.1%    Normal
UN  10.0.0.3   ...  256     19.9%    Normal
UN  10.0.0.4   ...  256     20.0%    Normal
UJ  10.0.0.5   ...  256     0.0%     Joining

# Watch bootstrap streaming progress:
nodetool netstats

When bootstrapping completes, the new node's status changes from UJ (Up Joining) to UN (Up Normal) and its Owns percentage rises to approximately 1/N of the cluster.

Post-Bootstrap: Run Cleanup

After the new node finishes bootstrapping, run cleanup on all existing nodes. Cleanup removes data from existing nodes that now belongs to the new node — freeing disk space.

# Run on each existing node (not the new one):
nodetool cleanup

Run cleanup one node at a time to avoid overloading the cluster. Do not skip this step — without cleanup, existing nodes continue to store data that the new node already holds, wasting disk space.

Adding a Node to a New Data Center

To expand into a new geographic region, add nodes configured with a different dc value in cassandra-rackdc.properties. Then alter the keyspace to include the new data center in its replication settings.

# cassandra-rackdc.properties on new DC nodes:
dc=eu-west
rack=rack1

# After nodes bootstrap, alter the keyspace:
ALTER KEYSPACE ecommerce
  WITH replication = {
    'class': 'NetworkTopologyStrategy',
    'us_east': 3,
    'eu_west': 3     -- add new DC
  };

# Run rebuild on each new DC node to pull data:
nodetool rebuild -- us_east

Replacing a Dead Node

If a node fails permanently, replace it with a new node at the same IP address, or use the replace_address option to bring up a replacement at a different IP.

# Start replacement node with replace_address JVM option:
JVM_OPTS="$JVM_OPTS -Dcassandra.replace_address=10.0.0.3"
sudo systemctl start cassandra

Summary

Adding a node to Cassandra requires installing Cassandra on the new machine, configuring cassandra.yaml with the correct cluster name and seeds, and starting the Cassandra service. The new node bootstraps automatically by streaming data from existing nodes. After bootstrapping completes, run nodetool cleanup on existing nodes to reclaim disk space. Adding nodes is a zero-downtime operation — the cluster continues serving traffic throughout the entire process.