Routes

Important

End of support notice: On September 30, 2026, AWS will discontinue support for AWS App Mesh. After September 30, 2026, you will no longer be able to access the AWS App Mesh console or AWS App Mesh resources. For more information, visit this blog post Migrating from AWS App Mesh to Amazon ECS Service Connect.

A route is associated with a virtual router. The route is used to match requests for the virtual router and to distribute traffic to its associated virtual nodes. If a route matches a request, it can distribute traffic to one or more target virtual nodes. You can specify relative weighting for each virtual node. This topic helps you work with routes in a service mesh.

Creating a route

AWS Management Console

To create a 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 route in. All of the meshes that you own and that have been shared with you are listed.

3. Choose Virtual routers in the left navigation.

4. Choose the virtual router that you want to associate a new route with. If none are listed, then you need to create a virtual router first.

5. In the Routes table, choose Create route. To create a route, your account ID must be listed as the Resource owner of the route.

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

7. For Route type, choose the protocol that you want to route. The protocol that you select must match the listener protocol that you selected for your virtual router and the virtual node that you're routing traffic to.

8. (Optional) For Route priority, specify a priority from 0-1000 to use for your route. Routes are matched based on the specified value, where 0 is the highest priority.

9. (Optional) Choose Additional configuration. From the protocols down below, choose the protocol that you selected for Route type and specify settings in the console as desired.

10. For Target configuration, select the existing App Mesh virtual node to route traffic to and specify a Weight. You can choose Add target to add additional targets. The percentage for all targets must add up to 100. If no virtual nodes are listed, then you must create one first. If the selected virtual node has multiple listeners, Target port is required.

11. For Match configuration, specify:

    Match configuration is not available for tcp

    • If http/http2 is the selected type:

      • (Optional) Method ‐ specifies the method header to be matched in the incoming http/http2 requests.

      • (Optional) Port match ‐ Match the port for incoming traffic. Port match is required if this virtual router has multiple listeners.

      • (Optional) Prefix/Exact/Regex path ‐ method of matching the path of the URL.

        • Prefix match ‐ 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. 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.

          Note

          If you enable Path/Prefix based matching, App Mesh enables path normalization (normalize_path and merge_slashes) to minimize the probability of path confusion vulnerabilities.

          Path confusion vulnerabilities occur when parties participating in the request use different path representations.

        • Exact match ‐ the exact param disables the partial matching for a route and makes sure that it only returns the route if the path is an EXACT match to the current url.

        • Regex match ‐ used to describe patterns where multiple URLs may actually identify a single page on the website.

      • (Optional) Query parameters ‐ this field allows you to match on the query parameters.

      • (Optional) Headers ‐ specifies the headers for http and http2. It should match the incoming request to route to the target virtual service..

    • If grpc is the selected type:

      • Service name ‐ the destination service for which to match the request.

      • Method name ‐ the destination method for which to match the request.

      • (Optional) Metadata ‐ specifies the Match based on the presence of metadata. All must match for the request to be processed.

12. Select Create route.

AWS CLI

To create a route using the AWS CLI.

Create a gRPC route using the following command and input JSON (replace the red values with your own):

1. aws appmesh create-route \
        --cli-input-json file://create-route-grpc.json

2. Contents of example create-route-grpc.json

   {
       "meshName" : "meshName",
       "routeName" : "routeName",
       "spec" : {
          "grpcRoute" : {
             "action" : {
                "weightedTargets" : [
                   {
                      "virtualNode" : "nodeName",
                      "weight" : 100
                   }
                ]
             },
             "match" : {
                "metadata" : [
                   {
                      "invert" : false,
                      "match" : {
                         "prefix" : "123"
                      },
                      "name" : "myMetadata"
                   }
                ],
                "methodName" : "nameOfmethod",
                "serviceName" : "serviceA.svc.cluster.local"
             },
             "retryPolicy" : {
                "grpcRetryEvents" : [ "deadline-exceeded" ],
                "httpRetryEvents" : [ "server-error", "gateway-error" ],
                "maxRetries" : 3,
                "perRetryTimeout" : {
                   "unit" : "s",
                   "value" : 15
                },
                "tcpRetryEvents" : [ "connection-error" ]
             }
          },
          "priority" : 100
       },
       "virtualRouterName" : "routerName"
   }

3. Example output:

   {
       "route": {
           "meshName": "meshName",
           "metadata": {
               "arn": "arn:aws:appmesh:us-west-2:210987654321:mesh/meshName/virtualRouter/routerName/route/routeName",
               "createdAt": "2022-04-06T13:48:20.749000-05:00",
               "lastUpdatedAt": "2022-04-06T13:48:20.749000-05:00",
               "meshOwner": "123456789012",
               "resourceOwner": "210987654321",
               "uid": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
               "version": 1
           },
           "routeName": "routeName",
           "spec": {
               "grpcRoute": {
                   "action": {
                       "weightedTargets": [
                           {
                               "virtualNode": "nodeName",
                               "weight": 100
                           }
                       ]
                   },
                   "match": {
                       "metadata": [
                           {
                               "invert": false,
                               "match": {
                                   "prefix": "123"
                               },
                               "name": "myMetadata"
                           }
                       ],
                       "methodName": "nameOfMehod",
                       "serviceName": "serviceA.svc.cluster.local"
                   },
                   "retryPolicy": {
   "grpcRetryEvents": [
                           "deadline-exceeded"
                       ],
                       "httpRetryEvents": [
                           "server-error",
                           "gateway-error"
                       ],
                       "maxRetries": 3,
                       "perRetryTimeout": {
                           "unit": "s",
                           "value": 15
                       },
                       "tcpRetryEvents": [
                           "connection-error"
                       ]
                   }
               },
               "priority": 100
           },
           "status": {
               "status": "ACTIVE"
           },
           "virtualRouterName": "routerName"
       }
   }

For more information on creating a route with the AWS CLI for App Mesh, see the create-route command in the AWS CLI reference.

gRPC

(Optional) Match

• (Optional) Enter the Service name of the destination service to match the request for. If you don't specify a name, requests to any service are matched.

• (Optional) Enter the Method name of the destination method to match the request for. If you don't specify a name, requests to any method are matched. If you specify a method name, you must specify a service name.

(Optional) Metadata

Choose Add metadata.

• (Optional) Enter the Metadata name that you want to route based on, select a Match type, and enter a Match value. Selecting Invert will match the opposite. For example, if you specify a Metadata name of myMetadata, a Match type of Exact, a Match value of 123, and select Invert, then the route is matched for any request that has a metadata name that starts with anything other than 123.

• (Optional) Select Add metadata to add up to ten metadata items.

(Optional) Retry policy

A retry policy enables clients to protect themselves from intermittent network failures or intermittent server-side failures. A retry policy is optional, but recommended. The retry timeout values define the timeout per retry attempt (including the initial attempt). If you don't define a retry policy, then App Mesh may automatically create a default policy for each of your routes. For more information, see Default route retry policy.

• For Retry timeout, enter the number of units for the timeout duration. A value is required if you select any protocol retry event.

• For Retry timeout unit, select a unit. A value is required if you select any protocol retry event.

• For Max retries, enter the maximum number of retry attempts when the request fails. A value is required if you select any protocol retry event. We recommend a value of at least two.

• Select one or more HTTP retry events. We recommend selecting at least stream-error and gateway-error.

• Select a TCP retry event.

• Select one or more gRPC retry events. We recommend selecting at least cancelled and unavailable.

(Optional) Timeouts

• The default is 15 seconds. If you specified a Retry policy, then the duration that you specify here should always be greater than or equal to the retry duration multiplied by the Max retries that you defined in the Retry policy so that your retry policy can complete. If you specify a duration greater than 15 seconds, then make sure that the timeout specified for the listener of any virtual node Target is also greater than 15 seconds. For more information, see Virtual Nodes.

• A value of 0 disables the timeout.

• The maximum amount of time that the route can be idle.

HTTP and HTTP/2

(Optional) Match

• Specify the Prefix that the route should match. For example, if your virtual service name is service-b.local and you want the route to match requests to service-b.local/metrics, your prefix should be /metrics. Specifying / routes all traffic.

• (Optional) Select a Method.

• (Optional) Select a Scheme. Applicable only for HTTP2 routes.

(Optional) Headers

• (Optional) Select Add header. Enter the Header name that you want to route based on, select a Match type, and enter a Match value. Selecting Invert will match the opposite. For example, if you specify a header named clientRequestId with a Prefix of 123, and select Invert, then the route is matched for any request that has a header that starts with anything other than 123.

• (Optional) Select Add header. You can add up to ten headers.

(Optional) Retry policy

A retry policy enables clients to protect themselves from intermittent network failures or intermittent server-side failures. A retry policy is optional, but recommended. The retry timeout values define the timeout per retry attempt (including the initial attempt). If you don't define a retry policy, then App Mesh may automatically create a default policy for each of your routes. For more information, see Default route retry policy.

• For Retry timeout, enter the number of units for the timeout duration. A value is required if you select any protocol retry event.

• For Retry timeout unit, select a unit. A value is required if you select any protocol retry event.

• For Max retries, enter the maximum number of retry attempts when the request fails. A value is required if you select any protocol retry event. We recommend a value of at least two.

• Select one or more HTTP retry events. We recommend selecting at least stream-error and gateway-error.

• Select a TCP retry event.

(Optional) Timeouts

• Request timeout – The default is 15 seconds. If you specified a Retry policy, then the duration that you specify here should always be greater than or equal to the retry duration multiplied by the Max retries that you defined in the Retry policy so that your retry policy can complete.

• Idle duration – The default is 300 seconds.

• A value of 0 disables the timeout.

Note

If you specify a timeout greater than the default, make sure that the timeout specified for the listener for all virtual node participants is also greater than the default. However, if you decrease the timeout to a value that is lower than the default, it's optional to update the timeouts at virtual nodes. For more information, see Virtual Nodes.

TCP

(Optional) Timeouts

• Idle duration – The default is 300 seconds.

• A value of 0 disables the timeout.

Deleting a route

AWS Management Console

To delete a route using the AWS Management Console

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

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

3. Choose Virtual routers in the left navigation.

4. Choose the router from which you want to delete a route.

5. In the Routes table, choose the route that you want to delete and select Delete in the top right corner.

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

AWS CLI

To delete a route using the AWS CLI

1. Use the following command to delete your route (replace the red values with your own):

   aws appmesh delete-route \
        --mesh-name meshName \
        --virtual-router-name routerName \
        --route-name routeName

2. Example output:

   {
       "route": {
           "meshName": "meshName",
           "metadata": {
               "arn": "arn:aws:appmesh:us-west-2:210987654321:mesh/meshName/virtualRouter/routerName/route/routeName",
               "createdAt": "2022-04-06T13:46:54.750000-05:00",
               "lastUpdatedAt": "2022-04-07T10:43:57.152000-05:00",
               "meshOwner": "123456789012",
               "resourceOwner": "210987654321",
               "uid": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
               "version": 2
           },
           "routeName": "routeName",
           "spec": {
               "grpcRoute": {
                   "action": {
                       "weightedTargets": [
                           {
                               "virtualNode": "nodeName",
                               "weight": 100
                           }
                       ]
                   },
                   "match": {
                       "metadata": [
                           {
                               "invert": false,
                               "match": {
                                   "prefix": "123"
                               },
                               "name": "myMetadata"
                           }
                       ],
                       "methodName": "methodName",
                       "serviceName": "serviceA.svc.cluster.local"
                   },
                   "retryPolicy": {
                       "grpcRetryEvents": [
                           "deadline-exceeded"
                       ],
                       "httpRetryEvents": [
                           "server-error",
                           "gateway-error"
                       ],
                       "maxRetries": 3,
                       "perRetryTimeout": {
                           "unit": "s",
                           "value": 15
                       },
                       "tcpRetryEvents": [
                           "connection-error"
                       ]
                   }
               },
               "priority": 100
           },
           "status": {
               "status": "DELETED"
           },
           "virtualRouterName": "routerName"
       }
   }

For more information on deleting a route with the AWS CLI for App Mesh, see the delete-route command in the AWS CLI reference.