Call CreatePatchPlan to create a patch plan.

Usage notes

Patch installation may involve potential risks such as service interruptions, CPU spikes, and I/O spikes, which can affect normal business operations. Perform patch installation during an appropriate period, such as off-peak hours. Risks include:

Server restart is required after kernel patch installation, which directly interrupts services on the deployment node.

Operations such as file decompression, signature verification and system file replacement during patch installation can easily cause CPU and I/O resource contention. This impairs business performance and causes application crashes and other issues. This process may also consume a large amount of network bandwidth, affecting cross-node service communication.

Debugging

API Explorer

You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.

Go to debug

Request parameters

Only the request parameters specific to this operation and some common parameters are listed below. For more information, refer to Common parameters.

Action string required Sample value: CreatePatchPlan

The operation that you want to perform. Value: CreatePatchPlan.

Version string required Sample value: 2020-04-01

The API version. Value: 2020-04-01.

UseDefaultBaseline boolean Optional Sample value: true

Whether to use the default patch baseline. Value:

true: Use the default patch baseline. The patch plan performs a scan, or a scan and patch installation, based on the default baseline corresponding to the operating system of the target instance.

tip

When this parameter is set to true, you do not need to specify BaselineId.

false (default): Do not use the default patch baseline. You need to specify a custom patch baseline ID using BaselineId.

Name string required Sample value: UbuntuBaseline

The name of the patch plan. Value:

It must start with a letter or a Chinese character.

It can contain only Chinese characters, letters, digits, underscores (_), hyphens (-), and English periods (.).

It must be 1 to 64 characters in length.

BaselineId string Optional Sample value: bl-xffsafgewgdf****

The ID of the patch baseline.

You can obtain a patch baseline ID that meets the conditions by calling CreatePatchBaseline.

Description string Optional Sample value: The description of the baseline.

The description of the patch plan. Value:

It must start with a letter or a Chinese character.

It can contain only Chinese characters, letters, digits, underscores (_), hyphens (-), equal signs (=), English commas (,), English periods (.), Chinese commas (，), Chinese periods (。), and spaces.

It must be 0 to 256 characters in length.

tip

If left blank, the parameter defaults to an empty value.

RepeatMode string Optional Sample value: Once

The execution mode of the plan. Value:

Once (default): Immediate execution.

Recurrence: Periodic execution.

Scheduled: Scheduled execution.

ScheduledPolicy object Optional Sample value: --

The scheduled or periodic policy.

tip

This parameter is required only when the task execution mode is scheduled or periodic execution.

RecurrenceEndTime string Optional Sample value: 2025-12-09T20:45Z

The end time of the periodic task.

RecurrenceType string Optional Sample value: Daily

The recurrence cycle of the periodic task. Valid values:

Daily: Repeat at a daily interval, for example, execute every 2 days.

Weekly: Repeat weekly, and execute once per day within the week.

Monthly: Repeat monthly, for example, execute daily from the 2nd to the 8th of each month.

Cron: Repeat based on the specified cron expression.

LaunchTime string required Sample value: 2022-04-01T16:00Z

The trigger time of the task.

tip

If ScheduledPolicy.RecurrenceType is specified, this parameter specifies the start time of the periodic task.

When RepeatMode is set to Once, this parameter is invalid.

RecurrenceValue string Optional Sample value: 1

The value for recurring execution of periodic tasks. Valid value: String type, such as "10".

OperationType string required Sample value: Scan

The execution type of the patch plan. Valid values:

Scan: Only scan patches.

Install: Scan and install patches.

AutoCreateSnapshot boolean Optional Sample value: true

Whether to create a snapshot for the system volume. Valid values:

false (default): Do not create a snapshot.

true: Automatically create a snapshot for the system volume, and the snapshot is retained for 7 days by default.

AutoReboot boolean Optional Sample value: true

Specifies whether to automatically restart the instance after patch installation. Valid values:

false (default): Do not automatically restart the instance.

true: Automatically restart the instance.

tip

This parameter is required only when the OperationType parameter is set to Install.

Whether a restart is required after patch installation depends on the type of component involved. Generally, there are two types:

A restart is required for the patch to take effect: Kernel-related patches, core system library patches, daemon/service package patches, and more.

A restart is not required for the patch to take effect: User-mode tools, CLI tool types, and more.

TargetType string required Sample value: ECS

The filter type of the target instance. Value:

ECS: ECS instance.

Tag: Filter target instances by tag.

Project: Filter target instances by project.

TargetValue string required Sample value: ["i-xffsafgewgdf****"]

The value corresponding to the target filter type (JSON-formatted string). Valid values:

ECS: When TargetType is ECS instance, this value is a list of ECS instance IDs. Up to 200 instances are supported.

Tag: When TargetType is Tag, this value is a list of tag key-value pairs. Up to 10 tags are supported.

Project: When TargetType is Project, this value is a single ProjectName.

MaxConcurrency string Optional Sample value: 10

During task execution, the maximum number of instances allowed to execute the command simultaneously. Value:

Default value: 50

Value range

Quantity: 0–100

Percentage: 0–100%

MaxErrors string Optional Sample value: 10

The maximum number of failed instances allowed during task execution. Value:

Default value: 0

Value range

Quantity: 0–100.

Percentage: 0–100%

tip

When the number of failed instances exceeds this threshold, the system stops issuing commands to the remaining unexecuted instances.

ClientToken string Optional Sample value: example

ClientToken is used to ensure the idempotency of the request. The client automatically generates a token to ensure that the token is unique among different requests. This prevents repeated actions due to multiple client retries when the API call times out or an internal server error occurs. Values:

It can contain only ASCII characters.

It cannot exceed 64 characters in length.

Response parameters

Only the response parameters specific to this operation are listed below. For more information, refer to the response structure.

PatchPlanId string Sample value: pp-yedfvyt41q5s2jax****

The ID of the patch plan.

Sample request

Sample response

Error codes

The table below lists the business-related error codes of the operation. For more information, refer to Common error codes.

Status code	Error code	Error message	Description
400	InvalidArgument	The specified argument is invalid.	The specified parameter is invalid.
500	InternalError	An internal error has occurred.	An internal error occurred. Try again. If multiple attempts fail, submit a ticket.

Elastic Compute Service