Cloud-native gateway FAQ

Does the MSE cloud-native gateway support IPv6?

Yes. The gateway uses a CLB or NLB instance for traffic ingress. To enable IPv6, bind an IPv6-enabled CLB or NLB instance on the Gateway Ingress tab of the Overview page.

Support for the x-real-ip request header

No, not by default. The x-real-ip request header is specific to NGINX. To use it, you must enable the gateway's http-real-ip plug-in. This plug-in extracts the client IP address based on your configuration and writes it to the x-real-ip request header.

Support for the x-forwarded-for request header

Yes. If an original request contains the x-forwarded-for request header, the gateway appends the IP address of the previous hop to the end of the header. If the original request does not have an x-forwarded-for header, the gateway creates the header and adds the client's IP address.

Upstream connect error or disconnect/reset header

This error occurs because the security group of the backend service does not allow the gateway to access the service port. Go to the Overview page of your gateway instance, click the Security Group Authorization tab, and then click Add Security Group Rule to add a new rule. The gateway forwards requests directly to the pod IP address in ACK. The security group rule must allow access to the port used by the pod.

Matching a domain name with a header

When you create a route, add a request header matching rule. Set the Header name to :authority and the Header value to a specific domain name.

Plug-in logs not visible

This may happen for the following reasons:

• By default, the plug-in only prints logs at the Info level or higher. Logs at the Trace or Debug level are not displayed.

• The plug-in failed to start, possibly due to a compilation issue. You can clear the default log query statement to view error logs from the plug-in's startup phase. Ensure you compile the plug-in correctly according to the development documentation and debug it locally using docker compose mode to confirm that it works before uploading it to the gateway.

Request failures due to large body size

This issue occurs because the gateway's connection buffer is too small. To resolve this, increase the buffer size:

• If the protocol is HTTP 1.x, adjust the DownstreamConnectionBufferLimits parameter in the console.

• If the protocol is HTTP/2, adjust the parameters DownstreamConnectionBufferLimits and InitialStreamWindowSize in the console.

Service source limits

• A single gateway instance can be associated with a maximum of three ACK clusters.

• A single gateway instance can be associated with a maximum of three Nacos instances.

Cannot select existing Nacos or ACK clusters

A cloud-native gateway can only be associated with Nacos instances or ACK clusters that are in the same VPC.

Support for custom HTTPS certificates

The cloud-native gateway does not host certificates directly. Instead, it pulls certificates from Alibaba Cloud Certificate Management Service. You can upload your own certificate to Certificate Management Service and then select it when you configure a domain name for your gateway.

Impact of parameter changes on traffic

• Changes to XffTrustedNum require a gateway restart to take effect.

• After you modify UpstreamIdleTimeout, the upstream connection will be disconnected and reconnected.

• After DownstreamIdleTime is modified, downstream connections will disconnect and reconnect.

CLB port 443 health check failures

If no HTTPS domain name is configured on the gateway, the gateway does not listen on port 443. As a result, the CLB health check for port 443 fails. To resolve this, configure an HTTPS domain name on the gateway. For more information, see Create a domain name. If you are using an Ingress, see Kubernetes Ingress.

Abnormal service health check status

To forward requests to a backend service, the gateway must be able to reach the backend service. An abnormal health check status is usually caused by one of the following issues:

• For private services within a VPC, check whether the security group of the backend service allows the gateway to access the required port. For more information, see Set security group rules.

• For public services, check whether the VPC has internet access. You can configure SNAT rules on an Internet NAT gateway to provide this access. For more information, see Use the SNAT feature of an Internet NAT gateway to access the internet.

• For HTTP-based health checks, ensure that the request path and domain name are correctly configured.

• For HTTP-based health checks, if the backend service's health check endpoint requires HTTPS, set the service to one-way TLS mode in the Policies configuration.

• For HTTP-based health checks, if the preceding steps do not resolve the issue, the problem might be that the health check interval is the same as the connection keep-alive time of the backend service. Try increasing the health check interval.

Determining request error causes

• Check if the response header contains the x-envoy-upstream-service-time header. Normally, if the response contains the x-envoy-upstream-service-time header, this indicates that the gateway has forwarded the request to the backend service for processing, and that subsequent request errors are highly related to the logic of the backend service itself.

• Check if the upstream_service_time field in the gateway's access log is empty. Normally, if the upstream_service_time field is not empty, it indicates that the gateway has forwarded the request to the backend service for processing. Subsequent request errors are highly related to the backend service's own logic.

Updated HTTPS certificates not taking effect

This issue usually occurs if an HTTPS certificate is also configured on a component upstream from the gateway, such as a CLB, DCDN, WAF, or Anti-DDoS Proxy instance. Check whether the HTTPS certificate has also been updated on these nodes. As a best practice, manage HTTPS certificates in a single location. For example, if your gateway is behind a DCDN or WAF instance, configure HTTPS only on the DCDN or WAF instance and use HTTP for back-to-origin traffic to the gateway.

Parameter setting changes not taking effect

This issue typically occurs if you are using MSE Ingress. The MseIngressConfig resource contains related configuration options. MSE Ingress automatically synchronizes these settings to the MSE gateway console. Changes made directly in the console may be overwritten by this synchronization. Manage these settings exclusively through the MseIngressConfig resource.

How is route priority determined?

The order of routes on the Route Settings page of a gateway instance represents their matching priority, from highest to lowest. The matching priority is determined by the domain name and the route rule. For domain name matching, an exact domain name has a higher priority than a wildcard domain name. For example, test.example.com has a higher priority than *.example.com. For routes that use the same domain name, the Path matching priority is as follows: Exact match > Prefix match > Regular expression match. For routes that use the same domain name and Path, the rule with more matching conditions has a higher priority than the rule with fewer matching conditions. Matching conditions include Header and Query conditions.

HTTPS request failures with DCDN

This issue usually occurs because DCDN does not include the SNI extension in its back-to-origin requests to the gateway. To fix this, enable SNI in your DCDN's back-to-origin configuration.

HTTPS request failures with WAF

This issue usually occurs because WAF does not include the SNI extension in its back-to-origin requests to the gateway. If you added your service to WAF by using the CNAME method, you must modify its forwarding configuration to Enable Origin SNI in the Forwarding Settings.

WebSocket support

Yes. Support for the WebSocket protocol is enabled by default.

gRPC support

Yes. gRPC uses the HTTP/2 protocol for transmission. Make sure that EnableHttp2 = true in the gateway's Parameters.

Gzip decompression support

Yes. Make sure that EnableGzip = true in the gateway's Parameters. The supported compression algorithms are Gzip and Brotli. You can configure the algorithm by using the ZipAlgorithm parameter. The default value is Gzip.

Preserving header case

Yes. Make sure that PreserveHeaderFormat = true is set in the gateway Parameters. This parameter is effective only for HTTP 1.0 or 1.1. According to the specification, the HTTP/2 protocol requires all request/response headers to be in lowercase.

HTTP/3 support

Yes. Make sure that EnableHttp3 = true is set in the gateway's Parameters.

Custom listener ports

Yes. The cloud-native gateway supports HTTP (port 80) and HTTPS (port 443). In the CLB console, add a new listener for your custom port (for example, TCP 8080) and forward its traffic to the same backend vServer group used by port 80.

Headers converted to lowercase

The gateway converts all request/response headers to lowercase by default. To preserve the original case, set PreserveHeaderFormat = true in the gateway's Parameters.

Request failures for DNS domain services

Because a gateway cannot access external networks by default, you must configure an Internet NAT gateway with SNAT rules to allow access to public domains.

HTTP 400 Bad Request errors

This error usually has two possible causes:

• The client sent a protocol error. Check the gateway's access log for response_flags = DPE.

• The 400 error is returned by the backend service. Check the access log of the gateway. If the response_flags field is empty and the upstream_host field has a value, this indicates that the backend service returned the 400 error. The value of the upstream_host field is the IP address of the specific backend service to which the gateway forwarded the request.

Use the AI Diagnostics feature for an initial analysis.

HTTP 401 Unauthorized errors

This error usually has two possible causes:

• The gateway returned the error, indicating missing credentials. Check whether you have enabled authentication and authorization or a WebAssembly plug-in.

• The 401 error is returned by the backend service. Check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, this indicates that the error is from the backend service. The value of the upstream_host field is the IP address of the specific backend service to which the gateway forwarded the request.

Use the AI Diagnostics feature for an initial analysis.

HTTP 403 Forbidden errors

This error usually has two possible causes:

1. The gateway returned the error, indicating a lack of permissions. Check whether you have enabled an IP blacklist/whitelist, authentication and authorization, or a WebAssembly plug-in.

2. The 403 error is returned by the backend service. Check the access log of the gateway. If the log shows that response_flags is empty and upstream_host has a value, this indicates that the backend service returned the 403 error. The specific backend IP address to which the gateway forwarded the request is the value of upstream_host.

Use the AI Diagnostics feature for an initial analysis.

HTTP 404 Not Found errors

This error usually has two possible causes:

• The gateway is missing a routing rule. Check the access log of the gateway. The flag response_flags = NR indicates that no route was found.

• This is a 404 error returned by the backend service. Check the access log of the gateway. If the response_flags field is empty and the upstream_host field has a value, this means the 404 error was returned by the backend service at the IP address specified in upstream_host.

Use the AI Diagnostics feature for an initial analysis.

HTTP 405 Method Not Allowed errors

This status code is returned by WAF when WAF protection is enabled and the request matches a protection rule.

HTTP 413 Payload Too Large errors

This error usually has two possible causes:

• The request size exceeds the gateway's connection buffer size. You need to increase the value of DownstreamConnectionBufferLimits in Parameters.

• This is a 413 error returned by the backend service. Check the access log of the gateway. If the response_flags field in the log is empty and the upstream_host field has a value, this indicates that the 413 error was returned by the backend service. The value of upstream_host is the IP address of the specific backend service to which the gateway forwarded the request.

Use the AI Diagnostics feature for an initial analysis.

HTTP 429 Too Many Requests errors

A gateway throttling rule is triggered. The access log for the gateway shows response_flags = RL. Check the gateway throttling rule.

Use the AI Diagnostics feature for an initial analysis.

HTTP 502 Bad Gateway errors

This error usually has two possible causes:

• A protocol error was returned by the backend service. In the gateway's access log, this error is indicated by response_flags = UPE. The most common cause is that the header returned by the backend service contains a duplicate Transfer-Encoding field. Please check the backend service.

• A 502 error is returned by the backend service. To identify the source, check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, the 502 error originated from the backend service. The upstream_host field contains the IP address of this backend service.

Use the AI Diagnostics feature for an initial analysis.

HTTP 503 Service Unavailable errors

This error can be caused by several issues:

• The destination service specified in the gateway's route rule has no healthy IP addresses. In the gateway's access log, response_flags = UH.

• The connection is closed by the backend service when the gateway forwards a request. In the gateway's access log, response_flags = UC usually indicates that the idle timeout of the backend service is shorter than the gateway's UpstreamIdleTimeout. Reduce the UpstreamIdleTimeout value in the gateway's Parameters.

• The gateway cannot connect to the backend service IP address. If the access log shows that response_flags = UF or response_flags = URX, the cause is typically that the security group of the backend service is blocking access from the gateway. Verify that the security group of the backend service allows the gateway to access the required port. For more information, see Set security group rules.

• The gateway has no corresponding backend service. Check the access log of the gateway. The log shows response_flags = NC, which is usually caused by the following reasons:

  • The corresponding service has been deleted.

  • If the backend service has multiple ports, you must select a fixed port, not a dynamic one, when you configure the destination service in the route.

  • The backend service was configured with a fixed port, but the service's port has since changed.

• A 503 error is returned by the backend service if the response_flags field in the logs is empty and the upstream_host field has a value. In this case, the upstream_host field contains the IP address of the specific backend service to which the gateway forwarded the request.

Use the AI Diagnostics feature for an initial analysis.

Response_code is 0 in access logs

A response_code of 0 in the logs indicates that the client did not receive a response code.

This error usually has two possible causes:

• The client closed the connection prematurely. This can happen, for example, if the client is on a weak mobile network or if the backend response time is too long. In the logs, a response_flags value of "DC" confirms this cause.

• An HTTPS request was sent without the Server Name Indication (SNI) extension (indicated by an empty requested_server_name field in the access log), which is required to identify the destination domain during the TLS handshake. The error can also occur if no HTTPS certificate is configured for the wildcard domain (*).

Use the AI Diagnostics feature for an initial analysis.