Create a Cloud Native API Gateway - API Gateway - Alibaba Cloud Documentation Center

Prerequisites

Service-linked role authorization — The first time you activate Cloud-native API Gateway, you must grant the following system access policies:
- AliyunServiceRoleForNativeApiGw: Grants access to other Alibaba Cloud services, such as ACK, VPC, SLB, and MSE.
- AliyunServiceRolePolicyForNativeApiGwInvokeFC: Grants access to Function Compute (FC).
Region — Create the gateway in the same region as your backend services.
VPC and vSwitches — An existing VPC that runs your services, and a vSwitch for the gateway nodes. The gateway must run in the same VPC as your services.

Important

You cannot change the region after the instance is created. Gzip hardware acceleration must be selected on the purchase page, and cannot be made available on an existing instance.

Basic configuration

Log on to the Cloud-native API Gateway console. In the left-side navigation pane, choose Instance. On the instance page, click Instance Creation.
On the Cloud-native API Gateway purchase page, configure the following parameters:
- Product Type: Select Pay-as-you-go or Subscription. The pricing details of each billing method are described in Billing overview.
  - Pay-as-you-go — You are charged by the hour. Usage of less than one hour is billed as one full hour. Bills are settled once per hour.
  - Subscription — You are charged by the month. A one-year subscription is billed as 12 months.
- Region: Select the region in which the gateway runs. For the region constraints, see Prerequisites.
- Gateway Name: Enter a custom name for the gateway. As a best practice, name the gateway after the environment, or after the environment and the business domain, such as test or order-prod. The name can be up to 64 characters in length.
- GatewaySpec: Perform a capacity assessment based on your business requirements, and then select a node specification. For the thresholds of each specification, see Capacity thresholds for different node specifications.
  - A gateway that runs on a single node provides no SLA. For production workloads, select a specification that deploys multiple nodes.
  - To use Gzip hardware acceleration, select apigw.medium.x1 or a higher specification.
- Resource Group: Select an existing resource group or the default resource group. Resource groups let you classify and group the resources of your Alibaba Cloud account, so that you can handle permission management, resource deployment, and resource monitoring for a whole group instead of for each resource. To create a resource group, click Create Resource Group.
- Network Type: Select Internet, Private Network, or Public + Private. If clients reach the gateway only over the private network, select Private to avoid public network traffic fees.
  - Internet — When the gateway is accessed over the public network, public network traffic fees apply. Public network traffic is billed and invoiced through Cloud Data Transfer (CDT) in BGP (multi-line) mode, as described in Public network traffic.
  - Private Network — No traffic fees apply to private network access.
  - Public + Private — When the gateway is accessed over the public network, public network traffic fees apply. Public network traffic is billed and invoiced through Cloud Data Transfer (CDT) in BGP (multi-line) mode. No traffic fees apply to private network access.
- VPC: Select the VPC in which the gateway instance runs. The VPC of the gateway must be the same as the VPC of your services.
- Zone Selection: Select Auto-assign or Manual Select.
  - Auto-assign — Select the vSwitches for the gateway nodes. The system automatically assigns two zones for the gateway nodes.
  - Manual Select — Manually select the Zone and vSwitches for the gateway nodes. Select this option when the gateway nodes must run in specific zones, such as the zones that support Gzip hardware acceleration.
Click Buy Now. On the Confirm Order page, check the configuration details of the Cloud-native API Gateway instance, and then click Open now.
Note
Creating a gateway instance takes 1 to 5 minutes.
On the Cloud-native API Gateway Instance page, check the status of the gateway instance that you created. A status of Running indicates that the gateway is created.

Capacity thresholds for different node specifications

The following table lists the capacity thresholds for each GatewaySpec of Cloud-native API Gateway. When the capacity metrics of a gateway stay below the warning threshold, the gateway is covered by the full SLA. For core business, keep the capacity metrics below the secure threshold to achieve better stability.

Secure threshold — The gateway maintains high throughput and low latency even when traffic suddenly doubles.
Warning threshold — When capacity rises above the warning threshold, gateway latency may increase, and stability risks may occur during traffic spikes.
Single-node gateways — A gateway that runs on a single node provides no SLA and is intended for test scenarios only. For production workloads, use a GatewaySpec that deploys multiple nodes.

Gateway specification	Client connections		New HTTPS connections		CPU utilization		Memory usage
Gateway specification	Secure threshold	Warning threshold	Secure threshold	Warning threshold	Secure threshold	Warning threshold	Secure threshold	Warning threshold
`apigw.dev.x1`	12,000	24,000	400	800	30%	60%	75%	75%
`apigw.small.x1`	24,000	48,000	800	1,600	30%	60%	75%	75%
`apigw.small.x2`	48,000	96,000	1,600	3,200	30%	60%	75%	75%
`apigw.small.x4`	96,000	192,000	3,200	6,400	30%	60%	75%	75%
`apigw.medium.x1`	192,000	384,000	6,400	12,800	30%	60%	75%	75%
`apigw.medium.x2`	384,000	768,000	12,800	25,600	30%	60%	75%	75%
`apigw.medium.x3`	576,000	1,152,000	19,200	38,400	30%	60%	75%	75%
`apigw.large.x1`	768,000	1,536,000	25,600	51,200	30%	60%	75%	75%
`apigw.large.x2`	1,536,000	3,072,000	51,200	102,400	30%	60%	75%	75%
`apigw.large.x3`	2,304,000	4,608,000	76,800	153,600	30%	60%	75%	75%
`apigw.large.x4`	3,072,000	6,144,000	102,400	204,800	30%	60%	75%	75%

Advanced features

When you create a Cloud-native API Gateway instance, use the following configurations to monitor and analyze log data, or to compress requests and responses and reduce gateway traffic. Gzip hardware acceleration is available only if you select it on the purchase page. Simple Log Service (SLS) has no such restriction.

Enable Gzip hardware acceleration

Gzip hardware acceleration uses dedicated hardware to compress and decompress data quickly. Offloading Gzip decompression from the CPU to dedicated hardware improves processing efficiency and reduces CPU load.

Enabling the feature has two stages. The option that you select on the purchase page determines whether the instance can use Gzip hardware acceleration, and you cannot add the capability to an existing instance. After the instance is created, you control the feature with the EnableGzipHardwareAccelerate parameter.

To configure Gzip hardware acceleration on the purchase page

On the Cloud-native API Gateway purchase page, complete the basic configuration and the following configurations, and then click Open now:
- Region: Gzip hardware acceleration is available in China (Hangzhou), China (Beijing), China (Shanghai), China (Shenzhen), China (Ulanqab), China (Hong Kong), and Singapore.
  Note
  Some zones in the supported regions do not support this feature. The purchase page shows the zones that are actually available.
- GatewaySpec: Select apigw.medium.x1 or a higher specification.
- Gzip Hardware Acceleration: Select this option to enable Gzip hardware acceleration.
If Gzip Hardware Acceleration is unavailable on the purchase page, check whether the GatewaySpec is apigw.medium.x1 or higher and whether the selected zones support the feature.

Example

The following example shows a purchase-page configuration that meets the requirements of Gzip hardware acceleration. For the capacity of each specification, see Capacity thresholds for different node specifications.

For GatewaySpec, select apigw.medium.x1. For Resource Group, select Default Resource Group. For Network Type, select Internet. For VPC, select the target VPC. For Zone Selection, click Manual Select, select Hangzhou Zone J and Hangzhou Zone K (both support Gzip hardware acceleration), and then select a vSwitch for each zone.

To turn on Gzip hardware acceleration after the instance is created

After the instance is created, click the ID or name of the target instance. In the left-side navigation pane, choose Parameters. In the Gateway Engine Parameters section, edit the EnableGzipHardwareAccelerate parameter.
Important
If you did not select Gzip Hardware Acceleration when you purchased the instance, you cannot enable this parameter.
Verify that the current value of EnableGzipHardwareAccelerate on the Parameters page is the value that you set.
After the feature is enabled, the client must be able to process Gzip-compressed data. For clients that support Gzip, add the Accept-Encoding: gzip request header.

Enable gateway log delivery

To collect, store, and analyze gateway runtime logs, activate Simple Log Service (SLS) when you create a gateway instance. You can then use SLS for log analysis and dashboard monitoring.

While you complete the basic configuration, select Use Simple Log Service (SLS). The system activates Simple Log Service (SLS) and enables gateway log delivery.
After log delivery is enabled, verify that gateway logs appear in Observation and Analysis > Logs.
For the meaning of each log field, see Gateway log fields.

Reference

Gzip performance reference

How much traffic does Gzip compression save? With Gzip compression, the compression ratio, which is the size of the compressed data divided by the size of the original data, depends largely on the data itself. A lower compression ratio means better compression, and a higher compression ratio means worse compression.

In general, Gzip compresses data that contains many repeated patterns or structures, such as the letters, words, and punctuation in text, more effectively and produces a lower compression ratio. For data with high randomness and high entropy, such as images, videos, and compressed files, internal repetition is low, so the compression ratio is usually higher and compression is less effective.

Compression ratios differ significantly between customers because their business data differs. Statistics for instances with Gzip enabled in core regions show that most instances have a compression ratio between 10% and 50%. On average, these users save more than 50% of their traffic after they enable Gzip.

The following figure shows the compression ratios measured on instances with Gzip enabled in core regions.

Compression ratios measured on Cloud-native API Gateway instances with Gzip enabled in core regions

How many instance resources does hardware acceleration save when Gzip is already enabled? After Gzip hardware acceleration is enabled, the gateway compresses data on dedicated hardware and saves CPU resources. The following stress test data compares CPU usage between a single-node instance with Gzip hardware acceleration and a four-node instance that uses software-based Gzip, when both serve the same QPS.

For example, the compressed data is a JSON text file of about 120 KB:

QPS	CPU usage: hardware-accelerated Gzip/apigw.medium.x1/single node	CPU usage: software Gzip/apigw.medium.x1/4 nodes
2,000	9%	11%
5,000	26%	28%
10,000	56%	56%
13,000	69%	72%

The table shows that CPU usage for Gzip hardware acceleration/single node is roughly the same as CPU usage for software Gzip/4 nodes. A workload that previously required 4 nodes runs on 1 node after you enable Gzip hardware acceleration, which saves about 75% of instance resources.

Gateway log fields

The following table describes the fields in the logs that Cloud-native API Gateway delivers to Simple Log Service (SLS).

Field	Type	Description
__time__	long	The time when the log was generated.
cluster_id	string	The ID of the AI Gateway instance.
ai_log	json	A JSON object that contains log fields for Model API, Agent API, and MCP API. This field is empty for other API types. api: The name of the AI API. cache_status: Indicates whether a request hit the cache when content caching is enabled for a Model API. consumer: The identity of the consumer. This field is populated when consumer authentication is enabled. fallback_from: The route from which the request fell back. This field is populated when a fallback policy is enabled for a Model API. input_token: The number of input tokens in the LLM request. llm_first_token_duration: The time to first token (TTFT) for the LLM request. llm_service_duration: The end-to-end response time for the LLM request. model: The name of the model used in the LLM request. output_token: The number of output tokens in the LLM response. response_type: The response type of the LLM request, such as streaming or non-streaming. safecheck_status: The Content Moderation result for the LLM request. token_ratelimit_status: Indicates whether the request was blocked by token-based rate limiting.
authority	string	The value of the Host header in the request.
bytes_received	long	The size of the request body in bytes, excluding the header.
bytes_sent	long	The size of the response body in bytes, excluding the header.
downstream_local_address	string	The address of the gateway pod.
downstream_remote_address	string	The address of the client that connects to the gateway.
duration	long	The total request processing time in milliseconds, measured from when the gateway receives the first byte from the client until it sends the last byte of the response.
method	string	The HTTP method.
path	string	The path in the HTTP request.
protocol	string	The HTTP protocol version.
request_duration	long	The time in milliseconds from when the gateway receives the first byte of the request from the client until it receives the last byte.
request_id	string	A unique ID that the gateway generates for each request. This ID is included in the `x-request-id` header. You can use this field to log and troubleshoot requests.
requested_server_name	string	The server name used for the SSL connection.
response_code_details	string	Additional context for the response code. For example, `via_upstream` indicates the backend service returned the response code, and `route_not_found` indicates that the gateway could not find a matching route.
response_tx_duration	long	The time in milliseconds from when the gateway receives the first byte from the upstream service to when it sends the last byte to the client.
route_name	string	The route name.
start_time	string	The start time of the request. The time is in UTC.
trace_id	string	The trace ID.
upstream_cluster	string	The upstream cluster.
upstream_host	string	The IP address of the upstream host.
upstream_local_address	string	The local address used to connect to the upstream service.
upstream_service_time	long	The request processing time in milliseconds for the upstream service. This duration includes network latency and the service's own processing time.
upstream_transport_failure_reason	string	The reason for the upstream connection failure.
user_agent	string	The value of the User-Agent header in the request.
x_forwarded_for	string	The value of the `x-forwarded-for` header, which typically contains the client's real IP address.

Next steps

Cloud-native API Gateway supports multiple API types, including REST API, HTTP API, and WebSocket API. You can configure routing rules or policies for each API type.
When you create a service, the backend service is added to the gateway, and the gateway obtains and manages the endpoints of the backend service in one place.
To expose internal services externally by configuring gateway routes, see Use an HTTP API to access applications in Container Service for Kubernetes (ACK).
If you encounter problems when you use Cloud-native API Gateway, see the FAQ.