API Gateway:Nginx Ingress migration guide

High compatibility with Nginx Ingress annotations

APIG Ingress, the Ingress Controller for Cloud-native API Gateway, supports most Nginx Ingress annotations. It supports 51 annotations, which cover 90% of user scenarios. You can migrate existing Kubernetes Ingress YAML files without major changes.

Examples of key compatible annotations:

Feature enhancements (Higress annotations)

This mode is not only compatible with Nginx but also provides advanced features that Nginx Ingress lacks. These features are available through annotations with the higress.ingress.kubernetes.io/ prefix and include the following:

Traffic mirroring. Nginx issue: Lacks traffic mirroring capabilities. Requires writing Lua scripts.

APIG Ingress solution: Provides the native higress.ingress.kubernetes.io/mirror-target-service annotation. This lets you easily replicate traffic to a test service for shadow testing in a production environment.

Complete API lifecycle management

This mode supports full lifecycle management for APIs, from design, development, and testing to publishing and unpublishing. This includes:

• Version control: Supports multiple API versions, such as v1 and v2, to be online at the same time. You can also manage their publishing status.

• Publishing and rollbacks: Provides a history of API publications and supports one-click rollbacks to any previous version.

Advanced enterprise-grade security

This mode provides security capabilities far beyond the Ingress mode. It separates complex authentication logic from backend services. Features include the following:

• Rich authentication and authorization: Natively supports JWT and OIDC. It can also integrate with Alibaba Cloud IDaaS.

• Multilayer defense: Deeply integrates with Web Application Firewall (WAF). Supports mutual authentication (mTLS), IP blacklists and whitelists, and custom security plugins.

Powerful extensibility

• Plugin marketplace: Offers a rich selection of official plugins covering authentication, security, traffic, and more. It also supports uploading custom plugins.

• Hot updates: The gateway supports hot updates for plugins and configurations without restarting instances. This ensures high availability (HA) for your business.

API operations and multi-source service discovery

• API ecosystem: Provides a consumer management feature. You can manage API call quotas and subscription rules.

• Multi-source discovery: Backend services are not limited to Kubernetes clusters. The gateway can also discover services from multiple sources, such as Nacos, Function Compute (FC), and fixed addresses or domain names.

Route priority explanation:

For routes with the same domain name and path, APIs created in the console have a higher priority than routes synced from an Ingress. Therefore, during migration, you can configure routes one by one in the console. If you find an issue, you can immediately revert to the Ingress mode by deleting the console configuration.

Example:

Scenario: You have a domain name, example.com, and need to progressively migrate 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

At this point, the API Gateway automatically generates the following routes:

• /api → api-service-v1:8080

• /web → web-service-v1:80

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

In the console, you can create a route for example.com and configure the /api path to point to the new service version, api-service-v2:8080.

The actual order of the merged routes is now:

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, takes effect)

Result:

• Accessing example.com/api/* → Routes to api-service-v2 (console configuration takes effect)

• Accessing example.com/web/* → Routes to web-service-v1 (Ingress configuration takes effect)

3. Find an issue and roll back quickly

If you find that api-service-v2 is abnormal, you can simply delete the /api route configuration in the console.

The route order after deletion is:

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

Result: Traffic immediately rolls back to api-service-v1, which is configured in the Ingress. You do not need to modify the Ingress or restart any services.

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

After you configure 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)

At this point, all traffic is controlled by the console configuration. You can safely delete the corresponding Ingress configuration.