Configuring Circuit Breakers

Constraints

An API can be bound to only one plug-in policy of the same type in the same environment. A plug-in policy that has been bound to an API cannot be deleted.

Creating a Circuit Breaker Policy

1. Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific instance.
2. In the navigation pane on the left, choose API Connect > API Policies. On the Policies tab, click Create Policy.
3. On the Select Policy Type page, select Circuit Breaker in the Plug-ins area.
4. On the page displayed, configure plug-in policy information.

   Table 1 Policy configuration

   Parameter	Description
   Name	Enter a policy name. Using naming rules facilitates future search.
   Type	Fixed as Circuit Breaker.
   Scope	Specify the scope to view the policy. Integration application: Each policy belongs to an integration application. Only users who have the permission on the integration application can view and use the policy. All: All users in the current instance can view and use the policy.
   Integration Application	Mandatory for Scope set to Integration application. Select an integration application for the policy. If none is available, click Create Integration Application on the right to create one.
   Description	Describe the policy.
   Policy Content: Configure the policy in a form or script. For details about how to configure a script, see Script Configuration Example.
   Policy Type	Select a policy type. API-specific: APIs bound to the current plug-in are calculated separately for circuit breaker triggering. API-sharing: All APIs bound to the current plug-in are calculated together for circuit breaker triggering.
   Trigger Configuration
   Circuit Breaker Type	Specify a circuit breaker triggering type. Timeout downgrade: The circuit breaker is triggered upon backend timeout. Conditional downgrade: The circuit breaker is triggered whenever conditions configured in Match Conditions are met.
   Condition Type	Specify a circuit breaker triggering mode. Count: Once the number of requests that meet the conditions specified within the time window reaches the threshold, the circuit breaker is immediately triggered. Percentage: Once the percentage of requests that meet the conditions specified within the time window reaches the threshold, the circuit breaker is triggered at the end of the time window.
   Match Conditions	This parameter is mandatory only when Circuit Breaker Type is set to Conditional downgrade. Configure the match conditions for circuit breaker triggering. Response Error Codes: The circuit breaker is triggered when the backend responds with the status codes specified. Response Latency: The circuit breaker is triggered when the backend response latency exceeds the threshold specified.
   Time Window (s)	Configure the time window for circuit breaker triggering. Use this parameter together with Threshold or Min Percentage. Once the number of times or percentage when conditions are met within the time window exceeds the threshold, the circuit breaker is triggered.
   Threshold	This parameter is mandatory only when Condition Type is set to Count. Configure the threshold for circuit breaker triggering. Use this parameter together with Time Window (s). Once the number of backend requests that meet the conditions within the time window reaches the threshold, the circuit breaker is triggered. NOTE: A circuit breaker plug-in is triggered for a single gateway component. If ROMA Connect has multiple components, the triggering for each component is determined separately. If the threshold is reached within the time window for a gateway component, requests sent to the component trigger the circuit breaker, but other gateway components still forward requests normally. An IP address indicates a gateway component. To view the number of gateway components, go to the Instance Information page of a ROMA Connect instance by clicking the instance name on the console and view the number of IP addresses in Connection Addresses.
   Min Calls	This parameter is mandatory only when Condition Type is set to Percentage. Set the minimum number of API calls that will trigger the circuit breaker within the time period. The circuit breaker will not be triggered if the number of API calls within the time period is less than this value.
   Min Percentage (%)	This parameter is mandatory only when Condition Type is set to Percentage. Configure the threshold for circuit breaker triggering. Use this parameter together with Time Window (s). Once the percentage of backend requests that meet the conditions within the time window reaches the threshold, the circuit breaker is triggered.
   Control Duration (s)	Configure the duration for which the circuit breaker is open. The circuit breaker is closed when the duration reaches the value specified.
   Backend Downgrade Policy	Specify whether to enable the backend downgrade policy. Enable: Requests for APIs that have triggered a downgrade will be forwarded to a specified backend. Disable: Requests for APIs that have triggered a downgrade will not be forwarded to any backend. Instead, an error message indicating that the service is unavailable will be returned.
   Backend Policy Type	This parameter is mandatory only when Backend Downgrade Policy is enabled. Specify the backend type to which requests will be forwarded when the circuit breaker is open. NOTE: For security purposes, do not include sensitive information in these parameters. Mock: The defined response will be returned. Status Code: the status code to be included in the response Response: the response body, which is in JSON format Response Header: header parameters to be included in the response HTTP&HTTPS: Backend requests will be forwarded to the specified backend service. Load Balance Channel: Determine whether to use a load balance channel to access the backend service. If you want to select Configure, create a load balance channel in advance. Backend URL: address of the backend service to forward requests to. Timeout (ms): backend request timeout. The default value is 5000 ms. FunctionGraph: Backend requests will be forwarded to a specified function. Function URN: unique identifier of a function request. Click Select to select a function. Function Name: automatically displayed after you select a function. Version/Alias: Select the version or alias of the function to be used. Invocation Mode: the mode in which the function is invoked. - Synchronous: When receiving an invocation request, FunctionGraph immediately processes the request and returns a result. The client closes the connection once it has received a response from the backend. - Asynchronous: After receiving an invocation request, FunctionGraph queues the request and returns the result after the request is successfully processed. The server processes the queuing requests one by one when it is idle. The client does not care about the invocation result. Timeout (ms): backend request timeout. The default value is 5000 ms. Passthrough: Backend requests will be forwarded to the original API backend. To add header parameters to backend requests, click Add Parameter.
   Downgrade Parameter Settings	Specify whether to enable downgrade parameter configuration. When enabled, custom rules take precedence over the default ones configured above: If a custom rule is matched, its trigger conditions and downgrade policy take effect. If the custom rule contains no trigger condition or downgrade policy, the default settings in Trigger Configuration and Backend Downgrade Policy take effect. If the custom rules are not matched, the default settings take effect.
   Define Parameters	Define the parameters for rule matching. Click Add Parameter to add rule parameters. NOTE: For security purposes, do not include sensitive information in these parameters. Parameter Location: position of a parameter in an API request. path: API request URI. This parameter is configured by default. method: API request method. This parameter is configured by default. header: first value of the header parameter in an API request. query: first value of the query parameter in an API request. system: a system parameter. Parameter: name of a parameter used for rule matching.
   Define Rules	Customize matching rules for the circuit breaker. Click Add Rule to add rules. The system matches rules from top to bottom. Define Rules: Click to edit the condition expressions. If there are three or more expressions, you can layer them by clicking Set Lower Level. =: equal to !=: not equal to pattern: regular expression enum: enumerated values, separated by comma (,) For details about how to configure the triggering conditions and backend downgrade, see the instructions for the default settings above. Example: You have enabled Downgrade Parameter Settings and added rules rule01 and rule02 in sequence. And you have disabled Trigger Configuration and enabled Backend Downgrade Policy for rule01, and have enabled both parameters for rule02. Analysis: The circuit breaker first checks whether the match conditions of rule01 are met. If yes, the circuit breaker opens based on the default settings because no trigger condition is defined in rule01, and the backend downgrade policy in rule01 is executed. If no, rule02 is checked.

5. Click OK.

   After a plug-in policy is created, perform Binding a Plug-in Policy to an API for the policy to take effect for the API.

Binding a Plug-in Policy to an API

1. On the Policies tab page, filter policies by Circuit Breaker.
2. Click the name of a policy to go to the details page.
3. On the APIs tab, select the environment of the APIs you want to bind the policy to and click Bind to APIs.
4. On the page displayed, select the APIs to bind the policy to.

   APIs can be filtered by API group and API name.

5. Click OK.

Script Configuration Example

{
  "breaker_condition":{
    "breaker_type":"timeout",
    "breaker_mode":"counter",
    "unhealthy_threshold":30,
    "time_window":15,
    "open_breaker_time":15,
    "unhealthy_percentage":51,
    "min_call_threshold":20
  },
  "scope":"share",
  "downgrade_default":{
    "type":"http",
    "passthrough_infos":null,
    "func_info":null,
    "mock_info":null,
    "http_info":{
      "isVpc":false,
      "vpc_channel_id":"",
      "address":"10.10.10.10",
      "scheme":"HTTP",
      "method":"GET",
      "path":"/demo",
      "timeout":5000
    },
    "http_vpc_info":null
  },
  "downgrade_parameters":[
  {
    "name":"reqPath",
    "type":"path",
    "value":"path",
    "disabled":true,
    "focused":true,
    "id":"92002eqbpilg6g"
  },
  {
    "name":"method",
    "type":"method",
    "value":"method",
    "disabled":true,
    "focused":true,
    "id":"tuvxetsdqvcos8"
  }],
  "downgrade_rules":[
  {
    "rule_name":"rule-test1",
    "parameters":[
      "reqPath",
      "method"
    ],
    "match_regex":"[\"reqPath\",\"==\",\"/test\"]",
    "downgrade_backend":{
      "type":"mock",
      "passthrough_infos":null,
      "func_info":null,
      "mock_info":{
        "status_code":200,
        "result_content":"{status: ok}",
        "headers":[]
      },
      "http_info":null,
      "http_vpc_info":null
    },
    "breaker_condition":{
      "breaker_type":"timeout",
      "breaker_mode":"percentage",
      "unhealthy_threshold":30,
      "time_window":15,
      "open_breaker_time":15,
      "unhealthy_percentage":51,
      "min_call_threshold":20
    }
  }]
}