All Products
Search

This Product

    Elasticsearch:Upgrade cluster configuration

    Document Center

    Elasticsearch:Upgrade cluster configuration

    Last Updated:Jun 02, 2026

    Upgrade your ES cluster by adding nodes, upgrading node specifications, expanding disk space, or adding node types when resource utilization stays high or performance falls short.

    Before you begin

    Important

    Upgrading can cause service latency, configuration conflicts, and billing changes. Review the following items before you proceed.

    • Service stability

      • Service stability during configuration changes:

        Cluster condition

        Service impact

        Recommended action

        Normal load with replicas

        Normal load: CPU ≤ 60%, heap memory ≤ 50%, load < number of cores.

        Service remains available. Minor performance decrease possible.

        No action required.

        High load without replicas

        High load: High concurrent writes or queries during the upgrade, with CPU > 60% or heap memory > 50%.

        Occasional access timeouts may occur.

        • Enable a retry mechanism on the client.

        • Increase the number of index replicas before the upgrade.

        High load with an unhealthy status

        Occasional access timeouts or service jitters may occur.

        Restore cluster health before the change.

      • Maintenance window: Perform the operation during off-peak hours.

    • Capacity planning

      evaluate the required cluster capacity.

    • Configuration constraints

      • You cannot upgrade the Elasticsearch version while upgrading the cluster configuration.

      • You can change only one type of node in a single upgrade operation.

    • Cost impact

      After you submit the upgrade order, billing follows the updated configuration. Billing rules: pay-as-you-go, subscription.

    Pre-upgrade checks

    Important

    Skipping these checks can cause cluster crashes, data loss, or service unavailability.

    • Cluster health

      Run GET _cluster/health to verify the cluster status is GREEN. If unhealthy, resolve the issue using Cluster Change Error - Unhealthy Cluster State.

    • Load safety

      Run GET _cat/nodes?v. CPU utilization should be ≤ 60%. If higher, enable client-side retries and increase index replicas.

    • Index readiness

      • Run GET /_cat/indices?v to check for closed indices. Open any with POST /<index_name>/_open before proceeding. Closed indices cause configuration changes to fail because:

        • Closed indices prevent the cluster from reaching GREEN status, which is required for shard allocation changes.

        • During a configuration change, the cluster reallocates shards:

          • Shards of closed indices cannot participate in reallocation.

          • Operations requiring GREEN status fail.

          • The cluster can only reach YELLOW at best.

      • Run GET _cat/indices?v to verify each index has at least 1 replica.

        For multi-zone deployments, keep the replica count below the number of zones during the change (recommended: 1). Increase replicas after the change completes.

    • Shard balance

      Run GET _cat/shards?v to check for any unbalanced shards.

      Important

      Unbalanced shards can cause performance degradation or cluster crashes after the upgrade.

      • prirep: Check if any replica shard (r) is UNASSIGNED.

      • state: Check if any shard migration is stuck in the RELOCATING state for an extended period.

      These issues prevent new nodes from receiving shards, leaving the cluster in YELLOW or RED. Resolve them using Solutions for uneven cluster load.

    Method 1: Upgrade via console

    1. On the Instances page, click Upgrade Configuration.

      Alternative entry point: On the Basic Information page of your instance, click Configuration Update > Upgrade.

    2. On the Upgrade/Downgrade page, adjust the configuration parameters based on your business requirements.

      Important

      Available parameters vary by cluster type and version. The upgrade page shows the applicable options.

      • Availability zone changes: If stock is insufficient for a specification in a zone, migrate nodes first.

        You can expand from one zone to two or three.

      • Node specifications and storage types (lowest to highest performance):

        1. Previous generation cloud disks: standard cloud disk -> ultra cloud disk -> SSD cloud disk.

          Note

          These disk types are being phased out in some regions. Use ESSDs instead.

        2. ESSDs: ESSDs (Enterprise SSDs) use 25 GbE networking and RDMA for up to 1 million IOPS per disk with low latency.

        3. Local disks.

          Note

          Local disks reside on the physical ECS host machine. They suit workloads requiring high I/O performance or cost-effective mass storage.

      • Intelligent Update (enabled by default): The system selects the optimal update method automatically. You can disable it and choose manually:

        Update method

        Mechanism

        Duration

        Service impact and use cases

        Blue-green Update

        Add new nodes → Copy data → Seamless switchover

        Long

        • Node IP addresses change. Temporary performance fluctuations possible.

        • Best when availability matters more than update speed.

        In-place Update

        Rolling restart of nodes (no data copying required).

        Short

        • Node IP addresses unchanged. Temporary performance fluctuations possible.

        • Best for quick resolution of performance bottlenecks.

          Important

          Use caution if resource utilization is high (CPU > 60%).

      • Forced Update: Skips health checks and forces a cluster restart. Recovery time depends on data volume. Use only for emergency scaling when the cluster is already unavailable.

    3. Read the Terms of Service and Service Level Agreement. If you agree, click Buy Now. Billing follows the selected method.

      During the change, cluster status changes to Initializing with possible performance fluctuations and transient request failures. After completion, status returns to Normal.

    Method 2: Upgrade via API

    Call the UpdateInstance API operation.

    Monitor and verify

    • After the upgrade starts, check progress on the Basic Information page in the Elasticsearch Clusters console:

      Click Show Details:

    • After the upgrade, verify the new configuration on the Basic Information page:

      • The cluster status returns to Active.

      • Availability zone

      • Node count and storage: Confirm new nodes joined the cluster and storage specifications are correct.

      • Shard balance: Run GET _cat/allocation?v to check shard distribution. If unbalanced, use Solutions for uneven cluster load.

    FAQ

    Upgrades and performance metrics

    Q: Does upgrading always fix performance?

    A: Not necessarily. Upgrading CPU, memory, or disk does not fix all issues. Identify the specific bottleneck first:

    • CPU bottleneck: Sustained utilization above 80% (not brief spikes).

    • Memory bottleneck: Frequent long garbage collection (GC) times, memory swapping, or OutOfMemory (OOM) errors.

    • Disk bottleneck: Check actual I/O throughput, not just %util (see below).

    • Network bottleneck: Network bandwidth is consistently saturated, and latency is noticeably high.

    Confirm the bottleneck before upgrading. Optimizing indices, queries, or configurations is often more effective than adding resources.

    Q: Why is my system normal if %util is 100%?

    A: The %util metric in iostat measures the percentage of time a device was busy with I/O, not the I/O volume. Modern disks process multiple I/O requests in parallel, so 100% %util does not mean the device is saturated.

    • For example, a disk takes 0.1 seconds to process a single I/O request and can handle 10 requests simultaneously.

      • If 10 I/O requests are submitted sequentially, it takes 1 second to complete them, and %util is 100%.

      • If 10 I/O requests are submitted at once, they are processed in parallel and complete in 0.1 seconds. Measured over a one-second interval, this results in a %util of 10%.

    The %util metric is largely irrelevant for modern storage and should not drive upgrade decisions alone.

    Q: What metrics indicate a disk bottleneck?

    A: Focus on these metrics instead of %util:

    1. I/O throughput: Actual read/write rate (MB/s) versus your requirements.

    2. Response time: The latency of I/O requests, which directly affects query performance.

    3. IOPS: I/O operations per second for your workload pattern.

    4. Queue depth: The number of pending I/O requests.

    A %util of 100% that is not sustained for hours is usually not concerning. Use tools like fio to benchmark actual maximum bandwidth and IOPS.

    Q: How to assess a disk performance bottleneck?

    A: Evaluate disk performance as follows:

    1. Analyze your workload: Determine the read/write ratio, I/O size, and access patterns.

    2. Compare actual throughput against requirements, not %util.

    3. Benchmark with fio: Simulate your actual workload to test real-world disk performance.

    4. Evaluate query latency: Verify ES query response times meet your requirements.

    5. Monitor ES metrics: Track indexing latency and search latency.

    Base upgrade decisions on a complete set of metrics — CPU utilization, memory usage, I/O throughput, and query latency — not a single metric.

    Other questions