Cassandra beta4 changes the default token allocation
Cassandra 4.0-beta4 supplies sixteen tokens per node and enables allocation for a local replication factor of three. A new offline generator makes token planning explicit before nodes join.
Token count and token placement are separate choices in a Cassandra cluster. Cassandra 4.0-beta4 changes their packaged defaults together. Its configuration supplies sixteen tokens per node and enables the allocator for a local replication factor of three. The same preview adds an offline token generator, giving operators another way to examine an allocation before starting the nodes that will use it.
The beta4 changelog identifies the default change as CASSANDRA-13701 and the generator as CASSANDRA-16205. Beta4 is available in the Apache distribution archive, whose Debian directory is dated December 30, 2020. The changes make this preview interesting for cluster planning as well as for continued stability work.
I find Cassandra attractive when an application needs active-active operation at scale. Token allocation is part of the physical arrangement that supports that choice. A configuration should make the relationship between the number of tokens and the replication assumption visible, because those values participate in different decisions.
The shipped configuration states both assumptions
The beta4 configuration supplies the following settings.
num_tokens: 16
allocate_tokens_for_local_replication_factor: 3
The comments describe the allocator as choosing tokens to optimise replicated load over nodes in the datacenter for the specified replication factor. This is an allocation objective that accounts for replicas. It should not be reduced to selecting arbitrary positions independently for each node.
The replication-factor setting belongs to token allocation. It does not define the replication policy of every keyspace. The configuration separately offers allocation based on the replication strategy of a named keyspace. In the explicit-factor form, the number is supplied directly instead of obtained from a keyspace.
That distinction matters in a configuration review. Reading a three beside the allocator does not establish that an application has three replicas. It establishes the factor the allocator uses when selecting tokens. The keyspace replication policy remains a separate definition whose relationship to the allocation should be understood.
The comments also limit this automatic allocation option to Murmur3Partitioner. They describe expected load as approximately proportional to the number of virtual nodes. That describes the intended arrangement of token ownership. It is not a measured guarantee that every request workload produces identical CPU or disk utilisation across the cluster.
Defaults in a file and defaults when omitted differ
The same configuration comments say that leaving the token-count setting unspecified uses one token for legacy compatibility. That is a different condition from starting with the packaged configuration containing num_tokens: 16. Calling sixteen the default without naming the supplied file can obscure this distinction.
The file also describes interaction with initial_token. An explicitly supplied initial token overrides the count on the initial start. On subsequent starts, the count setting applies even when an initial token remains configured. An explanation of a new-node configuration therefore needs to distinguish initial placement from later startup behaviour.
These details are relevant to configuration management. Replacing a package does not imply that an existing deployment's configuration file becomes identical to the new example. An installation that retains an explicit token count has an explicit value to assess. A missing property and a newly supplied example are different inputs to the startup logic.
The changelog establishes that the packaged defaults changed. The configuration comments establish the conditions under which those values participate in allocation. Neither source promises that upgrading the executable automatically replans an existing cluster.
The offline tool accepts a topology
The new generator implementation requires a node count, a token count per node and a replication factor. An optional rack specification lists the number of nodes in each rack. The implementation checks that those counts add up to the total node count.
For example, the following invocation describes thirty nodes, sixteen tokens per node and three racks of ten nodes each. The replication factor supplied to the allocation is three.
tools/bin/generatetokens -n 30 -t 16 --rf 3 --racks 10,10,10
The tool prints generated tokens for each simulated node, along with its rack identifier. It defaults to Murmur3Partitioner and exposes a partitioner option. This output is a planned allocation, so the node and rack inputs are part of the result's meaning.
An invalid rack total produces an error and usage information. That validation is useful because a topology entered with inconsistent counts would not describe the intended datacenter. The tool makes that inconsistency an explicit input error instead of silently accepting two incompatible node totals.
Offline generation does not connect the simulated topology to an application's workload distribution. It supplies tokens for the topology and factor that the operator gives it. Interpreting the result still requires knowing which machines and rack arrangement those inputs represent.
I prefer having these allocation assumptions available before node startup. Beta4 provides a packaged choice for automatic allocation and a tool that prints an offline plan for explicit inputs. Its configuration makes the legacy omitted-setting behaviour visible alongside the new supplied values, so a reader can distinguish the package's recommendation from the settings an existing installation actually retains.