Migrate NGINX configurations to an ASM gateway - Alibaba Cloud Service Mesh

NGINX Ingress and Service Mesh (ASM) gateways handle traffic configuration differently. When you migrate from NGINX Ingress to an ASM gateway, you need to map each NGINX ConfigMap parameter to the corresponding Istio or Envoy configuration. This document provides a complete parameter mapping reference with before-and-after configuration examples.

Prerequisites

Before you begin, make sure that you have:

A running ASM instance with an ASM gateway deployed
Basic familiarity with Istio resources (Gateway, DestinationRule, VirtualService)
Access to the ASM console

NGINX vs. ASM architecture differences

ASM gateways run on Envoy, which differs from NGINX in several ways:

Aspect	NGINX	ASM (Envoy)
Connection scope	Per worker process	Per destination host
Configuration model	Single ConfigMap	Distributed across `Gateway`, `DestinationRule`, and ASM console
Header validation	Silently ignores invalid headers (configurable)	Rejects invalid headers with `400 Bad Request` by default
Request body limits	Enforced via `proxy-body-size`	Not enforced; use chunked transfer encoding
Server identity	`Server: nginx` (configurable)	`Server: istio-envoy` (default)

Parameter mapping reference

The following table maps each NGINX parameter to its ASM equivalent. Click the linked examples for complete YAML configurations.

NGINX parameter	Status	ASM equivalent	Type / Default	Migration notes
`allow-backend-server-header`	Supported	Default behavior	bool / `true`	No action required. ASM gateways allow backend `Server` headers by default.
`allow-snippet-annotations`	Partial	IstioGateway YAML	bool / N/A	No direct parameter. Edit the IstioGateway YAML to customize gateway behavior.
`compute-full-forwarded-for`	Supported	Envoy `use_remote_address`	bool / `true`	Controlled by Envoy's `use_remote_address` setting. See Configuring Gateway Network Topology.
`enable-underscores-in-headers`	Supported	Envoy `headers_with_underscores_action`	bool / `true`	No action required if you use the default.
`forwarded-for-header`	Not supported	Fixed: `X-Forwarded-For`	string / `X-Forwarded-For`	ASM gateways always use `X-Forwarded-For`. Custom forwarded-for headers are not supported.
`generate-request-id`	Supported	Envoy `generate_request_id`	bool / `true`	To change this value, use an ASM plug-in.
`ignore-invalid-headers`	Partial	Envoy Header Validator	N/A	Without a Header Validator configured, Envoy rejects invalid headers with a `400 Bad Request` response. Note Whether underscores (`_`) are valid in header names depends on the `headers_with_underscores_action` setting.
`keep-alive-requests`	Supported	`connectionPool.http.maxRequestsPerConnection`	int32	Configure in a `DestinationRule`. See the connection pool settings example below.
`log-format-upstream`	Supported	ASM console	N/A	Customize log format on the Observability Settings page in the ASM console. See Configure Observability Settings.
`max-worker-connections`	Supported	`connectionPool.tcp.maxConnections`	int32 / 2^32-1	Configure in a `DestinationRule`. Sets the maximum connections to a single host. See the connection pool settings example below.
`proxy-body-size`	Not supported	N/A	N/A	ASM does not enforce a maximum request body size. Use chunked transfer encoding for large payloads.
`proxy-connect-timeout`	Supported	`connectionPool.tcp.connectTimeout`	Duration / `10s`	In NGINX, this timeout cannot exceed 75 seconds. Configure the ASM equivalent in a `DestinationRule`. Format: duration string (for example, `30ms`, `5s`). Must be >= 1ms. See the connection pool settings example below.
`reuse-port`	Supported	Default behavior	bool / `true`	No action required. ASM gateways enable `SO_REUSEPORT` by default.
`server-tokens`	Supported	Default Envoy server header	N/A	ASM gateways set the `Server` header to `istio-envoy` by default. Error pages do not display Envoy version information.
`ssl-redirect`	Supported	`tls.httpsRedirect`	bool	Configure in a `Gateway` resource. See the HTTPS redirect example below.
`upstream-keepalive-connections`	Partial	`connectionPool.tcp.maxConnections`	int32 / 2^32-1	Important In NGINX, this sets the maximum idle keepalive connections per worker. In Istio, `maxConnections` sets the maximum total connections (active + idle) per host. Adjust values accordingly. See the connection pool settings example below.
`upstream-keepalive-timeout`	Supported	`connectionPool.http.idleTimeout`	Duration / `1h`	Configure in a `DestinationRule`. Set to `0s` to disable. See the connection pool settings example below.
`use-forwarded-headers`	Supported	Gateway network topology	N/A	In NGINX, setting this to `true` forwards incoming `X-Forwarded-*` headers (typical when NGINX sits behind another L7 proxy). In ASM, configure this through Istio's network topology settings. See Configuring Gateway Network Topology.
`worker-cpu-affinity`	Not supported	N/A	N/A	In containerized environments, use Kubernetes resource limits and CPU pinning instead. Use the default value.

Configuration examples

Configure connection pool settings

Several NGINX parameters map to Istio DestinationRule connection pool fields. The following example shows how to configure connection limits, timeouts, and keepalive behavior in a single DestinationRule.

NGINX ConfigMap (before):

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
data:
  max-worker-connections: "1024"
  upstream-keepalive-connections: "320"
  upstream-keepalive-timeout: "60"
  proxy-connect-timeout: "5"
  keep-alive-requests: "1000"

ASM DestinationRule (after):

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: my-service-pool
  namespace: <your-namespace>
spec:
  host: <your-service-host>     # For example, my-service.default.svc.cluster.local
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 1024     # Replaces max-worker-connections
        connectTimeout: 5s       # Replaces proxy-connect-timeout
        tcpKeepalive:
          time: 7200s
          interval: 75s
      http:
        maxRequestsPerConnection: 1000   # Replaces keep-alive-requests
        idleTimeout: 60s                 # Replaces upstream-keepalive-timeout

Replace the following placeholders with your values:

Placeholder	Description	Example
`<your-namespace>`	Namespace of the target service	`default`
`<your-service-host>`	Fully qualified service hostname	`my-service.default.svc.cluster.local`

Note

The NGINX upstream-keepalive-connections parameter limits idle connections per worker, while Istio maxConnections limits total connections (active + idle) per host. If your NGINX configuration sets upstream-keepalive-connections: 320, you may need a higher maxConnections value in Istio to accommodate both active and idle connections.

Configure HTTPS redirect

To redirect HTTP traffic to HTTPS (equivalent to NGINX ssl-redirect), configure tls.httpsRedirect in an Istio Gateway resource.

NGINX ConfigMap (before):

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
data:
  ssl-redirect: "true"

ASM Gateway (after):

apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: <your-namespace>
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - "*.example.com"
    tls:
      httpsRedirect: true    # Sends a 301 redirect for HTTP requests
  - port:
      number: 443
      name: https
      protocol: HTTPS
    hosts:
    - "*.example.com"
    tls:
      mode: SIMPLE
      credentialName: my-tls-credential

Configure X-Forwarded-For handling

To control how ASM handles X-Forwarded-For headers (equivalent to NGINX compute-full-forwarded-for and use-forwarded-headers), configure the gateway network topology:

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      gatewayTopology:
        numTrustedProxies: 1    # Number of trusted proxies in front of the gateway

Set numTrustedProxies to the number of L7 proxies between clients and the ASM gateway. This determines which X-Forwarded-For entry Envoy trusts as the real client IP.

For more information, see Configuring Gateway Network Topology.

References

Destination Rule reference -- Full field reference for connection pools, load balancing, and TLS settings
Gateway reference -- Full field reference for port, TLS, and host configuration
Configuring Gateway Network Topology -- Details on X-Forwarded-For handling and trusted proxy configuration
Configure Observability Settings -- Customize log format in the ASM console
Ingress Nginx ConfigMap reference -- Original NGINX parameter documentation