All Products
Search
Document Center

:Change orders

Last Updated:Dec 18, 2023

Serverless App Engine (SAE) provides a variety of APIs. You can use these APIs to perform different tasks, such as managing namespaces and VPCs, querying application information, implementing auto scaling, and querying microservices. SAE manages applications based on change orders. This topic describes the basic concept, API calls, and process design of SAE change orders.

What is a change order?

Basic concept

SAE manages applications based on change orders. You must rely on change orders to perform O&M on your applications in SAE. Change orders of an application managed in SAE must be executed in sequence. SAE executes only one change order for an application at a time.

Why cannot change orders be executed in parallel?

  • Auto scaling

    When you use SAE to release or scale applications, all auto scaling rules must be disabled to prevent exceptions. If multiple change orders are executed in parallel, conflicts may occur. For example, auto scaling rules are disabled for Order A but are re-enabled for Order B while Order A is still in progress. When auto scaling rules take effect and you attempt to scale an application, the application may not scale as expected.

  • Release and rollback

    Each release and rollback operation generates a description file about underlying resources. SAE allows a maximum of two application versions to exist at the same time. If multiple change orders are executed in parallel, more than two application versions may be deployed, which is beyond the limit.

API calls related to change orders

You can call APIs related to change orders to deploy applications in SAE. This topic describes how to check whether a change order is executed successfully. The application release scenario is used in the example. Application release is the most complex usage scenario of change orders. Therefore, the method used to check whether a change order is successfully executed in this scenario can also be applied in other scenarios.

The Status parameter is returned when you call APIs related to change orders. This parameter has the following valid values:

  • 0: The change order is being prepared.

  • 1: The change order is being executed.

  • 2: The change order is executed successfully.

  • 3: The change order fails to be executed.

  • 6: The execution of the change order is stopped.

  • 8: The execution process is pending. You must manually determine the release batch.

  • 9: The execution process is pending. SAE will automatically determine the release batch.

  • 10: The execution fails due to a system exception.

  • 11: The change order is pending approval.

  • 12: The change order is approved and is pending execution.

Check whether the change order is executed successfully

  1. Call an API operation, such as CreateApplication or DeployApplication. If the returned Success value is true and the Code value is 200, the ChangeOrderId parameter is also returned.

  2. Call the DescribeChangeOrder operation, in which the ChangeOrderId parameter is set to the value obtained in the previous step.

  3. Check the value of the Status parameter in the response. If the value is 2, the change order is executed successfully.

Rollback scenarios

  • Single-batch release

    When a single-batch release fails or is stopped, SAE does not automatically roll back the application. You can call the RollbackApplication operation to implement the rollback as needed. If you call the DescribeChangeOrder operation and the returned value of the Status parameter is 3 or 10, the change order fails to be executed.

  • Canary release or batch release

    When a change order fails to be executed, SAE automatically rolls back the application.

    You need to call the AbortAndRollbackChangeOrder operation to stop the execution of a change order when the returned values of the Status and SubStatus parameter are both 1.

Manual operations in canary and batch releases

This section describes how to manually determine the batch in a batch release. In a canary or batch release, you can start operations on a new batch only after the previous batch is processed.

  1. Call the DeployApplication operation and obtain the ChangeOrderId value in the response.

  2. Call the DescribeChangeOrder operation, in which the ChangeOrderId parameter is set to the value obtained in the previous step.

  3. If the value of the Status parameter in the response is 8, you can call the ConfirmPipelineBatch operation to continue the release. You must specify the PipelineId parameter when you call the ConfirmPipelineBatch operation. This parameter indicates the ID of the next batch in the release. The response of the DescribeChangeOrder operation contains the CurrentPipelineId and Pipelines parameters. The Pipelines parameter indicates the array of all batches. The CurrentPipelineId parameter indicates the ID of the current batch. This step can be repeated. When PipelineId that you specified when you called the ConfirmPipelineBatch operation is the same as CurrentPipelineId returned from the DescribeChangeOrder operation, you need to call the ConfirmPipelineBatch again, in which PipelineId is set to the ID of the batch that follows the current one in the array of all batches.

Process design of change orders

Why are auto scaling rules not automatically restored after a change order fails to be executed?

  • Release and rollback

    Auto scaling rules are disabled before a change order is executed. SAE automatically restores the auto scaling rules when the change order is successfully executed. If the execution fails, SAE does not automatically restore the rules. Because multiple application versions are generated during the execution process, SAE cannot determine the application version to run.

  • Application scaling

    Auto scaling rules may conflict with your manual scaling operations. For example, you want to manually scale the number of application instances from 10 to 5, but SAE determines that the number needs to be increased to 15 based on an auto scaling rule. Therefore, auto scaling rules must be disabled when you want to manually scale your application.

Why does SAE automatically roll back the application when a batch release fails?

In a batch release, when only some of the batches are processed successfully, two versions of application instances coexist. In this case, the change order for the batch release fails to be executed. If the execution is stopped but the application is not rolled back, three versions of instances may coexist the next time the application is released. Therefore, SAE must automatically roll back the application to ensure that the application instances have two versions at most.