Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Version Upgrade/ Upgrading Kernel Versions of Instances in Batches
Updated on 2025-08-11 GMT+08:00

Upgrading Kernel Versions of Instances in Batches

Function

This API is used to upgrade kernel versions of instances in batches. There are three upgrade types: gray upgrade, in-place upgrade, and hot patch update. The earliest version of all selected instances must be earlier than available target versions, and they must support the same upgrade method and action. If gray upgrade is used, all AZs and shards are upgraded by default.

  • In-place upgrade: Services are interrupted for about 30 minutes during the in-place upgrade. All nodes in a DB instance are upgraded at a time and you need to stop all services during the upgrade.
  • Gray upgrade:
    Services are interrupted for 10s during the upgrade of each primary DN or CN. The management plane is upgraded first, and then the data plane from the standby nodes to the primary nodes.
    • Auto-commit: All nodes are upgraded at the same time. Services are interrupted for about 10s during the upgrade.
    • Rolling upgrade: You can observe service status before committing the upgrade. There are upgrade and commit phases.
      • In the upgrade phase, DB instances can be upgraded by shard or AZ based on the deployment model.
        • Distributed instances are upgraded by shard. When instances are upgraded in batches, all shards are upgraded by default.
        • Centralized instances are upgraded by AZ. When instances are upgraded in batches, all shards are upgraded by default.
      • In the commit phase, you can test services on your instance after the upgrade is complete, and then either commit or roll back the upgrade based on test results.
        • Commit: After the upgrade is complete and services are normal, commit the upgrade.
        • Rollback: When the upgrade is complete and enters the commit phase, you can roll back the instance to the source version as required.
  • Hot patch update
    • Auto-commit: Hot patches are automatically updated and committed without downtime. Only product bugs are fixed.
    • Rollback: Services are not interrupted when the hot patches are rolled back.

URI

PUT /v3/{project_id}/instances/db-upgrade

Table 1 Parameter description

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID of a tenant in a region.

To obtain the value, see Obtaining a Project ID.

Constraints

N/A

Range

The value can contain 32 characters. Only letters and digits are allowed.

Default Value

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

instance_ids

Yes

Array of strings

Definition

Instance IDs for batch upgrade.

Constraints

N/A

upgrade_type

Yes

String

Definition

Instance upgrade type. There are three upgrade types: in-place upgrade, gray upgrade, and hot patch update. The value is case-sensitive.

Constraints

N/A

Range

  • grey: Gray upgrade
  • inplace: In-place upgrade
  • hotfix: Hot patch update

Default Value

N/A

upgrade_action

No

String

Definition

Instance upgrade action. For an in-place upgrade, this parameter does not need to be specified. For the gray upgrade, this parameter can be set to upgradeAutoCommit, upgrade, commit, or rollback. The value is case-sensitive.

Constraints

N/A

Range

  • upgrade: Upgrade
  • upgradeAutoCommit: Auto-commit
  • commit: Commit
  • rollback: Rollback

Default Value

N/A

target_version

No

String

Definition

Target version that the instances are upgraded to in batches. This parameter is optional.

Constraints

For a gray upgrade or an in-place upgrade, if this parameter is not specified, the instances are upgraded to the preferred version by default. For a major version upgrade, this parameter is mandatory for the gray upgrade and in-place upgrade. For a hot patch update, this parameter does not need to be specified and all available hot patches are updated by default. To obtain its value, see Querying Upgrade Types and Versions That Instances Can Be Upgraded to in Batches.

Range

N/A

Default Value

N/A

Response Parameters

Table 3 Response parameters

Parameter

Type

Description

job_ids

Array of strings

Definition

Job ID.

succeeded_num

Integer

Definition

Number of instances whose task requests are submitted successfully.

Range

N/A

failed_num

Integer

Definition

Number of instances whose task requests fail to be submitted.

Range

N/A

failed_instance_ids

Array of strings

Definition

IDs of instances whose task requests fail to be submitted.

error_messages

Array of strings

Definition

List of error information about task submission failures.

Example Request

  • Upgrading instances in batches using the in-place upgrade
    PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances/db-upgrade
    { 
      "instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14", "aa0ae5c47bf94834bf9e44138f7f995ain14" ], 
      "upgrade_type" : "inplace" , 
      "target_version" : "8.100.0" 
    }
  • Upgrading instances in batches using the gray upgrade with the rolling upgrade action
    PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances/db-upgrade
    { 
      "instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14", "aa0ae5c47bf94834bf9e44138f7f995ain14" ], 
      "upgrade_type" : "grey", 
      "upgrade_action" : "upgrade", 
      "target_version" : "8.100.0" 
    }
  • Upgrading instances in batches using the gray upgrade with the rollback action
    PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances/db-upgrade
    { 
      "instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14", "aa0ae5c47bf94834bf9e44138f7f995ain14" ], 
      "upgrade_type" : "grey", 
      "upgrade_action" : "rollback", 
      "target_version" : "8.100.0" 
    }
  • Upgrading instances in batches using the gray upgrade with the auto-commit action
    PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances/db-upgrade
    { 
      "instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14", "aa0ae5c47bf94834bf9e44138f7f995ain14" ], 
      "upgrade_type" : "grey", 
      "upgrade_action" : "upgradeAutoCommit", 
      "target_version" : "8.100.0" 
    }
  • Upgrading instances in batches using the hot patch update with the auto-commit action
    PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances/db-upgrade
    { 
      "instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14", "aa0ae5c47bf94834bf9e44138f7f995ain14" ], 
      "upgrade_type" : "hotfix", 
      "upgrade_action" : "upgradeAutoCommit" 
    }
  • Rolling back instances in batches using the hot patch update with the rollback action
    PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e663/instances/db-upgrade
    {
    "instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14", "aa0ae5c47bf94834bf9e44138f7f995ain14" ],
    "upgrade_type" : "hotfix",
    "upgrade_action" : "rollback"
    }

Example Response

{ 
  "job_ids" : [ "2b414788a6004883a02390e2eb0ea227", "aa414788a6004883a02390e2eb0ea228" ], 
  "succeeded_num" : 2, 
  "failed_num" : 1, 
  "failed_instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14" ], 
"error_messages": ["This operation cannot be performed because the instance status is abnormal."]
}

Status Codes

Error Codes

For details, see Error Codes.