DocsICP FilingConsole
官方文档
首页

Configure policies and plug-ins

更新时间：
复制 MD 格式
产品详情
我的收藏

Cloud-native API Gateway lets you add policies and configure plug-ins for APIs and operations to improve their security, performance, and maintainability.

Important

  • Policy changes take effect immediately. You do not need to republish the API.

  • By default, the gateway applies API-level plug-in configurations at the operation level.

  • While you cannot delete API-level policies at the operation level, operation-level policies can override API-level policies.

Procedure

  1. You can add an API policy in two ways: from outside an instance or from within an instance.

    APIs outside an instance

    1. Log on to the Cloud-native API Gateway console. In the left-side navigation pane, click API and select a region from the top menu bar.

    2. Click the target API and select the target instance from the drop-down list.

    APIs inside an instance

    1. Log on to the Cloud-native API Gateway console. In the left-side navigation pane, click Instance and select a region from the top menu bar.

    2. On the Instance page, click the ID of the target gateway instance. In the left-side navigation pane, click API, and then click the target API.

  2. You can configure policies and plug-ins at the API level or the operation level:

    • API level: Click the API Policy Configuration tab to configure policies and plug-ins for all operations at the API level. Then, click Enable Policy/Plug-in.

    • Operation level: On the Operations tab, click the target operation. Click the Policy Configuration tab, and then click Enable Policy/Plug-in.

  3. In the Enable Policy/Plug-in panel, select a policy or plug-in to configure. For more information, see Policy configuration and Plug-in configuration.

Policies

Throttling policy

Cloud-native API Gateway supports throttling policies at the API and operation levels. These policies prevent inbound requests from overwhelming your backend services and help you avoid cascading failures. In high-concurrency scenarios, throttling protects the availability of backend services by blocking some requests. This lets you precisely control the number of requests for each API and operation within a specific time period, ensuring that the number does not exceed a preset threshold.

Throttling policies include Concurrency Control, Traffic Control, and Circuit Breaking.

  • Concurrency control policy: This policy limits the number of concurrent requests. It works by counting the total number of requests currently being processed by the gateway. When this number reaches the configured threshold, the gateway immediately blocks new traffic. You can set this threshold to match the maximum concurrent requests that your backend service can handle to protect its availability during traffic spikes.

    Procedure

    On the Add Policy page, click the Concurrency Control card. In the Add Policy: Concurrency Control panel, configure the parameters.

    Parameter

    Description

    Enable or Not

    Enables the concurrency control rule.

    Overall Concurrency Threshold

    Set the Overall Concurrency Threshold.

    Web Fallback Behavior

    Return Specific Content

    HTTP Status Code

    Set the HTTP Status Code. The default value is 429.

    Type of Returned Content

    Set Type of Returned Content to Regular Text or JSON.

    HTTP Text

    The content of the custom response body.

    Return Specific Content

    Redirect URL

    Enter the Redirect URL.

  • Traffic control policy: This policy limits the request rate based on queries per second (QPS). It works by monitoring the QPS for an API or operation. When the QPS reaches the configured threshold, the gateway immediately blocks new traffic. This prevents backend services from being overwhelmed by sudden traffic spikes and ensures high availability.

    Procedure

    On the Add Policy page, click the Traffic Control card. In the Add Policy: Traffic Control panel, configure the parameters.

    Parameter

    Description

    Enable or Not

    Enables the traffic control rule.

    Overall QPS Threshold

    Set the Overall QPS Threshold.

    Web Fallback Behavior

    Return Specific Content

    HTTP Status Code

    Set the HTTP Status Code. The default value is 429.

    Type of Returned Content

    Set Type of Returned Content to Regular Text or JSON.

    HTTP Text

    The content of the custom response body.

    Redirect to Specified Page

    Redirect URL

    Enter Redirect URL.

  • Circuit breaking policy: This policy protects backend services by monitoring the response time or error rate of APIs and operations. When a specified threshold is reached, the gateway "trips the circuit," immediately failing fast on requests to the unstable service to prevent further strain. After a configured duration, the gateway enters a "half-open" state and allows a limited number of test requests to see if the service has recovered. If the service is stable, the circuit closes; otherwise, it trips again.

    Procedure

    On the Add Policy page, click the Circuit Breaking card. In the Add Policy: Circuit Breaking panel, configure the parameters.

    Parameter

    Description

    Enable or Not

    Enables the circuit breaking rule.

    Statistical Window Duration

    The length of the time window for collecting statistics. Valid values: 1 second to 120 minutes.

    Minimum Number of Requests

    The minimum number of requests within the statistics window required to trigger circuit breaking. If the request count is below this value, the circuit breaker will not trip, even if the error threshold is met.

    Threshold Type

    Select either Slow Call Ratio (%) or Exception Ratio (%) as the threshold type.

    1. If you select Slow Call Ratio (%), you must set the Slow Call RT (maximum response time). A request is counted as a slow call if its response time exceeds this value. When the rule is enabled, if the number of requests within the statistics window is greater than the minimum request count, and the percentage of slow calls exceeds the threshold, the circuit is tripped. After the circuit breaking duration elapses, the circuit breaker enters a probing recovery (half-open) state. If the next test request's response time is less than the specified slow call RT, the circuit closes. Otherwise, the circuit is tripped again.

    2. If you select Exception Ratio (%), you must set the error percentage threshold. When the rule is enabled, if the number of requests within the statistics window is greater than the minimum request count, and the percentage of errors exceeds the threshold, the circuit is tripped for the configured duration.

    Slow Call RT

    Set the allowed Slow Call RT (that is, the maximum response time).

    Circuit Breaking Ratio Threshold

    The percentage of slow calls or errors that triggers circuit breaking. Valid values: 0 to 100 (representing 0% to 100%).

    Circuit Breaking Duration (s)

    The duration for which the circuit remains open after being tripped. During this period, all requests to the resource will fail fast.

    Web Fallback Behavior

    Return Specific Content

    HTTP Status Code

    Set the HTTP Status Code. The default is 429.

    Type of Returned Content

    Set Type of Returned Content to Regular Text or JSON.

    HTTP Text

    The content of the custom response body.

    Redirect to Specified Page

    Redirect URL

    Enter the Redirect URL.

Rewrite policy

A rewrite policy lets you modify the request path and hostname before forwarding the request to the backend service. This helps meet specific business and architectural requirements by ensuring that requests are routed to the correct service or endpoint.

Procedure

On the Add Policy page, click HTTP Rewrite to open the Add Policy: HTTP Rewrite panel and configure the parameters.

  • Path rewrite

    Cloud-native API Gateway supports two modes for path rewrite.

    • Exact Rewrite: Supports only operation-level rewrites.

    • Regex Rewrite: Supports both operation-level and API-level rewrites.

    Exact rewrite

    Exact rewrite allows you to modify the prefix of the original request path.

    Example 1

    The original request path is /app/test, but the path forwarded to the backend service should be /test. We recommend the following configuration:

    • API and operation matching condition: Set the match type to Exact Match and the path to /app/.

    • Rewrite: Set the rewrite type to Exact Rewrite and the path to /.

    Note

    The path for the API and operation matching condition must be set to /app/ because an exact rewrite only modifies the exact matched string. If the path were set to /app, the rewritten path would incorrectly be //test.

    Example 2

    The original request path is /v1/test, but the path forwarded to the backend service should be /v2/test. We recommend the following configuration:

    • API and operation matching condition: Set the match type to Exact Match and the path to /v1.

    • Rewrite: Set the rewrite type to Exact Rewrite and the path to /v2.

    Important

    Exact rewrite requires that the API or operation matching method is set to Exact Match. Prefix Match and Regex Match do not support exact rewrite. Exact rewrite applies to all requests with the specified prefix. If this is not your intent, use a different rewrite method.

    Regex rewrite

    Regex rewrite allows you to modify parts of the original request path. A regex rewrite configuration consists of two parts: a pattern to match the part of the path you want to change, and a replacement string to substitute the matched part. For more information about the regular expression syntax, see RE2 Syntax.

    Example 1

    The original request path is /aaa/one/bbb/one/ccc, but the path forwarded to the backend service should be /aaa/two/bbb/two/ccc. We recommend the following configuration:

    • API and operation matching condition: Set the match type to Exact Match and the path to /aaa/one/bbb/one/ccc.

    • Rewrite: Set the rewrite type to Regex Rewrite, the pattern to one, and the replacement string to two.

    Example 2

    The original request path is /httpbin/(.*)/(.*). You want to remove the /httpbin prefix and swap the positions of the two captured path segments. We recommend the following configuration:

    • API and operation matching condition: Set the match type to Regex Match and the path to /httpbin/(.*)/(.*).

    • Rewrite: Set the rewrite type to Regex Rewrite, the pattern to /httpbin/(.*)/(.*), and the replacement string to /\2/\1. Here, \1 represents the first captured group, and \2 represents the second. This is similar to the $1 and $2 variables in Nginx.

    Example 3

    For a REST API that uses path-based versioning, you may want to remove the version segment from the path before forwarding the request to the backend. For example, if the original path is /basePath/version/order/get and the desired backend path is /basePath/order/get, we recommend the following configuration:

    • Use the API policy configuration.

    • Rewrite: Set the rewrite type to Regex Rewrite, the pattern to (/.*)/version(/.*), and the replacement string to \1\2. Here, \1 represents the first captured group and \2 represents the second, similar to $1 and $2 in Nginx.

    Note

    Regex rewrite is an advanced feature with a complex syntax, typically used for special cases.

  • Hostname rewrite

    Cloud-native API Gateway supports exact rewrite for the request hostname.

    For example, if the original request Host header is test.com but the backend service expects dev.com, you can set the rewrite hostname to dev.com in the rewrite policy.

Header modification policy

The header modification feature lets you change request headers before it is forwarded to the backend service, or in a response before it is returned to the client.

Procedure

On the Add Policy page, click the Edit Header card. In the Add Policy: Header Modification panel, configure the parameters.

Parameter

Description

Enable

Specifies whether to enable the header modification policy.

  • Enable: The gateway processes request and response headers based on this policy.

  • Disable: The gateway does not modify request or response headers.

Header Type

Select the header type to modify.

  • Request: Modifies the headers of the incoming client request.

  • Response: Modifies the headers of the outgoing response from the backend service.

Operation Type

Select the action to perform.

  • Add: Adds a header to the request or response.

    Note

    If the header already exists, the new value is appended to the existing value, separated by a comma (,).

  • Modify: Modifies a specified header in the request or response.

    Note

    • If the specified header does not exist, it is added with the specified Header Key and Header Value.

    • If the specified header exists, its value is overwritten.

  • Delete: Deletes a specified header from the request or response.

Header Key

The name of the request or response header.

Header Value

The value of the request or response header.

CORS policy

Cross-origin resource sharing (CORS) is a security feature that lets a web application server control cross-origin access, enabling secure data transfer. Cloud-native API Gateway supports CORS policies at the API and operation levels. You can specify which domains and request methods can access your resources.

Important

The CORS policy does not take effect for mock services. You must configure an actual backend service for testing.

Procedure

On the Add Policy page, click the CORS card. In the Add Policy: CORS panel, configure the parameters.

Parameter

Description

Enable

Turn on the Enable switch on the right.

  • Enable: Allows third-party domains to access your server resources from a browser.

  • Disable: Denies all cross-origin requests from browsers.

Allowed Origins

The origins that are allowed to access your server resources. The rules are as follows:

  • To allow all origins, enter *.

  • To allow origins from a specific root domain, enter a value such as *.example.com.

  • To allow multiple specific origins, enter each origin on a new line. The origin must start with http:// or https://.

Note

This parameter corresponds to the Access-Control-Allow-Origin header. If the Origin header of a client request matches an allowed origin, the Access-Control-Allow-Origin header in the response is set to the value of the request's Origin header.

Allowed Methods

The HTTP methods allowed for cross-origin access. Common methods include GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH.

Note

This parameter corresponds to the Access-Control-Allow-Methods header.

Trusted Request Headers

The allowed headers in a cross-origin request, in addition to the basic headers built into the browser. The rules are as follows:

  • To allow all request headers, enter *.

  • To allow multiple specific headers, enter each header on a new line.

Note

This parameter corresponds to the Access-Control-Allow-Headers header.

Trusted Response Headers

The response headers that can be accessed by browsers and JavaScript scripts. The rules are as follows:

  • To allow all response headers, enter *.

  • To allow multiple specific headers, enter each header on a new line.

Note

This parameter corresponds to the Access-Control-Expose-Headers header.

Allow to Carry Credentials

Specifies whether to allow credentials, such as cookies, in cross-origin requests.

Note

This parameter corresponds to the Access-Control-Allow-Credentials header.

Precheck Expiration Time

The maximum time, in seconds, that a preflight OPTIONS request's results can be cached by the browser.

Note

This parameter corresponds to the Access-Control-Max-Age header.

Traffic replication policy

The traffic replication policy lets you copy live application traffic to a specified service. This feature is useful for simulation testing and issue diagnosis, to help you evaluate application performance and troubleshoot failures.

Procedure

On the Add Policy page, click the Mirror Traffic card. In the Add Policy: Traffic Replication panel, configure the parameters.

Parameter

Description

Enable

Specifies whether to enable the traffic replication policy for the API or operation.

Destination Service

The destination service to which the replicated traffic is forwarded.

Note

The destination service must use the HTTP or HTTPS protocol.

Port

The port of the destination service. You can also select a dynamic port.

Note

Dynamic ports are suitable for services whose port number changes dynamically but are not supported for services with multiple ports. Do not select a dynamic port for multi-port services.

Traffic Mirror Percentage

The percentage of traffic to replicate. Valid values: 0 to 100.

Note

If you set this parameter to 50, 50% of the traffic for the API or operation is replicated to the destination service.

Timeout policy

Cloud-native API Gateway provides timeout settings at the API and operation levels. You can configure the maximum time that the gateway waits for a response from the backend service. If the gateway does not receive a response within the specified time, it returns an HTTP 504 (Gateway Timeout) status code to the client.

Procedure

On the Add Policy page, click the Timeout card. In the Add Policy: Timeout panel, configure the parameters.

Note

After you configure and enable the timeout policy, verify that the rule takes effect as expected for your service.

Parameter

Description

Enable

Specifies whether to enable the timeout policy.

  • Enable: The timeout policy for the API or operation takes effect.

  • Disable: The timeout policy for the API or operation is disabled.

Timeout Period

The timeout duration for the API or operation, in seconds.

Note

If you set this to 0 or disable the timeout policy, the gateway waits indefinitely for a response.

Retry policy

Cloud-native API Gateway provides retry settings at the API and operation levels to automatically retry failed requests. You can configure retry conditions, such as triggering a retry on a connection failure, an unavailable backend service, or a specific HTTP status code.

Retry conditions for APIs and operations

When the backend service returns a 5xx error, the Cloud-native API Gateway automatically retries the failed request according to the configured number of retries.

image

  • The retry conditions for the HTTP protocol are as follows:

    • 5xx: If the backend service returns any 5xx response, or if a connection is disconnected or reset, or if a read timeout occurs, Cloud-native API Gateway retries the failed request.

      Note

      The 5xx condition includes the connect-failure and refused-stream conditions.

    • reset: If a connection is disconnected or reset, or if a read timeout occurs, Cloud-native API Gateway retries the failed request.

    • connect-failure: If a request fails because a connection is disconnected, Cloud-native API Gateway retries the failed request.

    • refused-stream: If the backend service resets a stream with the REFUSED_STREAM error code, Cloud-native API Gateway retries the failed request.

    • retriable-status-codes: If the HTTP status code in the response from the backend service matches a retry status code that you specify, Cloud-native API Gateway retries the request.

      Note

      You can specify retry status codes only if you select retriable-status-codes as a retry condition.

  • The retry conditions for the gRPC protocol are as follows:

    • cancelled: If the gRPC status code in the response header from the backend gRPC service is cancelled, Cloud-native API Gateway retries the request.

    • deadline-exceeded: If the gRPC status code in the response header from the backend gRPC service is deadline-exceeded, Cloud-native API Gateway retries the request.

    • internal: If the gRPC status code in the response header from the backend gRPC service is internal, Cloud-native API Gateway retries the request.

    • resource-exhausted: If the gRPC status code in the response header from the backend gRPC service is resource-exhausted, Cloud-native API Gateway retries the request.

    • unavailable: If the gRPC status code in the response header from the backend gRPC service is unavailable, Cloud-native API Gateway retries the request.

Procedure

On the Add Policy page, click the Retry card. In the Add Policy: Retry panel, configure the parameters.

Note

After you configure and enable the retry policy, verify that the rule takes effect as expected for your service.

Parameter

Description

Enable

Specifies whether to enable the retry policy.

  • Enable: The retry policy for the API or operation takes effect.

  • Disable: The retry policy for the API or operation is disabled.

    When retries are disabled, the gateway has a default internal retry configuration. The default number of retries is 2, and the default retry conditions are connect-failure, refused-stream, unavailable, cancelled, or retriable-status-codes.

Retry Times

The maximum number of retries for a failed request. You can set this to an integer from 0 to 10. We recommend a value of 2 or less.

Setting this parameter to 0 disables retries.

Retry Condition

Select the conditions that trigger a retry. You can select multiple conditions.

Retry Status Code

Specifies the HTTP status codes that trigger a retry. You can configure multiple status codes.

Important

You can configure Retry Status Code only if you select retriable-status-codes for Retry Condition.

Plug-ins

  1. Click the Add Plug-in tab.

  2. In the Quick Navigation section, select a plug-in type or search for a plug-in by name, and then click the plug-in card:

    • If the plug-in is not installed, click Install and Configure in the pop-up dialog box. In the subsequent dialog box, configure the plug-in rules and enable it.

    • If the plug-in is already installed, configure the plug-in rules and enable it in the pop-up dialog box.

  3. Click OK to return to the attachment list for the API, where you can view the attachment and enablement status of plug-ins for the operations.

    The attachment list is a flowchart. It includes four blocks: Frontend API, Inbound Processing, Backend Service, and Outbound Processing. Arrows between the blocks show the request flow. Each processing block lists attached plug-ins, and you can add more by clicking the Enable Policy/Plug-in link.

Previous：Manage operationsNext：Configure an authentication policy