API Gateway:Migrate from Nginx Ingress to API Gateway

Nginx Ingress compatibility

APIG Ingress supports most Nginx Ingress annotations (51 annotations, covering over 90% of use cases), so you can migrate existing Kubernetes Ingress YAML files with minimal changes.

Examples of key compatible annotations:

Enhanced capabilities

API Gateway adds advanced features through higress.ingress.kubernetes.io/ annotations, unavailable in Nginx Ingress.

Traffic mirroring
Nginx: No native traffic mirroring; requires custom Lua scripts.

APIG Ingress: The higress.ingress.kubernetes.io/mirror-target-service annotation mirrors traffic to a test service for shadow testing in production.

API lifecycle management

Manage APIs through their full lifecycle: design, development, testing, publishing, and retirement.

• Version management: Run multiple concurrent API versions (such as v1 and v2) and manage their publication status.

• Publishing and rollback: Maintain a publish history and roll back to any previous version with one click.

Enterprise-grade security

Offload complex authentication logic from backend services with enterprise-grade security.

• Authentication and authorization: Natively supports JWT, OIDC, and Alibaba Cloud IDaaS integration.

• Defense-in-depth: Integrates with WAF and supports mTLS, IP allowlists/blocklists, and custom security plugins.

Extensibility

• Plugin marketplace: Official plugins for authentication, security, and traffic management, plus custom plugin uploads.

• Hot updates: Update plugins and configurations without restarting instances.

API operations and multi-source service discovery

• API ecosystem: Manage API call quotas and subscription rules through consumer management.

• Multi-source discovery: Discover services from Kubernetes, Nacos, Function Compute, and static IP addresses or domain names.

Routing priority

For routes with the same domain and path, console-created APIs take priority over Ingress-synced routes. Migrate routes individually — if issues arise, delete the console configuration to revert to the Ingress route instantly.

Example:

Scenario: You have a domain example.com and need to progressively migrate it from an Ingress configuration to a console configuration.

1. Initial state (Ingress configuration only)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service-v1
            port:
              number: 8080
      - path: /web
        pathType: Prefix
        backend:
          service:
            name: web-service-v1
            port:
              number: 80

API Gateway generates these routes:

• /api → api-service-v1:8080

• /web → web-service-v1:80

2. Mid-migration (configure the /api path in the console)

Create a console route for example.com directing /api to api-service-v2:8080.

Merged routing order:

1. /api → api-service-v2:8080  (Console configuration, matched first) 
2. /api → api-service-v1:8080  (Ingress configuration, not matched)
3. /web → web-service-v1:80    (Ingress configuration, effective)

Result:

• Requests to example.com/api/* are routed to api-service-v2 (console configuration takes effect).

• Requests to example.com/web/* are routed to web-service-v1 (Ingress configuration takes effect).

3. Find an issue and perform a quick rollback

If an issue occurs with api-service-v2, simply delete the/api route configuration in the console.

Routing order after deletion:

1. /api → api-service-v1:8080  (Ingress configuration, immediately restored) 
2. /web → web-service-v1:80    (Ingress configuration)

Result: Traffic immediately reverts to api-service-v1 from the Ingress configuration, with no Ingress changes or service restarts.

4. Complete migration (configure all paths in the console)

After configuring the /web path in the console:

1. /api → api-service-v2:8080  (Console configuration) 
2. /web → web-service-v2:80    (Console configuration) 
3. /api → api-service-v1:8080  (Ingress configuration, not matched)
4. /web → web-service-v1:80    (Ingress configuration, not matched)

All traffic now uses the console configuration. You can safely delete the Ingress configuration.