On this page

Show all

Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Version Upgrade/ Upgrading the Kernel Version of a DB Instance

Upgrading the Kernel Version of a DB Instance

Updated on 2024-11-15 GMT+08:00

View PDF

Function

This API is used to upgrade kernel version of a DB instance. There are three upgrade types: in-place upgrade, gray upgrade, and hot patch update.

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. You can select auto-commit after the upgrade or perform a rolling upgrade.
- 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.
    - Primary/standby instances are upgraded by AZ.
  - 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.
- Rollback: Services are not interrupted when the hot patches are rolled back.

Learn how to authenticate this API.
Obtain the required region and endpoint.

URI

PUT https://{Endpoint}/v3.1/{project_id}/instances/{instance_id}/db-upgrade

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Explanation: Project ID of a tenant in a region. For details about how to obtain the value, see Obtaining a Project ID. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None
instance_id	Yes	String	Instance ID, which is compliant with the UUID format.

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
upgrade_type	Yes	String	Instance upgrade type. The value is case-sensitive. inplace: In-place upgrade grey: Gray upgrade hotfix: Hot patch update
upgrade_action	No	String	Instance upgrade action. The value is case-sensitive. For the in-place upgrade, this parameter is optional. For the gray upgrade, this parameter can be set to upgradeAutoCommit, upgrade, commit, or rollback. For the hot patch update, this parameter can be set to upgradeAutoCommit or rollback. upgradeAutoCommit: Auto-commit upgrade: Rolling upgrade commit: Commit rollback: Rollback
target_version	No	String	Target version that the instance will be upgraded to. In a hot patch update, multiple hot patch versions can be configured.
upgrade_shard_num	No	Integer	Number of shards to be upgraded in a gray upgrade for a distributed instance. This parameter is mandatory when upgrade action is set to upgrade (rolling upgrade). The value cannot be greater than the number of shards that have not been upgraded.
upgrade_az	No	String	AZ to be upgraded in a gray upgrade. This parameter is mandatory when upgrade action is set to upgrade (rolling upgrade). Multiple AZs can be upgraded at the same time. Use commas (,) to separate AZs. You cannot enter an AZ that does not belong to the instance.

Response Parameters

**Table 3** Response body parameters
Parameter	Type	Description
job_id	String	Task ID. For pay-per-use instances, only the task ID is returned.
order_id	String	Order ID. This parameter is returned only when your instance is billed at a yearly/monthly basis.

Example Request

In-place upgrade

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{ 
    "upgrade_type" : "inplace",
    "target_version": "xxx"
}

Hot patch update

Updating hot patches

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{
    "upgrade_type" : "hotfix",
    "target_version" : "xxxx,xxxx,xxxx",
    "upgrade_action" : "upgradeAutoCommit"
}

Rolling back hot patches

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{
    "upgrade_type": "hotfix",
    "target_version": "xxxx,xxxx,xxxx",
    "upgrade_action": "rollback"
}

Gray upgrade

Setting upgrade_action to upgradeAutoCommit

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{ 
    "upgrade_type" : "grey",
    "target_version": "xxx",
    "upgrade_action" : "upgradeAutoCommit" 
}

Setting upgrade_action to upgrade

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{ 
    "upgrade_type" : "grey",
    "target_version": "xxx",
    "upgrade_action" : "upgrade", 
    "upgrade_shard_num" : 1, 
}

Rolling back the upgrade when the instance is in the rolling upgrade phase (All upgraded shards will be rolled back. After the instance becomes available, the rollback is successful.)

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{ 
    "upgrade_type" : "grey",
    "target_version": "xxx",
    "upgrade_action" : "rollback"
}

Committing the upgrade when the instance is in the rolling upgrade phase (After all upgraded shards are upgraded, you can commit the upgrade.) (After the instance is available, the upgrade is complete.)

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{ 
    "upgrade_type" : "grey",
    "target_version": "xxx",
    "upgrade_action" : "commit"
}

Upgrading a primary/standby instance in the gray method (upgrade action is rolling upgrade)

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/db-upgrade
{ 
    "upgrade_type" : "grey", 
    "upgrade_action" : "upgrade", 
    "target_version": "xxx",
    "upgrade_az" : "az1,az2" 
}

Example Response

{ 
  "job_id" : "2b414788a6004883a02390e2eb0ea227" 
}

Status Code

Normal
202
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Parent topic: Version Upgrade

Previous topic: Querying Versions That a DB Instance Can Be Upgraded To

Next topic: Querying Upgrade Types and Versions That Instances Can Be Upgraded to in Batches

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot