Migrate Services from Zuul to Cloud-Native Gateway - Microservices Engine

A cloud-native gateway unifies traffic management and microservice routing into a single managed layer built on Envoy and Kubernetes. Compared to Zuul gateways, cloud-native gateways support container service discovery, deliver higher performance than NGINX Ingress gateways, and provide out-of-the-box observability and security without custom development.

This guide walks through each phase of migration: connecting service sources, converting routing and resilience configurations, setting up authentication and observability, and cutting over traffic.

How Zuul concepts map to cloud-native gateway concepts

Zuul concept	Cloud-native gateway equivalent	Notes
Zuul route (`zuul.routes.*`)	Routing rule	Configured in the MSE console or via Spring Cloud Gateway YAML
`serviceId`	Service (imported from a service source)	Subscribe to services through the console
Zuul filter (pre/post/route)	Routing policy (throttling, rewrite, header setting, CORS)	Built-in policies replace custom filter code
Ribbon (`NFLoadBalancerRuleClassName`)	Built-in load balancing	Configured per service version
Hystrix (`timeoutInMilliseconds`, `maxConcurrentRequests`)	Timeout and retry settings	Configured per routing rule
Nacos registry	Service source	Add as a service source in the MSE console
Custom auth filters	Authentication plugins (JWT, OIDC, IDaaS, custom)	No code required
Hystrix Dashboard	Data dashboards, Tracing Analysis, log shipping	Built-in observability

Prerequisites

Step 1: Connect service sources

The cloud-native gateway discovers backend services through service sources, the equivalent of Zuul's registry configuration. Skip this step and go to Step 2 if any of the following conditions apply:

Container Service for Kubernetes (ACK) is used, and services are discoverable through Kubernetes.
An MSE Nacos instance is already configured as a registry and upgraded to a version that supports Mesh Configuration Protocol (MCP).
No service discovery is used. Services are accessed by domain names or fixed IP addresses.

Choose a service source type

MSE Nacos instance

Create an MSE Nacos instance. For more information, see Create a Nacos engine.
Update your application configuration or code to register services with the MSE Nacos instance. For more information, see Java SDK.
(Optional) For Java applications, use the Microservices Governance agent to migrate registrations automatically. For more information, see Migration solution based on MSE Sync.

Enterprise Distributed Application Service (EDAS) shared registry

Cloud-native gateways support EDAS registries directly. Add an EDAS registry as a service source. For more information, see Add a service source.

Serverless App Engine (SAE) shared registry

Cloud-native gateways support SAE registries directly. Add an SAE registry as a service source. For more information, see Add a service source.

Step 2: Convert Zuul routing configurations

This step maps your existing Zuul YAML to cloud-native gateway equivalents. The following sections use this sample Zuul configuration as a reference.

Zuul routing configuration (before)

zuul:
  routes:
    demo:
      path: /test/a
      serviceId: service-a
    pre:
      path: /auth/validation/**
      serviceId: service-a
    header:
      path: /auth/test
      requestHeadersToAdd:
      - key: debug_tag
        value: true
    retry:
      path: /app/try/**
      stripPrefix: false
      retryable: true
      serviceId: service-a
  retryable: true
  ignoredPatterns:
  - /login/api/a/v3/a
  - /auth/api/b

Zuul registry and resilience configuration (before)

spring:
  application:
    name: zuul-demo
  cloud:
    nacos:
      discovery:
        server-addr: nacos-server:8848
      config:
        enabled: false

service-a:
  ribbon:
    NFLoadBalancerRuleClassName: com.netflix.loadbalancer.WeightedResponseTimeRule
    ConnectTimeout: 1000
    ReadTimeout: 8000
    MaxAutoRetries: 3
    MaxAutoRetriesNextServer: 2
    MaxTotalConnections: 20000
    MaxConnectionsPerHost: 5000
hystrix:
  command:
    service-a:
      execution:
        isolation:
          thread:
            timeoutInMilliseconds: 60000
          strategy: SEMAPHORE
          semaphore:
            maxConcurrentRequests: 60000

2a. Add a service source (replaces registry configuration)

In the MSE console:

Open the Service source page for your cloud-native gateway.
Add your Nacos registry (or other registry type) as a service source.
The configuration takes effect in real time.

This replaces the spring.cloud.nacos.discovery.server-addr setting in Zuul. For full instructions, see Add a service source.

2b. Import and configure services (replaces serviceId and Ribbon)

Import the services that your Zuul routes reference (for example, service-a). For more information, see Add a service.
Configure an appropriate route version for each service. For more information, see Manage service versions.

The cloud-native gateway handles load balancing natively. The Ribbon configuration from Zuul (WeightedResponseTimeRule, ConnectTimeout, ReadTimeout, connection pool settings) is replaced by the gateway's built-in service and routing rule settings.

Ribbon to cloud-native gateway mapping

Zuul Ribbon setting	Cloud-native gateway equivalent
`NFLoadBalancerRuleClassName`	Load balancing policy on the service version
`ConnectTimeout: 1000`	Timeout setting on the routing rule
`ReadTimeout: 8000`	Timeout setting on the routing rule
`MaxAutoRetries: 3`	Retry policy on the routing rule
`MaxAutoRetriesNextServer: 2`	Retry policy on the routing rule
`MaxTotalConnections` / `MaxConnectionsPerHost`	Managed by the gateway infrastructure

Hystrix to cloud-native gateway mapping

Zuul Hystrix setting	Cloud-native gateway equivalent
`timeoutInMilliseconds: 60000`	Timeout setting on the routing rule
`strategy: SEMAPHORE`	Not required (gateway handles isolation internally)
`maxConcurrentRequests: 60000`	Throttling policy on the routing rule

2c. Create routing rules (replaces zuul.routes)

Create routing rules in the MSE console. Each Zuul route maps to a routing rule with a path predicate and a target service.

Side-by-side route conversion

Zuul route	Path	Cloud-native gateway routing rule
`demo`	`/test/a` to `service-a`	Path predicate: `/test/a`, target: `service-a`
`pre`	`/auth/validation/**` to `service-a`	Path predicate: `/auth/validation/**`, target: `service-a`
`header`	`/auth/test` + header `debug_tag=true`	Path predicate: `/auth/test`, header setting policy: `debug_tag=true`
`retry`	`/app/try/**` to `service-a`, `stripPrefix=false`, `retryable=true`	Path predicate: `/app/try/**`, target: `service-a`, strip prefix: disabled, retry: enabled

For ignoredPatterns (/login/api/a/v3/a, /auth/api/b), do not create routing rules for those paths.

The cloud-native gateway uses Spring Cloud Gateway format internally:

spring:
  cloud:
    gateway:
      routes:
        - id: websocket_test
          uri: ws://localhost:9000
          order: 9000
          predicates:
            - Path=/echo
        - id: default_path_to_service-a
          uri: lb://service-a
          order: 10000
          predicates:
            - Path=/sleep

For full instructions, see Create a routing rule.

2d. Configure additional routing policies

Cloud-native gateways provide built-in routing policies that replace Zuul filter code:

Policy	Replaces	Details
Throttling	Custom rate-limiting filters	Configure a throttling policy
Rewrite	Custom URL rewrite filters	Configure a rewrite policy
Header setting	`requestHeadersToAdd` in Zuul routes	Configure a header setting policy
CORS	Custom CORS filters	Configure a CORS policy

Step 3: Set up authentication

Cloud-native gateways provide built-in authentication that replaces custom Zuul authentication filters. Choose the method that matches your current setup:

Method	Use when	Details
JWT authentication	Your Zuul gateway validates JWTs in a pre-filter	Configure JWT authentication
OIDC authentication	Your application uses OpenID Connect flows	Configure OIDC authentication
IDaaS authentication	Your organization uses Alibaba Cloud IDaaS	Configure IDaaS authentication
Custom authentication	None of the above methods apply	Configure custom authentication

Step 4: Set up observability

Cloud-native gateways provide built-in observability that replaces custom logging or tracing integrations in Zuul.

Capability	Replaces	Details
Gateway monitoring dashboards	Custom metrics dashboards	View the monitoring data of a cloud-native gateway
Alert rules	Custom alerting integrations	Manage alert rules
Log shipping	Custom log pipelines	Enable log shipping for a cloud-native gateway
Tracing Analysis	Custom tracing infrastructure	Enable Tracing Analysis for a cloud-native gateway

Step 5: Migrate traffic

Choose a traffic migration strategy based on your risk tolerance and available effort. The recommended approach is procedural migration, which balances safety and efficiency.

Traffic migration strategies

Strategy	How it works	Cost	Risk
Iterated migration	Change the access URLs of a few services at a time on the caller side. Verify each batch before proceeding.	High	Low
Phased migration (proxy side)	Create migration phases by service type (core vs. non-core) on the original proxy side. Migrate access URLs in phases.	Medium	Medium
DNS-based full migration	Associate the original domain name with the cloud-native gateway access URL in a single cutover.	Low	High
Procedural migration (recommended)	Combines the above: test a few services first, migrate core services in sequence, then perform a DNS-based full cutover after stress testing.	Relatively low	Relatively low

Recommended: procedural migration

Test with non-critical services. Select several non-critical services. Update their access URLs to point to the cloud-native gateway. Verify that routing, authentication, and observability work as expected.
Migrate core services in sequence. After the test phase succeeds, migrate core services one at a time. Monitor each service for errors, latency changes, and traffic anomalies by using the gateway's data dashboards.
Perform DNS cutover after stress testing. After all services are migrated and validated, run stress testing against the cloud-native gateway. Then associate the original domain name with the cloud-native gateway's access URL.

Verify the migration

After each phase, check the following:

Routing rules match the expected behavior (test key paths).
Authentication passes for all service endpoints.
Monitoring dashboards show expected traffic patterns.
No errors appear in gateway logs (check log shipping output).

Rollback

If issues arise during migration:

Revert the access URLs (or DNS records) to point back to the Zuul gateway.
Keep the Zuul gateway running in parallel until the cloud-native gateway migration is fully validated.
Investigate and resolve issues before retrying the migration.

References

Overview of cloud-native gateways