ScyllaDB Docs ScyllaDB Operator Reference nodetool alternatives

nodetool alternatives¶

This page is for ScyllaDB administrators transitioning to Kubernetes. It explains why direct nodetool operations that change cluster state must not be used with the Operator, and what to do instead.

Note

ScyllaDB’s nodetool is a distinct implementation from Apache Cassandra’s — it communicates with ScyllaDB via the REST API (not JMX), though many command names are the same.

Why this matters¶

The Operator reconciles cluster state continuously. Any out-of-band change to cluster membership or topology creates a mismatch between the Operator’s expected state and reality, leading to stuck rollouts, failed replacements, or data loss.

Read-only commands are always safe¶

If a nodetool command is read-only, it is always safe to use via kubectl exec. Examples:

status, gossipinfo, info, ring, cfstats / tablestats, compactionstats, toppartitions

kubectl exec -it <pod-name> -c scylla -- nodetool status

State-changing commands¶

If a command changes cluster state, consult the table below.

High risk — use Operator alternatives¶

Warning

These operations are irreversible and may cause data loss or cluster instability if performed on an unhealthy cluster. Back up your data before proceeding.

These commands change cluster membership or topology. Using them directly will desync the Operator’s state.

Command	Risk	Operator alternative
`decommission`	Desyncs StatefulSet replica count and Operator tracking labels. Operator will not know the node was decommissioned.	Scale down the rack’s `members` count by 1. The Operator labels the service, the sidecar calls decommission, and the StatefulSet scales down after completion. See Scale, add, remove racks.
`removenode`	Removes a node from the ring without Operator knowledge. Operator expects to manage membership via scale-down or replace.	Use the `scylla/replace` label on the member Service to trigger Operator-managed replacement. For dead nodes, see Recover from failed replace.
`move`	Changes token ownership without Operator awareness.	Not supported. Use scaling (add/remove nodes) to rebalance.
`rebuild`	Streams data from another datacenter; Operator does not track rebuild state. Running during an Operator-managed operation can cause conflicts.	No Operator alternative. If rebuild is needed (for example, adding a new DC), coordinate manually — ensure no other operations are in progress.
`disablebinary` / `enablebinary`	Disabling native transport makes the node unreachable to clients and may cause readiness probe failures, triggering Operator recovery actions.	Do not use. If you need to stop traffic to a node, use maintenance mode.
`disablegossip` / `enablegossip`	Disabling gossip effectively marks the node as down in the cluster, confusing the Operator’s health checks and potentially triggering unwanted recovery.	Do not use.

Medium risk — automatic or use with caution¶

Caution

Run these operations only on a healthy cluster. Monitor cluster health during execution.

Command	Risk	Operator alternative
`drain`	Puts node in DRAINED state; sidecar may restart ScyllaDB if a decommission is pending.	Automatic — drain runs as a `preStop` lifecycle hook before every pod shutdown. No manual invocation needed.
`disableautocompaction` / `enableautocompaction`	Ephemeral change, but disabling auto-compaction can cause unbounded SSTable growth if forgotten. Operator does not track this state.	No Operator alternative. Use with caution and re-enable promptly.
`stop` (compaction)	Stops in-progress compaction. Safe but may need to be repeated if compaction restarts.	No Operator alternative. Use with caution.

Low risk — safe to use¶

These commands are safe to use directly. The Operator either handles them automatically or does not conflict with them.

Command	Notes	Operator alternative
`repair`	Safe to run manually but redundant.	Configure repair tasks via ScyllaDB Manager (managed through the ScyllaCluster spec). Manager handles scheduling and distributed coordination.
`cleanup`	Safe and idempotent, but the Operator runs cleanup automatically when it detects token ring changes.	Automatic — the Operator tracks token ring hash changes per service and spawns cleanup Jobs when they diverge. Manual cleanup is only needed after replication factor changes (which the Operator does not detect).
`snapshot` / `clearsnapshot`	Safe to use.	No Operator alternative; for scheduled backups, use ScyllaDB Manager backup tasks.
`compact`	Safe to trigger manually.	No Operator alternative; manual compaction is acceptable.
`flush`	Safe to trigger manually.	No Operator alternative; flushing memtables is acceptable.
`scrub`	Safe to trigger manually.	No Operator alternative; manual scrub is acceptable.
`setlogginglevel`	Ephemeral change, lost on pod restart. Safe for live debugging.	Preferred method for emergency log-level changes when a rolling restart is not possible. See Change log level. For persistent changes, use the ScyllaCluster spec — see Pass ScyllaDB arguments.
`refresh`	Loads SSTables placed on disk; does not affect cluster membership.	No Operator alternative; safe to use.
`upgradesstables`	Rewrites SSTables to the latest format; safe but resource-intensive.	No Operator alternative; safe to use, typically needed after a ScyllaDB version upgrade.
`setcompactionthroughput` / `setstreamthroughput`	Ephemeral tuning changes, lost on restart.	No Operator alternative; safe to use for temporary tuning. For persistent changes, configure via the ScyllaCluster spec.
`settraceprobability`	Ephemeral diagnostic setting.	No Operator alternative; safe to use for debugging.

Was this page helpful?

nodetool alternatives¶

Why this matters¶

Read-only commands are always safe¶

State-changing commands¶

High risk — use Operator alternatives¶

Medium risk — automatic or use with caution¶

Low risk — safe to use¶

Related pages¶