Help Center/ Cloud Search Service/ API Reference/ API V1/ Cluster Management/ Obtaining Details About a Cluster Upgrade or AZ Switchover
Updated on 2025-11-28 GMT+08:00
View PDF

Obtaining Details About a Cluster Upgrade or AZ Switchover

Function

By deploying a CSS cluster across multiple AZs, you can increase the cluster's availability, lower the likelihood of data loss, and minimize service downtime. You can deploy a cluster across two or three AZs within a region. The upgrade may take a long time. This API can be used to check phase-by-phase information during a cluster upgrade or AZ switchover.

Calling Method

For details, see Calling APIs.

URI

GET /v1.0/{project_id}/clusters/{cluster_id}/upgrade/detail

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

Value range:

Project ID of the account.

Default value:

N/A

cluster_id

Yes

String

Definition:

ID of the cluster to be upgraded. For details about how to obtain the cluster ID, see Obtaining the Cluster ID.

Constraints:

N/A

Value range:

Cluster ID.

Default value:

N/A
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

offset

No

Integer

Definition:

The start value of the query. The default value is 1, indicating that the query starts from the first task.

Constraints:

N/A

Value range:

1-1000

Default value:

1

limit

No

Integer

Definition:

Number of AZs to be queried. The default value is 10, indicating that 10 AZs are queried at a time.

Constraints:

N/A

Value range:

1-1000

Default value:

10

action_mode

No

String

Definition:

Query details about a cluster upgrade or AZ change operation.

Constraints:

N/A

Value range:

  • UPGRADING: query cluster upgrade details.

  • AZ_MIGRATION: query AZ change details.

Default value:

UPGRADING

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

totalSize

Integer

Definition:

Total number of cluster upgrade or AZ change tasks.

Value range:

N/A

detailList

Array of GetUpgradeDetailInfo objects

Definition:

Details of cluster upgrade or AZ change tasks.

Value range:

N/A
Table 4 GetUpgradeDetailInfo

Parameter

Type

Description

id

String

Definition:

ID of the upgrade or AZ change task.

Value range:

N/A

startTime

String

Definition:

Start time of an upgrade or AZ change task.

Value range:

N/A

endTime

String

Definition:

End time of an upgrade or AZ change task.

Value range:

N/A

status

String

Definition:

Status of an upgrade or AZ change task.

Value range:

  • RUNNING: The task is being executed.

  • SUCCESS: The task is successful.

  • FAILED: The job failed.

  • PARTIAL_FAILED: The task failed partially.

agencyName

String

Definition:

Agency name. You can create an agency to allow CSS to call other cloud services.

Value range:

N/A

imageInfo

GetTargetImageIdDetail object

Definition:

Image details.

Value range:

N/A

totalNodes

String

Definition:

Names of all nodes that need to be upgraded or switched to another AZ.

Value range:

N/A

completedNodes

String

Definition:

Nodes where upgrade or AZ change tasks have been completed.

Value range:

N/A

currentNodeName

String

Definition:

Name of the node that is being upgraded or switched to another AZ.

Value range:

N/A

executeTimes

String

Definition:

Number of times the upgrade or AZ change task was retried.

Value range:

N/A

migrateParam

String

Definition:

This parameter is available only when action_mode is set to AZ_MIGRATION. It indicates the request parameter of the AZ change task.

Value range:

N/A

finalAzInfoMap

String

Definition:

This parameter is available only when action_mode is set to AZ_MIGRATION. It indicates the AZ details of each node after AZ switchover.

Value range:

N/A

currentNodeDetail

Array of CurrentNodeDetail objects

Definition:

Task details of the node that is being upgraded or switched to another AZ.

Value range:

N/A

batchSize

Integer

Definition:

Number of nodes where data is being migrated concurrently.

Value range:

N/A

currentBatchNodes

String

Definition:

Nodes where data is being migrated.

Value range:

N/A
Table 5 GetTargetImageIdDetail

Parameter

Type

Description

id

String

Definition:

ID of an image that can be upgraded.

Value range:

N/A

displayName

String

Definition:

Name of an image that can be upgraded.

Value range:

N/A

imageDesc

String

Definition:

Image description.

Value range:

N/A

datastoreType

String

Definition:

Cluster engine type.

Value range:

  • elasticsearch: Cloud Search Service (CSS) provides distributed search capabilities, log analytics, reporting, and semantic search based on open-source Elasticsearch.

  • logstash: Provides functions such as data ingestion, transformation, cleaning, and parsing based on open-source Logstash.

  • opensearch: Provides distributed search, log analytics, reporting, and semantic search based on open-source OpenSearch. It is the future version of CSS's Elasticsearch clusters.

datastoreVersion

String

Definition:

Image engine version.

Value range:

N/A

priority

Integer

Definition:

Priority of the target image. A larger value indicates a higher priority.

Value range:

N/A
Table 6 CurrentNodeDetail

Parameter

Type

Description

order

Integer

Definition:

SN of the upgrade or AZ switchover task.

Value range:

N/A

name

String

Definition:

Name of the upgrade or AZ switchover task.

Value range:

N/A

status

String

Definition:

Status of the upgrade or AZ change task of the current cluster.

Value range:

  • RUNNING: running

  • SUCCESS

  • FAILED

  • WAITING

desc

String

Definition:

Description of the upgrade or AZ change task of the current cluster.

Value range:

N/A

beginTime

String

Definition:

Start time of the upgrade or AZ change task of the current cluster.

Value range:

N/A

endTime

String

Definition:

End time of the upgrade or AZ change task of the current cluster.

Value range:

N/A

Example Requests

  • Query cluster upgrade details.

    GET https://{Endpoint}/v1.0/{project_id}/clusters/ea244205-d641-45d9-9dcb-ab2236bcd07e/upgrade/detail

  • Query details about a cluster AZ change task.

    GET https://{Endpoint}/v1.0/{project_id}/clusters/ea244205-d641-45d9-9dcb-ab2236bcd07e/upgrade/detail?action_mode=AZ_MIGRATION

Example Responses

Status code: 200

Request succeeded.

  • Example response for querying cluster upgrade details.

    {
  "totalSize" : 1,
  "detailList" : [ {
    "id" : "b7ac4c5b-3bda-4feb-a303-eb80f4bce986",
    "startTime" : "2023-01-05T02:23:39",
    "endTime" : "",
    "status" : "RUNNING",
    "agencyName" : "css_test_agency",
    "imageInfo" : {
      "id" : "439b5d30-5968-45df-b088-d030a858522d",
      "displayName" : "7.10.2_22.5.1_1230",
      "imageDesc" : "The latest image of version 7.10.2 will be officially released on December 30, 2022. the stability of the cluster has been optimized. It is recommended that you upgrade to this version.",
      "datastoreType" : "elasticsearch",
      "datastoreVersion" : "7.10.2",
      "priority" : 16
    },
    "totalNodes" : "css-test-ess-esn-1-1,css-test-ess-esn-2-1,css-test-ess-esn-3-1",
    "completedNodes" : "",
    "currentNodeName" : "css-test-ess-esn-1-1",
    "executeTimes" : "1",
    "currentNodeDetail" : [ {
      "order" : 0,
      "name" : "Data migration",
      "status" : "SUCCESS",
      "desc" : "Data is migrated from a node to other nodes in the cluster by running the exclude command.",
      "beginTime" : "2023-01-05T02:23:42",
      "endTime" : "2023-01-05T02:29:51"
    }, {
      "order" : 12,
      "name" : "Task status update",
      "status" : "WAITING",
      "desc" : "The cluster task status is refreshed. If there are no nodes to be replaced, the task is marked as completed. Otherwise, another node starts to be replaced.",
      "beginTime" : "",
      "endTime" : ""
    } ]
  } ]
}

  • Example response for querying cluster AZ change details.

    {
  "totalSize" : 1,
  "detailList" : [ {
    "id" : "8ebe958b-b8c6-4939-b5a7-85aee9468888",
    "startTime" : "2022-12-29T08:32:29",
    "endTime" : "",
    "status" : "RUNNING",
    "agencyName" : "css_test_agency",
    "totalNodes" : "css-test-ess-esn-2-1,css-test-ess-esn-1-1,css-test-ess-esn-3-1",
    "completedNodes" : "css-test-ess-esn-2-1",
    "currentNodeName" : "css-test-ess-esn-1-1",
    "executeTimes" : "1",
    "migrateParam" : "{\"instType\":\"ess\",\"migrateType\":\"az_migrate\",\"sourceAz\":\"cn-north-4a\",\"targetAz\":\"cn-north-4c\"}",
    "finalAzInfoMap" : "{\"cn-north-4c\":\"css-test-ess-esn-2-1,css-test-ess-esn-1-1,css-test-ess-esn-3-1\"}",
    "currentNodeDetail" : [ {
      "order" : 0,
      "name" : "Data migration",
      "status" : "SUCCESS",
      "desc" : "Data is migrated from a node to other nodes in the cluster by running the exclude command.",
      "beginTime" : "2022-12-29T08:41:05",
      "endTime" : "2022-12-29T08:41:23"
    }, {
      "order" : 12,
      "name" : "Task status update",
      "status" : "RUNNING",
      "desc" : "The cluster task status is refreshed. If there are no nodes to be replaced, the task is marked as completed. Otherwise, another node starts to be replaced.",
      "beginTime" : "2023-01-04T06:53:42",
      "endTime" : ""
    } ]
  } ]
}

Status Codes

Status Code

Description

200

Request succeeded.

400

Invalid request.

The client should not repeat the request without modifications.

403

Request rejected.

The server has received the request and understood it, but the server refuses to respond to it. The client should not repeat the request without modifications.

Error Codes

See Error Codes.

Parent topic: Cluster Management