Routing

Single-service routing

In single-service routing mode, the gateway matches incoming requests against configured routing rules and forwards them to a single backend service. For example:

• Requests matching the /user rule are forwarded to the user service.

• Requests matching the /order rule are forwarded to the order service.

For information about configuring services, see Manage services.

Percentage-based routing

In percentage-based routing mode, the gateway splits traffic across multiple backend services based on configured weights. Use this mode when migrating services between registries or operations and maintenance (O&M) systems without dropping traffic.

• Different registries

  When upgrading a service registry, deploy a replica of the service using the new registry alongside the existing service. Gradually shift traffic from the old service to the new one by adjusting weights. After the new service is stable, forward all traffic to it. If the new service encounters issues, roll back traffic to the old service at any time.

  For example, a user service originally uses Nacos as its registry. To switch to the built-in CoreDNS solution in Kubernetes (K8s), which requires Service resources, migrate traffic incrementally using percentage-based routing.

  

• Different O&M systems

  When migrating services from virtual machines to Kubernetes, deploy a replica on the K8s cluster and register it under a new service name. The service registry then contains two services with the same functionality: one on an Elastic Compute Service (ECS) instance and one on an Alibaba Cloud Container Service for Kubernetes (ACK) cluster. Gradually shift traffic to the K8s service, and adjust weights or roll back at any time during the migration.

  For example, a user service using Nacos as its registry is migrated from an ECS instance to ACK.

  

Tag-based routing

In tag-based routing mode, the gateway forwards requests to different versions of the same or different services based on configured weights or request attributes. Use this mode for canary releases, multi-environment routing, and high-availability deployments. For information about configuring service versions, see Manage service versions.

• Canary release

  During a canary release, a small percentage of traffic goes to the new version for validation. If the new version performs as expected, traffic shifts gradually until the old version receives none. Tag-based routing supports two approaches for canary releases:

  For example, a user service uses K8s container service for service discovery. The current version is v1, and a new version v2 is ready for release.

  • By percentage

    The /user route uses tag-based routing to forward requests to user service v1. Add v2 as a service version in service management, then add user service v2 as a destination in the routing rule and configure a weight to control the percentage of traffic it receives.

    

  • By tag

    The existing /user route forwards requests to user service v1. Create a second /user route with a canary release tag — for example, a header named stage with the value gray. Requests containing this header are forwarded to user service v2.

    

• Tag-based routing

  A service may have multiple long-running versions, each serving requests that match specific attributes. For example, requests with a particular header value can be routed to a specific service version. This is useful for managing multiple environments — such as test, pre-release, and production — within a single gateway.

  For example, a user service uses K8s container service for service discovery and has three environments: test, pre-release, and production. Requests to the /user route are routed as follows:

  • If the stage header value is test, traffic is forwarded to the test version of the user service.

  • If the stage header value is pre, traffic is forwarded to the pre-release version of the user service.

  • If the stage header value is online, traffic is forwarded to the production version of the user service.

  

• High-availability deployment

  To improve service availability, deploy the service across multiple K8s clusters and manage instances per cluster using cluster-related node metadata. Each cluster maps to a service version with a configurable traffic weight. If a cluster fails, set its weight to 0 to redirect all traffic to the remaining clusters.

  For example, a user service uses K8s container service for service discovery and is deployed in two ACK clusters, Cluster A and Cluster B. For requests to the /user route, 80% of traffic is forwarded to Cluster A and 20% to Cluster B.

  

Mock routing

Mock routing returns a fixed response for a route without forwarding the request to a backend service. Use it to unblock frontend development before the backend is ready, or to verify that request matching rules are working correctly.

For example, configure a fixed response for the user service API before the backend is developed so that frontend developers can test and debug independently. Once the backend is ready, switch the route from mock to point to the actual service for end-to-end testing.

Redirection routing

Redirection routing sends clients to a different domain name or path. Use it for domain name migrations or API path changes.

For example, a request to old.example.com/test arrives at the gateway, which redirects it to new.example.com/dev.