Gateway routes - AWS App Mesh

Gateway routes

A gateway route is attached to a virtual gateway and routes traffic to an existing virtual service. If a route matches a request, it can distribute traffic to a target virtual service. This topic helps you work with gateway routes in a service mesh.

Creating a gateway route

To create a gateway route using the AWS CLI version 1.18.116 or later, see the examples in the AWS CLI reference for the create-gateway-route command.

To create a gateway route using the AWS Management Console

  1. Open the App Mesh console at https://console.aws.amazon.com/appmesh/.

  2. Choose the mesh that you want to create the gateway route in. All of the meshes that you own and that have been shared with you are listed.

  3. Choose Virtual gateways in the left navigation.

  4. Choose the virtual gateway that you want to associate a new gateway route with. If none are listed, then you need to create a virtual gateway first. You can only create a gateway route for a virtual gateway that your account is listed as the Resource owner of.

  5. In the Gateway routes table, choose Create gateway route.

  6. For Gateway route name, specify the name to use for your gateway route.

  7. For Gateway route type choose one of the following protocols.

    • http or http2 – Specify a Match prefix. A matched request by a gateway route is rewritten to the target virtual service's name and the matched prefix is rewritten to /, by default. For example, if you have configured the Match prefix to be /, when a request is received for www.example.com/chapter/page, it would match the prefix, because it has a / after the host name. The request would be rewritten to the name of a virtual service, such as myservicea.svc.cluster.local/chapter/page.

      Depending on how you configure your virtual service, it could use a virtual router to route the request to different virtual nodes, based on specific prefixes or headers. If the Match prefix in the gateway route example were /chapter, rather than /, then:

      • A request to www.example.com/chapter/page would be re-written to myservicea.svc.cluster.local/page. Since chapter was the matched prefix, it would be removed in the re-written request.

      • A request to www.example.com/chapter1 would be rewritten to myservicea.svc.cluster.local/1. Again, chapter was removed, since it was the matched prefix, but /1 would be added to the rewritten request from the original request.

      Provided the virtual service’s virtual router has a route defined with a prefix of /1 or /page, the request would be routed to a virtual node. If the virtual service's virtual router doesn't have such a route however, the request would be dropped. This behavior enables you to minimize the number of gateway routes that are needed, but does require you to ensure that you have routes for a virtual service’s virtual router for each of the expected prefixes that may be requested. Learn more about Virtual services, Virtual routers, and Routes.

      Important
      • You can't specify either /aws-appmesh* or /aws-app-mesh* for Match prefix. These prefixes are reserved for future App Mesh internal use.

      • If multiple gateway routes are defined, then a request is matched to the route with the longest prefix. For example, if two gateway routes existed, with one having a prefix of /chapter and one having a prefix of /, then a request for www.example.com/chapter/ would be matched to the gateway route with the /chapter prefix.

    • grpc – Specify your gRPC Service name. Your gRPC service acts as an API for your application and is defined with ProtoBuf. For more information about gRPC, see grpc.io.

      Important

      You can't specify /aws.app-mesh* or aws.appmesh for the Service name. These service names are reserved for future App Mesh internal use.

  8. Select an existing Virtual service name. If none are listed, then you need to create a virtual service first.

  9. Choose Create gateway route to finish.

Deleting a gateway route

To delete a route using the AWS CLI version 1.18.116 or higher, see the AWS CLI reference for the delete-gateway-route command.

To delete a gateway route using the AWS Management Console

  1. Open the App Mesh console at https://console.aws.amazon.com/appmesh/.

  2. Choose the mesh that you want to delete a gateway route from. All of the meshes that you own and that have been shared with you are listed.

  3. Choose Virtual gateways in the left navigation.

  4. Choose the virtual gateway that you want to delete a gateway route from.

  5. In the Gateway routes table, choose the gateway route that you want to delete and select Delete. You can only delete a gateway route if your account is listed for Resource owner.

  6. In the confirmation box, type delete and then select Delete.