This message was deleted.
# questions-and-troubleshooting
s
This message was deleted.
r
The plan is fundamentally sound, but there are some critical risks and best practices you should consider to ensure zero downtime and data safety during the transition. 1. Decommissioning (Nodes 12 $\rightarrow$ 8) Using
ALTER SYSTEM DECOMMISSION BACKEND
is the correct approach as it triggers an asynchronous migration of all tablets to the remaining nodes. * Concurrency Warning: StarRocks documentation generally recommends decommissioning nodes in small batches (no more than 2 at a time) to avoid overwhelming the remaining nodes with migration traffic and to maintain query performance. For 4 nodes, I recommend decommissioning 2, waiting for them to finish, and then decommissioning the next 2. * Check Replicas: Ensure that your data's
replication_num
(default is 3) is less than the remaining 8 nodes. If you have any tables with a high replication factor (e.g., 8+), decommissioning will hang or fail. * Check for Single-Replica Tables: If any tables have a
replication_num
of 1, the decommission process may fail if the target nodes cannot accommodate the data immediately. 2. Monitoring the Decommission * Verification: Don't just wait for them to disappear. Use
SHOW BACKENDS;
and check the
SystemDecommissioned
column. Once the node is gone from the list, StarRocks has safely moved all data. * Tablet Health: It is a good idea to run
SHOW PROC '/statistic';
to ensure there are no "Unhealthy" tablets before proceeding to the Terraform phase. 3. Terraform & Instance Upgrades (The Risky Part) Your plan to
terraform apply
to upgrade the instance types of the remaining 8 nodes is the most dangerous step. * Avoid Simultaneous Restarts: Most cloud providers (AWS/GCP/Azure) require a stop/start or a replacement to change an instance type. If your Terraform configuration applies this change to all 8 nodes at once, your entire cluster will go offline. * Recommended Approach: 1. Do not let Terraform update all 8 nodes at once. 2. Either use a Terraform module that supports rolling updates (e.g., an AWS Auto Scaling Group with an Instance Refresh) or—more commonly—update the instance type manually one by one. 3. For each node: Stop the BE $\rightarrow$ Change Instance Type $\rightarrow$ Start BE $\rightarrow$ Wait for it to show as
Alive
in
SHOW BACKENDS
$\rightarrow$ Move to the next. * IP Pinning: Pinning private IPs is excellent. StarRocks uses the IP/Port as the unique identifier for BEs. If the IP changes, the FE will treat it as a new, empty node. 4. Refined Plan Strategy 1. Phase 1 (Scale In): Decommission 2 BEs, wait for completion. Decommission the next 2 BEs, wait for completion. 2. Phase 2 (Clean State): Run
terraform apply
to only remove the 4 decommissioned nodes from the state/infrastructure. 3. Phase 3 (Vertical Upgrade): Perform a rolling upgrade of the instance types for the 8 remaining nodes. If using Terraform for this, do it one node (or one small group) at a time by updating variables/targets specifically, or perform it manually to ensure the cluster stays up. Summary Checklist * [ ]
SHOW BACKENDS
shows all remaining nodes are healthy. * [ ]
SHOW PROC '/statistic'
shows 0 unhealthy tablets. * [ ] Verify
replication_num
on all tables is $\le 8$. * [ ] Ensure Terraform won't reboot all 8 nodes simultaneously. Referencesadministration/management/Scale_up_down.mddeployment/plan_cluster.mdknowledge/usage/best-practice.mdbest_practices/query_tuning/schema_tuning.mddeployment/upgrade.md
If the
UnhealthyTabletNum
is stuck or decreasing very slowly while
cluster_balance
shows 0 pending tablets, it usually means the Tablet Checker has detected issues but the Tablet Scheduler is either not creating tasks or the tasks are failing/being throttled. Here is a step-by-step troubleshooting guide to unstick the process: 1. Identify the Stuck Tablets First, find out exactly which tablets are considered "unhealthy" and why. 1. Find the Database ID:
Copy code
sql
    SHOW PROC '/statistic';
Look for the
DbId
where
UnhealthyTabletNum
is greater than 0. 2. Get the Tablet IDs:
Copy code
sql
    -- Replace <db_id> with the ID from the previous step
    SHOW PROC '/statistic/<db_id>';
This will return a list of
UnhealthyTablets
. 3. Inspect a specific tablet: Pick a few tablet IDs from the list and run:
Copy code
sql
    SHOW TABLET <tablet_id>;
In the output, copy the command in the
DetailCmd
column and execute it. This will show you exactly where each replica is located and its status (e.g.,
VERSION_ERROR
,
MISSING
, or if it's still sitting on the decommissioned node). 2. Check for Resource Throttling If
pending_tablets
is 0, the scheduler might be skipping tasks due to resource limits or disk space. * Disk High Watermark: Run
SHOW BACKENDS;
and check the
AvailCap
and
DataUsedCap
. If the remaining 8 nodes are over 85-90% full, StarRocks will stop scheduling new replicas to them. _ _Fix:* Increase disk space or delete unnecessary data. * Scheduling Slots: The FE limits how many concurrent tasks can run per BE path. _ _Fix:* Temporarily increase the scheduling concurrency:
Copy code
sql
        ADMIN SET FRONTEND CONFIG ("tablet_sched_slot_num_per_path" = "16");
        ADMIN SET FRONTEND CONFIG ("tablet_sched_max_scheduling_tablets" = "2000");
3. Check for "Blocking" Tablets * Single-Replica Tables: If any table has
replication_num = 1
, the decommissioning process cannot "move" the data; it must create a new replica first. If there are constraints (like Colocate Groups or rack awareness), this can hang. * Colocate Groups: If your tables are in a
colocate_with
group, the balancing is stricter. Check if the group is stable:
Copy code
sql
    SHOW PROC '/colocation_group';
If
IsStable
is
false
, the colocation balancer might be fighting with the decommission repair. 4. Force Repair If you've identified a specific table that is stuck, you can force the FE to prioritize its repair:
Copy code
sql
ADMIN REPAIR TABLE <table_name>;
This moves all unhealthy tablets of that table to the front of the scheduling queue with
VERY_HIGH
priority. 5. Check FE Logs (The "Why") If the numbers still don't move, the Leader FE log is the source of truth. Search the
fe.log
for these keywords: *
TabletScheduler
*
CloneTask
*
schedule repair tablet
Look for error messages like
no available backend to take replica
or
exceed max slot num
. Summary Checklist 1. Are the target BEs full? (Check
SHOW BACKENDS
) 2. Are there many small tablets? (Increases metadata overhead, speed up with
tablet_sched_slot_num_per_path
) 3. Is the Leader FE under heavy load? (Check FE JVM GC and CPU) 4. Are there tables with replication_num = 1? (These often require manual intervention or higher priority) Referencesadministration/management/resource_management/Replica.mdfaq/operation_maintenance_faq.md