• Elastic Cloud Server

ecs
  1. Help Center
  2. Elastic Cloud Server
  3. API Reference
  4. Extension ECS APIs
  5. Status Management
  6. Changing an ECS OS (Using an Image with Cloud-Init Installed)

Changing an ECS OS (Using an Image with Cloud-Init Installed)

Function Description

This interface is used to change an ECS OS. During the system disk reinstallation using a new image, the data disks of the ECS remain unchanged.

After this interface is called, the system uninstalls the system disk, uses the new image to create a system disk, and attaches it to the ECS. In this way, the OS is changed.

Constraints

  • You can only use an image with Cloud-Init or Cloudbase-Init installed.
  • Only a stopped ECS or an ECS on which reinstalling or changing the OS failed supports changing OS.
  • Only an ECS with a system disk supports changing OS.
  • You are not allowed to perform other operations when changing the OS. Otherwise, changing the OS will fail.
  • This interface supports only the images with Cloud-Init or Cloudbase-Init installed. Otherwise, this interface does not support injecting keys or passwords.

URI

POST /v2/{project_id}/cloudservers/{server_id}/changeos

Table 1 describes the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

server_id

Yes

Specifies the ECS ID.

Request

Request parameters

Table 2 describes the request parameters.
Table 2 Request parameters

Parameter

Mandatory

Type

Description

os-change

Yes

Dict

Changes an ECS OS.

Table 3 os-change field description

Parameter

Mandatory

Type

Description

keyname

No

String

Specifies the key pair name.

userid

No

String

Specifies the user ID.

imageid

Yes

String

Specifies the ID of the new image in UUID format.

metadata

No

Dictionary data structure

Specifies the metadata of the ECS for which the OS is to be changed.

For more information, see Table 4.

Table 4 metadata field description

Parameter

Mandatory

Type

Description

BYOL

No

String

Specifies whether a user has the license of an image.

  • If this parameter is set to true, the license file delivered with the image is used, indicating that BYOL is used.
  • If this parameter is set to a value other than true, BYOL is not used, and the license file provided by the public cloud platform must be used.

The default value is not true, indicating that BYOL is not used.

user_data

No

String

Specifies the user data to be injected during the ECS OS change process.

Text, text files, and gzip files can be injected. The content to be injected cannot be greater than 32 KB in size. The content to be injected must be encoded with base64.

Response

See Responses (Task).

Examples

  • Example request
    {
        "os-change": {
            "keyname": "KeyPair-350b", 
            "userid": "7e25b1da389f4697a79df3a0e5bd494e", 
            "imageid": "e215580f-73ad-429d-b6f2-5433947433b0", 
            "metadata": {
                  "BYOL": "false"
            }
        }
    }

Returned Values

See General Request Returned Values.

Error Code

See Error Code Description.