The Multi-active Service for High Availability (MSHA) console lets you add custom actions that run before or after a switchover. You can implement these pre-actions and post-actions by using callbacks to your business interfaces. This topic describes how to add a custom action.
Limitations
You can configure a maximum of five custom actions for each multi-active instance.
Procedure
Log on to the MSHA console.
In the left-side navigation pane, click Multi-active Instances.
On the Multi-active Instances page, click the Instance Name/ID of the target instance to go to its details page.
On the instance details page, click .
On the Custom Actions page, click Add and configure the following parameters.
Parameter
Description
Callback URL
The URL of the callback interface.
The MSHA control plane must be able to connect to the root IP address of the URL. We recommend that you test network connectivity before you configure the URL.
The URL must include the protocol prefix, such as
http://xx.domain.com/yy.
Pre/Post
When the custom action is executed.
Pre-action: A blocking action. MSHA calls the specified interface and proceeds with the switchover only after the blocking condition is met. You must set a blocking configuration.
Post-action: An action triggered after a switchover completes. MSHA calls the specified interface if the trigger condition is met. You must configure a trigger condition.
You can configure both pre-actions and post-actions for a multi-active instance.
Blocking Configuration/Trigger Condition
Blocking Configuration: If you select Pre, you must select a blocking configuration.
Wait for Success: The switchover process continues only after the HTTP interface returns a 2xx status code.
Wait for Completion: The switchover process continues as soon as the HTTP interface returns a response, regardless of whether the call succeeded or failed.
Wait for Failure: The switchover process continues only after the HTTP interface returns a non-2xx status code.
Ignore Result: MSHA asynchronously calls the HTTP interface and continues the switchover immediately, without waiting for a response.
Trigger Condition: If you select Post, you must select a trigger condition.
Switchover Successful: The interface is called only if the switchover succeeds.
Switchover Completed: The interface is called after the switchover completes, regardless of the outcome.
Switchover Failed: The interface is called only if the switchover fails due to an exception.
Ignore Result: Asynchronously calls the HTTP interface after the switchover completes. The result of the callback is ignored.
Parameter List
The parameters to include in the HTTP/HTTPS callback request.
HTTP Request Method
The HTTP/HTTPS request method to use for the callback. Valid values: GET and POST.
Digest Salt
The salt used to generate a security digest for the callback request.
Enabled
Specifies whether to execute this custom action.
Yes: Executes this custom action.
No: Does not execute this custom action.
Application Architecture
The application architecture used by the instance. Valid values:
Geo-redundant dual-active
Intra-city multi-active
Geo-redundant application dual-active
Parameter name
Parameter code
Description
Multi-active Space ID
mshaTenantId
The ID of the multi-active instance.
Switchover ticket ID
id
The switchover ticket ID.
Switchover ticket name
name
The switchover ticket name.
Source unit flag
sourceUnitFlag
The flag for the source unit.
Target unit flag
targetUnitFlag
The flag for the target unit.
Switchover Status
status
The final status of the switchover.
Normal completion states:
complete: The switchover completed normally.
canceled: The switchover was manually canceled.
Abnormal completion states:
autoCanceled: The switchover was automatically canceled after an error occurred, and the rollback is complete.
cancelFailed: The attempt to cancel the switchover failed.
closed: The switchover was forcibly closed without continuing or rolling back.
fail: The switchover was terminated due to other errors.
Switchover Completion Time
completeTime
The time when the switchover was completed.
Switchover Change Range
changeTokenRange
For range-based switchovers, this parameter specifies the range of tokens affected. For other switchover types, this parameter is an empty string ("").
Format:
[$start_of_range,$end_of_range]. The square brackets[]indicate an inclusive range.Java example:
String changeTokenRange="[1,9999]";.Switchover Change Exact List
changeTokenList
For list-based switchovers, this parameter specifies the exact list of tokens affected. For other switchover types, this parameter is an empty string ("").
Format: A list of tokens separated by commas (,).
Java example:
String changeTokenList="11,22,33";.Security digest
digest
The security digest, used to verify the trustworthiness of the call and prevent parameter tampering.
Affected Components
modules
A list of affected components, separated by commas (,).
Domain name list
domainList
A list of domain names affected by the switchover.
Java example:
String domainList="['domain1','domain2']";.Traffic ratio
ratio
The traffic distribution ratio after the switchover.
Format: A JSON string where the key is the unit flag and the value is the traffic ratio for that unit.
Custom
Passes through user-defined parameters.
ImportantDo not use the predefined parameter keys listed above, as this will cause parameter values to be overwritten.
Click Save, and then click Confirm in the dialog box that appears.
Other operations:
Delete: In the Actions column, click Delete to delete the custom action.
Modify: In the Actions column, click Modify to modify the custom action.
Requirements
When you use the custom action feature, your callback interface must meet the following requirements.
The callback interface must use the HTTP or HTTPS protocol.
The callback interface must be publicly accessible and not require authentication or login session validation.
The callback interface must not perform CSRF token validation.
The callback interface must accept parameters that follow the naming conventions below. When the MSHA console initiates a callback, you must select which parameters to include in the request. These parameters contain basic information about the switchover ticket and a security digest for verification.
Parameter
Description
mshaTenantId
The ID of the multi-active instance.
id
The switchover ticket ID.
name
The switchover ticket name.
sourceUnitFlag
The flag for the source unit from which traffic is switched.
targetUnitFlag
The flag for the target unit to which traffic is switched.
status
The final status of the switchover.
Normal completion states:
complete: The switchover completed normally.
canceled: The switchover was manually canceled.
Abnormal completion states:
autoCanceled: The switchover was automatically canceled after an error occurred, and the rollback is complete.
cancelFailed: The attempt to cancel the switchover failed.
closed: The switchover was forcibly closed without continuing or rolling back.
fail: The switchover was terminated due to other errors.
completeTime
The time when the switchover was completed.
changeTokenRange
For range-based switchovers, this parameter specifies the range of tokens affected. For other switchover types, this parameter is an empty string ("").
Format:
[$start_of_range,$end_of_range]. The square brackets[]indicate an inclusive range.Java example:
String changeTokenRange="[1,9999]";.changeTokenList
For list-based switchovers, this parameter specifies the exact list of tokens affected. For other switchover types, this parameter is an empty string ("").
Format: A list of tokens separated by commas (,).
Java example:
String changeTokenList="11,22,33";.digest
The security digest, used to verify the trustworthiness of the call and prevent parameter tampering.
Callback interface example
The following code provides an example of a callback interface written in Java by using the Spring MVC framework:
@RestController
@RequestMapping("/demo")
@Slf4j
public class DemoController {
@RequestMapping(path = "/switchEndCallback", method = {RequestMethod.POST, RequestMethod.GET})
public void switchEndCallback( @RequestParam String mshaTenantId,
@RequestParam String id,
@RequestParam String name,
@RequestParam String sourceUnitFlag,
@RequestParam String targetUnitFlag,
@RequestParam String status,
@RequestParam String completeTime,
@RequestParam String changeTokenRange,
@RequestParam String changeTokenList,
@RequestParam String digest) throws Exception {
// Add your business logic here.
}
} Validating the callback request
When the MSHA console sends a callback request, it includes the digest parameter. This security digest verifies the authenticity of the request and prevents parameter tampering.
Customize a digestSalt value, and configure digestSalt in the settings for the switchover completion callback interface on the MSHA console.
After the switchover, the caller (MSHA console) initiates the callback. It generates a
digestby using the digestSalt and the callback parameters, and includes thisdigestparameter in the callback request.When your application receives the callback request, it must generate its own digest, named expectedDigest, using the same method. Compare this expectedDigest with the
digestfrom the request. A match confirms that the request is authentic and its parameters are unaltered.NoteVerification succeeds only if both the caller and the provider use the same salt and parameters to generate the digest.
The following code provides an example:
@RestController
@RequestMapping("/demo")
@Slf4j
public class DemoController {
@RequestMapping(path = "/switchEndCallback", method = {RequestMethod.POST, RequestMethod.GET})
public Object switchEndCallback(@RequestParam String mshaTenantId,
@RequestParam String id,
@RequestParam String name,
@RequestParam String sourceUnitFlag,
@RequestParam String targetUnitFlag,
@RequestParam String status,
@RequestParam String completeTime,
@RequestParam String changeTokenRange,
@RequestParam String changeTokenList,
@RequestParam String digest) throws Exception {
// Use a TreeMap to ensure that the parameters are sorted alphabetically, which provides a consistent order for concatenation.
TreeMap<String, String> sortedParamMap = new TreeMap<>();
sortedParamMap.put("mshaTenantId", mshaTenantId);
sortedParamMap.put("id", id);
sortedParamMap.put("name", name);
sortedParamMap.put("sourceUnitFlag", sourceUnitFlag);
sortedParamMap.put("targetUnitFlag", targetUnitFlag);
sortedParamMap.put("status", status);
sortedParamMap.put("completeTime", completeTime);
sortedParamMap.put("changeTokenRange", changeTokenRange);
sortedParamMap.put("changeTokenList", changeTokenList);
log.info("switchEndCallback params:" + sortedParamMap);
// The salt used to generate the security digest. This value must be the same as the one you configured in the MSHA console.
String digestSalt = "kbBO1nD1BM_Ymr76XOoZkbJ72k4";
StringBuilder paramsStringBuilder = new StringBuilder();
for (Map.Entry<String, String> entry : sortedParamMap.entrySet()) {
paramsStringBuilder.append(entry.getValue());
}
paramsStringBuilder.append(digestSalt);
// We recommend that you use DigestUtils from commons-codec 1.10 or later to generate the MD5 hash digest.
String expectedDigest = org.apache.commons.codec.digest.DigestUtils.md5Hex(paramsStringBuilder.toString().getBytes("utf-8"));
// Verification succeeds only if both the caller and the provider use the same salt and parameters to generate the digest.
boolean digestCheckPassed = digest.equalsIgnoreCase(expectedDigest);
log.info("switchEndCallback digestCheckPassed:{}", digestCheckPassed);
return "switchEndCallback returned success";
}
}