Skip to content

dispatch yaml

Jump to bottom
ludoch edited this page Apr 15, 2026 · 1 revision

The dispatch.yaml allows you to override routing rules. You can use the dispatch.yaml to send incoming requests to a specific service (formerly known as modules) based on the path or hostname in the URL.

For more information, see How Requests are Routed.

An app can have only one dispatch.yaml file, and the routing rules in that file apply to all of the app's services and versions. The routing rules also apply to URLs that are used in a cron file or a task queue configuration.

Deploying the dispatch file

Before you deploy your dispatch file, you must ensure that all the services defined in that file have already been deployed to App Engine. To deploy the dispatch.yaml file, run the gcloud app deploy command from the directory that contains the dispatch.yaml:

gcloud app deploy dispatch.yaml

For more information about the deployment commands, see Deploying a Java App.

Syntax

The root element in the dispatch.yaml file is dispatch: and contains a list of routing definitions that are specified by the following subelements.

The rules that you define in your dispatch file must use HTTP URL patterns that include the "." notation for separating subdomains. URLs defined with the HTTPS "-dot-" notation are not supported.

Dispatch rules are order dependent, and only the first rule that matches a URL will be applied.

Element Description
`service` 
      Specifies the name of the service that will handle the requests that
      match the `url` pattern. Note that
      services were previously called modules.

  </td>
</tr>
<tr id="url">
  <td>`url`</td>
  <td>

      In the `url` element, you define the URL
      pattern, which can
      include the host name and URL path that are no longer than 100
      characters. For the `service` element, you specify the
      name of the service that you want handling any incoming requests that
      match the URL pattern of the `url` element.

      Tip: You can include glob patterns like the `*` wildcard
      character in the `url` element; however, those patterns
      can be used only before the host name and at the end of the URL path.

      A URL pattern that can include the hostname and URL path. Glob
      characters can be used to match patterns. The Glob characters can be
      specified only at the beginning of the pattern and end of the pattern.

      URL paths that begin with `/_ah/` are not routed by the
      dispatch file.

  </td>
</tr>

Example

The following is a sample dispatch file that routes requests to https://simple-sample.uc.r.appspot.com and requests like https://simple-sample.uc.r.appspot.com/favicon.ico to the default service. All static content is served from the default service. Mobile requests like https://simple-sample.uc.r.appspot.com/mobile/ are routed to a mobile frontend, and worker requests like https://simple-sample.uc.r.appspot.com/work/ are routed to a static backend.

If you prefer general routing rules that match many possible requests, you can define rules with wider scopes. For example:

You can also write expressions that are more strict:

Limits

The dispatch file can contain up to 20 routing rules. When specifying the URL string, neither the hostname nor the path can be longer than 100 characters.

Deleting all dispatch rules

To delete all dispatch rules:

  1. Edit the contents of the dispatch.yaml file to:

     dispatch: []

  2. Deploy the dispatch.yaml file to App Engine.

Clone this wiki locally