Updated on 2026-08-10 GMT+08:00

Replacing a Node

Function

This API is used to replace a failed node.

If a node in an Elasticsearch or OpenSearch cluster is faulty, you can replace it to restore services.

The node replacement process is as follows:

  1. Migrate data from the node that needs to be replaced to other available nodes.

  2. Rebuild the node using the original ID, IP address, specifications, and AZ.

  3. Add the new node into the cluster. The system automatically triggers a shard reallocation, migrating some of the shards to the new node.

This process does not interrupt services because data is migrated from the replaced node to other available nodes.

All mission-critical data has been backed up before a node replacement. This is to prevent data loss.

Constraints

  • Only one node can be replaced at a time. Each new node is rebuilt using the ID, IP address, specifications, and AZ of the node it is replacing.

  • The configurations you modified manually will not be retained after node replacement. For example, if you have manually added a return route for the original node, you need to add it again for the new node after the node replacement is complete.

  • If the node you want to replace is a data node or cold data node, pay attention to the following precautions:

  • When a data node or cold data node is replaced, its data is first migrated to other data nodes. This means the total number of data nodes and cold data nodes must be greater than the maximum number of index replicas plus 1.

  • Elasticsearch clusters whose version is earlier than 7.6.2 cannot have closed indexes. Otherwise, their data nodes or cold data nodes cannot be replaced.

  • In the AZ that contains the data node or cold data node to be replaced, there has to be at least another data node or cold data node.

  • If the cluster has not master nodes, the total number of data nodes plus cold data nodes must be at least three.

  • The precautions above do not apply if you are replacing a faulty node, regardless of its type. This is because faulty nodes are not included in _cat/nodes.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    css:cluster:upgradeCluster

    Write

    cluster *

    • g:EnterpriseProjectId

    • g:ResourceTag/<tag-key>

    -

    • ecs:cloudServerFlavors:get
    • evs:types:get
    • kms:cmk:get
    • iam:agencies:listAgencies
    • iam:permissions:listRolesForAgency
    • iam:permissions:listRolesForAgencyOnProject
    • iam:agencies:pass

URI

PUT /v1.0/{project_id}/clusters/{cluster_id}/instance/{instance_id}/replace

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. For details about how to obtain the project ID and name, see Obtaining the Project ID and Name.

Constraints

N/A

Range

Project ID of an account. The value contains 32 characters, consisting of lowercase letters and digits.

Default Value

N/A

cluster_id

Yes

String

Definition

ID of the cluster where nodes are to be replaced. For details about how to obtain the cluster ID, see Obtaining the Cluster ID.

Constraints

N/A

Range

The value is a UUID containing 36 characters.

Default Value

N/A

instance_id

Yes

String

Definition

ID of the node to be replaced. Obtain the ID attribute in instances by referring to Querying Cluster Details.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

migrateData

No

String

Definition:

Whether to migrate data.

Constraints:

N/A

Value range:

  • true: Migrate data.

  • false: Do not migrate data.

Default value:

true

agency

No

String

Definition

Agency name. To store snapshots to an OBS bucket, you must have the required OBS access permissions. Select an IAM agency to grant the current account the permission to access and use OBS.

Constraints

  • VPC permissions required by the agency: "vpc:subnets:get","vpc:ports:*".

  • This parameter is mandatory when the new IAM plane is connected, and is optional when the old IAM plane is connected.

Range

The agency name can contain at most 64 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

Default Value

N/A

Request Parameters

None

Response Parameters

Status code: 200

Request succeeded.

None

Example Requests

Replace a node.

PUT https://{Endpoint}/v1.0/{project_id}/clusters/4f3deec3-efa8-4598-bf91-560aad1377a3/instance/43e63449-339c-4280-a6e9-da36b0685995/replace?migrateData=true

Example Responses

None

SDK Sample Code

The SDK sample code is as follows.

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.css.v1.region.CssRegion;
import com.huaweicloud.sdk.css.v1.*;
import com.huaweicloud.sdk.css.v1.model.*;


public class UpdateInstanceSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        CssClient client = CssClient.newBuilder()
                .withCredential(auth)
                .withRegion(CssRegion.valueOf("<YOUR REGION>"))
                .build();
        UpdateInstanceRequest request = new UpdateInstanceRequest();
        request.withClusterId("{cluster_id}");
        request.withInstanceId("{instance_id}");
        try {
            UpdateInstanceResponse response = client.updateInstance(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}

Python

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkcss.v1.region.css_region import CssRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkcss.v1 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = CssClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(CssRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = UpdateInstanceRequest()
        request.cluster_id = "{cluster_id}"
        request.instance_id = "{instance_id}"
        response = client.update_instance(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)

Go

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    css "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/css/v1"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/css/v1/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/css/v1/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := css.CssClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := css.NewCssClient(hcClient)

    request := &model.UpdateInstanceRequest{}
	request.ClusterId = "{cluster_id}"
	request.InstanceId = "{instance_id}"
	response, err := client.UpdateInstance(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

More

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

200

Request succeeded.

400

Invalid request.

The client should modify the request instead of re-initiating it.

404

The requested resource could not be found.

The client should modify the request instead of re-initiating it.

Error Codes

See Error Codes.