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

A Cloud-native API Gateway instance provides service exposure, traffic management, security protection, and API lifecycle management.

Basic configuration

First-time authorization

System permission policies:

AliyunServiceRoleForNativeApiGw: Allows access to other Alibaba Cloud services such as Container Service for Kubernetes (ACK), Virtual Private Cloud (VPC), Server Load Balancer (SLB), and Microservices Engine (MSE).

AliyunServiceRolePolicyForNativeApiGwInvokeFC: Allows access to the Function Compute (FC) service.

Log on to the Cloud-native API Gateway console. In the left navigation pane, click Instance. On the Instances 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. See billing overview.
- Pay-as-you-go: Billed hourly. Usage under one hour is rounded up to a full hour, and bills are settled every hour.
- Subscription: Billed monthly. A yearly subscription equals 12 months.
Region: Select the region where your backend services reside. The region cannot be changed after creation.
Gateway Name: Enter a custom name (up to 64 characters). Use a name that combines environment and business domain, such as test or order-prod.

GatewaySpec: Perform a capacity assessment and select a node specification based on your business requirements.

Capacity thresholds for different node specifications

Keep capacity metrics below the warning threshold to maintain SLA guarantees. For core business workloads, stay below the secure threshold for higher stability.

Secure threshold: The gateway maintains high throughput and low latency even if traffic doubles.
Warning threshold: Above this level, the gateway may experience higher latency and stability risks during traffic spikes.
Single-node gateways have no SLA guarantee and are for testing only. Production workloads require multi-node specifications.

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%

Resource Group: Select an existing resource group or use the default. Resource groups let you manage resources, permissions, and monitoring as a unit. To create one, click Create Resource Group.
Network Type: You can select Internet, Private Network, or Public + private network.
- Internet: Public network access incurs traffic fees billed through Cloud Data Transfer (CDT) on the BGP (Multi-ISP) model. Public network traffic.
- Private Network: No traffic fees are incurred for access over the private network.
- Public + private network: Public access incurs CDT traffic fees (BGP Multi-ISP model). Private access is free.
VPC: Select the VPC where the gateway will run. The gateway and backend services must share the same VPC.
Availability zone selection: You can select Auto-assign or Manual select.
- Auto-assign: Select a vSwitches for the gateway nodes. The system deploys nodes across two availability zones automatically.
- Manual select: Manually select the Availability zone and vSwitches for the gateway nodes.

Click Buy Now, review the configuration on the Confirm Order page, and click Open now.

Gateway instance creation takes 1 to 5 minutes.
On the Instance page, verify that the instance status is Running.

Advanced features

Configure advanced features during instance creation to enable log analysis or Gzip compression. Gzip hardware acceleration can only be enabled at creation time. Log service can be enabled at any time.

Enable Gzip hardware acceleration

Gzip hardware acceleration offloads data compression and decompression to dedicated hardware, reducing CPU load and improving processing efficiency.

Steps

On the purchase page, complete the Basic configuration and set the following additional parameters. Then, click Open now.
- Region: Gzip hardware acceleration is available in the following regions: China (Hangzhou), China (Beijing), China (Shanghai), China (Shenzhen), China (Ulanqab), China (Hong Kong), and Singapore.
  
  Within these supported regions, some availability zones may not support this feature. Availability is subject to the options shown on the product purchase page.
- GatewaySpec: Select a specification of apigw.medium.x1 or higher.
- Gzip hardware acceleration: Select the checkbox to enable Gzip hardware acceleration.
After the instance is created, click its name or ID to go to the details page. In the left navigation pane, click Parameters. In the Gateway Engine Parameters section, edit the EnableGzipHardwareAccelerate parameter.

If you did not select the Gzip hardware acceleration checkbox during purchase, you cannot enable this setting.
After enabling this feature, clients must be able to process Gzip-compressed data and must include the Accept-Encoding: gzip header in their requests.

Performance reference

Gzip traffic savings

The Gzip compression ratio (compressed size / original size) depends on data characteristics. Lower ratios mean better compression.

Text with repetitive patterns (letters, words, punctuation) compresses well, yielding low ratios. High-entropy data (images, videos, already-compressed files) yields high ratios with limited benefit.

Based on production data from instances with Gzip enabled in core regions, most achieve a 10%–50% compression ratio, saving over 50% of traffic on average.

Resource savings with hardware acceleration

The following stress test compares CPU usage between a single-node instance with hardware Gzip and a four-node instance with software Gzip at the same QPS.

In this example, the data being compressed is a JSON text file of approximately 120 KB.

QPS	CPU usage (Hardware Gzip)	CPU usage (Software Gzip)
2,000	9%	11%
5,000	26%	28%
10,000	56%	56%
13,000	69%	72%

The CPU usage of Enabled Gzip hardware acceleration/single node is comparable to Software Gzip/4 nodes, saving approximately 75% of instance resources.

Enable gateway log delivery

Enable Simple Log Service (SLS) during instance creation to collect, store, and analyze gateway logs.

While completing the Basic configuration, select the Use Simple Log Service (SLS) checkbox. The system automatically provisions SLS and enables the gateway log delivery feature for you.

After you enable log delivery, you can view the gateway logs by navigating to Observation and Analysis > Logs.

Log field descriptions

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 flexibly configure routing rules and policies for different API types.
You can create a service to add backend services to the gateway, allowing it to discover and centrally manage their endpoints.
Expose applications in Container Service through an HTTP API.
FAQ.