dispatch.yaml Configuration File

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.

Deploying the dispatch file

To deploy and apply the configuration settings from your dispatch file to your App Engine environment:

gcloud app deploy dispatch.yaml

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 can also apply to the URLs that you define in your cron file.

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.

url

In the `url` element, you define the URL pattern within quotes, 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.

Example

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

dispatch:
  # Default service serves the typical web resources and all static resources.
  - url: "*/favicon.ico"
    service: default

  # Default service serves simple hostname request.
  - url: "simple-sample.appspot.com/"
    service: default

  # Send all mobile traffic to the mobile frontend.
  - url: "*/mobile/*"
    service: mobile-frontend

  # Send all work to the one static backend.
  - url: "*/work/*"
    service: static-backend

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

# Send any path that begins with “simple-sample.appspot.com/mobile” to the mobile-frontend service.
- url: "simple-sample.appspot.com/mobile*"
  service: mobile-frontend

# Send any domain/sub-domain with a path that starts with “work” to the static backend service.
- url: "*/work*"
  service: static-backend

You can also write expressions that are more strict:

# Matches the path "/fun", but not "/fun2" or "/fun/other"
- url: "*/fun"
  service: mobile-frontend

# Matches the hostname 'customer1.myapp.com', but not '1.customer1.myapp.com.
- url: "customer1.myapp.com/*"
  service: static-backend

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.

Was this page helpful? Let us know how we did:

Send feedback about...

App Engine flexible environment for Node.js docs