Configure routes

The routes.yaml file in the .magento/routes.yaml directory defines routes for your Magento Commerce Cloud Integration, Staging, and Production environments. Routes determine how Magento processes incoming HTTP requests.

On Pro projects, we recommend updating YAML configuration files in an Integration environment and testing the changes before pushing the updates to Staging and Production environments. If you discover that configuration changes are not applied to Staging and Production sites after you redeploy and do not see any related error messages in the log, submit a Support ticket that describes the attempted configuration changes. Include any updated YAML configuration files in the ticket.

The default routes.yaml file specifies the route templates for processing HTTP requests on projects that have a single default domain and on projects configured for multiple domains:

1
2
3
4
5
6
"http://{default}/":
    type: upstream
    upstream: "mymagento:http"
"http://{all}/":
    type: upstream
    upstream: "mymagento:http"

If you do not create a custom routes.yaml file, the automated deployment uses the default file.

Use the magento-cloud CLI to view a list of the configured routes:

1
2
3
4
5
6
7
magento-cloud environment:routes

+-------------------+----------+---------------+
| Route             | Type     | To            |
+-------------------+----------+---------------+
| http://{default}/ | upstream | mymagento:php |
+-------------------+----------+---------------+

Route templates

The routes.yaml file is a list of templated routes and their configurations. You can use the following placeholders in route templates:

• {default} represents the qualified domain name configured as the default for the project. For example, if you have a project with the default domain example.com, the route templates http://www.{default}/ and https://{default}/blog resolve to the following URLs in a production environment:

  1
  2
  3
  http://www.example.com/
  
  https://www.example.com/blog
  

  In a non-production branch, the project ID and environment ID replace the {default} placeholder when the project is deployed.

• {all} represents all the domain names configured for the project. For example, if you have a project with example.com and example1.com domains, the route templates http://www.{all}/ and https://{all}/blog resolve to routes for all domains in the project:

  1
  2
  3
  4
  5
  6
  7
  http://www.example.com/
  
  http://www.example.com/blog
  
  https://www.example1.com/
  
  https://www.example1.com/blog
  

  The {all} placeholder is useful for projects configured for multiple domains. In a non-production branch {all} is replaced with the project ID and environment ID for each domain.

  If a project does not have any domains configured, which is common during development, the {all} placeholder behaves in the same way as the {default} placeholder.

Magento Commerce also generates routes for every active Integration environment. For Integration environments, {default} is replaced with the following domain name:

1
[branch]-[project-id].[region].magentosite.cloud

For example, the refactorcss branch for the mswy7hzcuhcjw project hosted in the us cluster has the following the domains:

1
2
3
http://www-refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/

https://refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/blog

Magento Commerce Cloud also supports multiple applications per project. Each project has a single routes.yaml file that defines which request is routed to which application.

Route options

Configure each route separately using the following properties:

Simple routes

The following sample routes the apex domain and the www subdomain to the frontend application. This route does not redirect HTTPS requests:

1
2
3
4
5
6
7
"http://{default}/":
    type: upstream
    upstream: "frontend:http"

"http://www.{default}/":
    type: redirect
    to: "http://{default}/"

The following sample route does not redirect from the www to the apex domain; instead, it serves from both:

1
2
3
4
5
6
7
"http://{default}/":
    type: upstream
    upstream: "frontend:http"

"http://www.{default}/":
    type: upstream
    upstream: "frontend:http"

In the first sample, the server responds directly to a request of the form http://example.com/hello, but it issues a 301 redirect for http://www.example.com/mypath (to http://example.com/mypath).

Wildcard routes

Magento Commerce Cloud supports wildcard routes, so you can map multiple subdomains to the same application. This works for redirect and upstream routes. You prefix the route with an asterisk (*). For example, the following routes to the same application:

• *.example.com
• www.example.com
• blog.example.com
• us.example.com

This functions as a catch-all domain in a live environment.

Routing a non-mapped domain

You can route to a system that is not mapped to a domain using a dot (.) to separate the subdomain. For example, a project with an add-theme branch routes to http://add-theme-projectID.us.magento.com/.

If you define a http://www.{default}/ route, the route becomes http://www.add-theme-projectID.us.magento.com/.

You can put any subdomain before the dot and the route resolves. In this example, the route is defined as http://*.{default}/, so both of the following URLs work:

• http://foo.add-theme-projectID.us.magentosite.cloud/
• http://bar.add-theme-projectID.us.magentosite.cloud/

If you examine the routes of this sample application, you see:

1
echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 --decode | json_pp

1
https://*.add-theme-projectID.us.magentosite.cloud/

See more information about caching.

Redirects and caching

As discussed in more detail in Redirects, you can manage complex redirection rules, such as partial redirects, and specify rules for route-based caching:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
http://www.{default}/:
    type: redirect
    to: https://{default}/
http://{default}/:
    type: redirect
    to: https://{default}/
https://{default}/:
    cache:
        cookies: [""]
        default_ttl: 0
        enabled: true
        headers:
            - Accept
            - Accept-Language
    ssi:
        enabled: false
    type: upstream
    upstream: php:http