Create a Cloud Native API Gateway-API Gateway(API Gateway)-阿里云帮助中心

A Cloud-native API Gateway instance provides service exposure, traffic management, security, and API lifecycle management. This topic explains how to create one.

Basic configuration

First-time authorization

System policies:

AliyunServiceRoleForNativeApiGw: Allows access to other cloud services such as ACK, VPC, SLB, and MSE.

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

Log on to the Cloud-native API Gateway console. In the left-side 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. For more information about billing, see Billing overview.
- pay-as-you-go: You are charged hourly. Usage for less than one hour is billed as a full hour. Bills are settled hourly.
- subscription: You are billed based on a monthly or yearly (12-month) commitment.
Region: Select the region where you want to deploy the gateway instance. This region must be the same as your backend service's region. You cannot change this setting after the instance is created.
Gateway Name: Enter a custom name for the gateway. We recommend using a name that indicates the environment and business domain, such as test or order-prod. The maximum length is 64 characters.

GatewaySpec: Select an instance specification based on a capacity assessment of your business needs.

Capacity thresholds for different instance specifications

The following table lists the capacity thresholds for different instance specifications. To ensure your service-level agreement (SLA) is met, keep your gateway's capacity metrics below the warning threshold. For critical services, we recommend keeping capacity metrics below the security threshold to achieve higher stability.

Security threshold: Operating below this threshold allows the gateway to maintain high throughput and low latency even if traffic suddenly doubles.
Warning threshold: If this threshold is exceeded, gateway latency may increase and create stability risks during traffic surges.
Single-node gateways do not provide an SLA and are intended for testing purposes only. Ensure you use an instance specification with multiple nodes for production environments.

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 one. You can use resource groups to manage permissions, deployments, and monitoring for a group of resources instead of managing each resource individually. To create a new resource group, click Create Resource Group.
Network Type: Select Internet, Private Network, or Public + Private.
- Internet: When the gateway is accessed over the public network, you are charged for outbound traffic. This traffic is billed through Cloud Data Transfer (CDT) and uses the BGP (Multi-ISP) service. For more information, see Public network traffic.
- Private Network: No data transfer fees are charged for traffic over the private network.
- Public + Private: When the gateway is accessed over the public network, you are charged for outbound traffic. This traffic is billed through Cloud Data Transfer (CDT) and uses the BGP (Multi-ISP) service. No data transfer fees are charged for traffic over the private network.
VPC: Select the VPC for the gateway instance. The gateway's VPC must be the same as your service's VPC.
Select Zone: Select Auto-assign or Manual Select.
- Auto-assign: Select the vSwitches for the gateway nodes. The system automatically deploys the nodes across two zones.
- Manual Select: Manually select the Zone and vSwitches for the gateway nodes.

After you complete the configuration, click Buy Now. On the Confirm Order page, review the configuration details and click Open now.

Instance creation takes 1 to 5 minutes.
On the Cloud-native API Gateway Instance page, check the status of the gateway instance you created. A status of Running indicates that the gateway instance was created successfully.

Advanced features

When you create a gateway instance, you can configure advanced features to monitor and analyze log data using Simple Log Service (SLS), or compress requests and responses to reduce traffic using Gzip hardware acceleration. Gzip hardware acceleration can only be enabled when you create a gateway instance and cannot be enabled later.

Enable Gzip hardware acceleration

Gzip hardware acceleration is a technology that uses dedicated hardware to accelerate data compression and decompression. By offloading Gzip compression and decompression tasks from the CPU to dedicated hardware, this feature significantly improves processing efficiency and reduces CPU load.

Procedure

On the Cloud-native API Gateway purchase page, after completing the basic configurations, configure the following parameters and click Open now:
- Region: Gzip hardware acceleration is supported in the following regions: China (Hangzhou), China (Beijing), China (Shanghai), China (Shenzhen), China (Ulanqab), China (Hong Kong), and Singapore.
  
  This feature may not be available in all zones within the supported regions. For the latest information, refer to the product purchase page.
- GatewaySpec: Select apigw.medium.x1 or a higher specification.
- Gzip Hardware Acceleration: Select this option to enable Gzip hardware acceleration.
  
  For Instance Specification, select apigw.medium.x1 (Max Client Connections: 384,000, Max New HTTPS Connections/sec: 12,800, Max Short-lived Connection QPS: 28,000, Max Long-lived Connection QPS: 35,000, and SLA: 99.99%). For Resource Group, select Default Resource Group. For Network Access Type, select Public Network. For VPC, select the target VPC. For Zone Selection, click Manual Select, select China (Hangzhou) Zone J and China (Hangzhou) Zone K (both support Gzip hardware acceleration), and then select a VSwitch for each zone.
After the instance is created, click the ID or name of the target instance. In the left-side navigation pane, click Parameters. In the Gateway Engine Parameters section, edit the EnableGzipHardwareAccelerate parameter.

If you did not select Enable Gzip hardware acceleration during purchase, you cannot enable this parameter.
After this feature is enabled, clients must be able to process Gzip-compressed data. For supported clients, add the Accept-Encoding: gzip header to requests.

Performance reference

Traffic savings from Gzip compression

When using Gzip compression, the compression ratio (the ratio of compressed data size to the original data size) depends heavily on the data itself. A lower compression ratio indicates more effective compression, while a higher compression ratio indicates less effective compression.

Typically, Gzip compression is more effective on data with repetitive patterns or structures, such as text files containing common letters, words, and punctuation, resulting in a lower compression ratio. Conversely, for data with high randomness and entropy, such as images, videos, and already compressed files, compression is less effective because of low internal repetition, resulting in a higher compression ratio.

The compression ratio varies significantly among customers, depending on their business data. Statistics from instances with Gzip enabled in core regions show that most instances achieve a compression ratio between 10% and 50%. This means that after enabling Gzip, these users can save over 50% on traffic on average.

Resource savings from hardware acceleration

When you enable Gzip hardware acceleration, the gateway offloads compression to dedicated hardware, saving CPU resources. The following stress test data compares the CPU consumption between a single-node instance with Gzip hardware acceleration and a 4-node instance that uses software-based Gzip, both handling the same QPS.

For example, the test data is a JSON text file of approximately 120 KB.

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

The data in the table shows that the CPU consumption for Gzip hardware acceleration enabled/single node is basically the same as that for Software Gzip/4 nodes. This means that a workload that originally required 4 nodes can be handled by only 1 node after Gzip hardware acceleration is enabled, saving approximately 75% of instance resources.

Enable gateway log delivery

To collect, store, and analyze gateway logs, enable Simple Log Service (SLS) when you create a gateway instance. This provides log analysis and dashboard monitoring.

While completing the basic configurations, select Use Simple Log Service (SLS). The system then activates SLS and enables the gateway log delivery feature.

After log delivery is enabled, you can view gateway logs under 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 configure routing rules or policies for different API types.
You can create a service to add a backend service to your instance. The instance then centrally manages the endpoints of your backend services.
To configure gateway routing for external access to your internal services, refer to Use an HTTP API to access applications in Container Service for Kubernetes (ACK).
If you encounter issues while using Cloud-native API Gateway, refer to the FAQ.