Add routes.yaml {all} option for route templates. (#4795)

* Add routes.yaml {all} option for route templates.
* Updated route redirects topic and improved examples

Author: meker12

_includes/cloud/note-pro-missing-self-service-options.md

@@ -0,0 +1,2 @@
+{: .bs-callout .bs-callout-info}
+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](http://support.magento.com) that describes the attempted configuration changes. Include any updated YAML configuration files in the ticket.

_includes/cloud/note-route-all-placeholder.md

@@ -0,0 +1,2 @@
+{: .bs-callout-info}
+The following route configuration examples use route templates with placeholders. The `{default}` placeholder represents the default domain configured for your site. If your project has multiple domains, use the `{all}` placeholder instead to configure routing for the default domain and all aliases. See [Configure routes]({{ page.baseurl }}/cloud/project/project-conf-files_routes.html).

guides/v2.1/cloud/project/project-conf-files_routes.md

@@ -6,18 +6,19 @@ functional_areas:
   - Setup
 ---
 
-{{site.data.var.ee}} processes an incoming URL using a *route*. The `routes.yaml` file—located at `.magento/routes.yaml` in your project—defines routes for the Integration environment. The deploy script uses values defined in the configuration files in the `.magento` directory and deletes the directory after deployment. Your local workspace is not affected.
+The `routes.yaml` file in the `.magento/routes.yaml` directory defines routes for your {{ site.data.var.ece }} Integration, Staging, and Production environments. Routes determine how Magento processes incoming HTTP requests.
 
-{% include cloud/note-pro-using-yaml-support.md %}
+{% include cloud/note-pro-missing-self-service-options.md %}
 
-The following is the default `routes.yaml` file:
+The default `routes.yaml` file contains the following code:
 
 ```yaml
 "http://{default}/":
-    type: upstream
+  type: upstream
     upstream: "mymagento:php"
 ```
 
+By default, Magento routes all HTTP requests to the {{ site.data.var.ee }} application.
 If you do not create a custom `routes.yaml` file, the automated deployment uses the default file.
 
 #### To list the configured routes:
@@ -31,26 +32,58 @@ magento-cloud environment:routes
 | http://{default}/ | upstream | mymagento:php |
 +-------------------+----------+---------------+
 ```
+{: .no-copy}
 
 ## Route templates
 
-The `routes.yaml` file is a list of templated routes and their configurations. A route template looks similar to this: `http://www.{default}/` or `https://{default}/blog`, where `{default}` is the qualified domain name configured for the project. For example, the routes for `example.com` domain resolve to the following:
+The `routes.yaml` file is a list of templated routes and their configurations. You can use the following placeholders in route templates:
 
--  `http://www.example.com/`
--  `https://example.com/blog`
+- `{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:
 
-{{site.data.var.ee}} also generates URLs for every active environment, so you can test that system. In a test system, `{default}` is replaced with the following:
+  ```text
+  http://www.example.com/
 
-```
+  http://www.example.com/blog
+  ```
+  {: .no-copy}
+
+  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:
+
+  ```text
+  http://www.example.com/
+
+  http://www.example.com/blog
+
+  http://www.example1.com/
+
+  http://www.example1.com/blog
+  ```
+  {: .no-copy}
+
+  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.
+
+{{site.data.var.ee}} also generates URLs for every active environment, so you can test that system. In a test system, `{default}` is replaced with the following domain name:
+
+```text
 [branch]-[project-id].[region].magentosite.cloud
 ```
+{: .no-copy}
 
-For example, if the project ID is `mswy7hzcuhcjw` on a branch called `refactorcss` hosted in the `us` cluster, the domains are: 
+For example, the `refactorcss` branch for the `mswy7hzcuhcjw` project hosted in the `us` cluster has the following the domains: 
 
--  `http://www-refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/`
--  `https://refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/blog`
+```text
+http://www-refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/
 
-<!-- {{site.data.var.ece}} also supports [multiple applications]({{ page.baseurl }}/cloud/project/project-conf-multi.html) per project. Each project has a single `routes.yaml` file that defines which request is routed to which application. -->
+https://refactorcss-mswy7hzcuhcjw.us.magentosite.cloud/blog
+```
+  {: .no-copy}
+
+{:.bs-callout-info}
+{{site.data.var.ece}} also supports [multiple applications]({{ page.baseurl }}/cloud/project/project-multi-sites.html) per project. Each project has a single `routes.yaml` file that defines which request is routed to which application.
 
 ## Route options
 
@@ -64,10 +97,9 @@ Property         | Description
 `redirects:`     | Controls [redirect rules]({{ page.baseurl }}/cloud/project/project-routes-more-redir.html).
 `ssi:`           | Controls enabling of [Server Side Includes]({{ page.baseurl }}/cloud/project/project-routes-more-ssi.html).
 
-
 ## Simple routes
 
-The following sample routes the apex domain and the `www` subdomain to the `frontend`application. This route does not redirect HTTPS:
+The following sample routes the apex domain and the `www` subdomain to the `frontend`application. This route does not redirect HTTPS requests:
 
 ```yaml
 "http://{default}/":
@@ -96,10 +128,10 @@ In the first sample, the server responds directly to a request of the form `http
 ## Wildcard routes
 {{site.data.var.ece}} supports wildcard routes, so you can map multiple subdomains to the same application. This works for [redirect](https://glossary.magento.com/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`
+- `*.example.com`
+- `www.example.com`
+- `blog.example.com`
+- `us.example.com`
 
 This functions as a catch-all domain in a live environment.
 
@@ -111,18 +143,20 @@ If you define a `http://www.{default}/` route, the route becomes `http://www.add
 
 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/`
+- `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:
 
 ```bash
 echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 --decode | json_pp
 ```
+{: .no-copy}
 
 ```terminal
 https://*.add-theme-projectID.us.magentosite.cloud/
 ```
+{: .no-copy}
 
 {: .bs-callout .bs-callout-info}
 Some projects provisioned before December 8, 2017, use the triple dash (\-\-\-) as a separator for the subdomain.

guides/v2.1/cloud/project/project-routes-more-cache.md

@@ -8,6 +8,8 @@ functional_areas:
 
 {{site.data.var.ee}} enables you to use caching in your environment. If you disable caching, {{site.data.var.ee}} directly serves the files.
 
+{% include cloud/note-route-all-placeholder.md %}
+
 ## Set up caching {#cloud-cache-setup}
 
 Enable caching in your Magento application's `.magento/routes.yaml` as follows:

guides/v2.1/cloud/project/project-routes-more-redir.md

@@ -6,142 +6,127 @@ functional_areas:
   - Setup
 ---
 
-Managing redirection rules is a common requirement for web applications, especially in cases where you do not want to lose incoming links that have changed or been removed over time. The following demonstrates how to manage redirection rules on your {{site.data.var.ece}} projects.
+Managing redirection rules is a common requirement for web applications, especially in cases where you do not want to lose incoming links that have changed or been removed over time.
 
-If the redirection methods discussed in this topic do not work for you, you can use caching headers to do the same thing.
+The following demonstrates how to manage redirection rules on your {{site.data.var.ece}} projects using the `routes.yaml` configuration file. If the redirection methods discussed in this topic do not work for you, you can use caching headers to do the same thing.
+
+{% include cloud/note-route-all-placeholder.md %}
 
 ## Whole-route redirects {#cloud-route-whole}
 
-Using whole-route redirects, you can define very basic routes using the `routes.yaml` file. For example, you can redirect from a naked domain to a `www` subdomain as follows:
+Using whole-route redirects, you can define simple routes using the `routes.yaml` file. For example, you can redirect from an apex domain to a `www` subdomain as follows:
 
 ```yaml
 http://{default}/:
     type: redirect
     to: http://www.{default}/
 ```
 
-## Partial redirects {#cloud-route-partial}
+## Partial-route redirects {#cloud-route-partial}
 
-In the [`.magento/routes.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_routes.html) file you can also add partial [redirect](https://glossary.magento.com/redirect) rules
-to existing routes:
+In the [`.magento/routes.yaml`]({{ page.baseurl }}/cloud/project/project-conf-files_routes.html) file, you can also add partial redirect rules to existing routes based on pattern matching:
 
 ```yaml
 http://{default}/:
     redirects:
         expires: 1d
         paths:
-            "/from": { "to": "http://example.com/" }
-            "/regexp/(.*)/matching": { "to": "http://example.com/$1", regexp: true }
+          "/from": { to: "http://example.com/" }
+          "/regexp/(.*)/matching": { to: "http://example.com/$1", regexp: true }
 ```
 
-This format is more rich and works with any type of route, including routes served directly by the application.
+Partial redirects work with any type of route, including routes served directly by the application.
 
 Two keys are available under `redirects`:
 
--  `expires`: Optional, the duration that the redirect is cached.
-    Examples of valid values include `3600s`, `1d`, `2w`, `3m`.
-
--  `paths`: The paths to apply the redirects to.
-
-The following defines each rule under `paths`:
-
--  A key that describes the expression to match against the request path
--  A value object describing both the destination to redirect to with detail on how to handle the redirection.
+- **expires**—Optional, specifies the amount of time to cache the redirect in the browser. Examples of valid values include `3600s`, `1d`, `2w`, `3m`.
 
-The value object is defined with the following keys:
+- **paths**—One or more key-value pairs that specify the configuration for partial-route redirect rules.
 
--  [`to`](#cloud-route-partial-to)
--  [`regexp`](#cloud-route-partial-regexp)
--  [`prefix`](#cloud-route-partial-prefix)
--  [`append_suffix`](#cloud-route-partial-append)
--  [`code`](#cloud-route-partial-code)
+  For each redirect rule, the key is an expression to filter request paths for redirection. The value is an object that specifies the target destination for the redirect and options for processing the redirect.
 
-### `to` {#cloud-route-partial-to}
+  The value object has the following properties:
 
-Required, a partial (`"/destination"` or `"//destination"`) or full URL (`"http://example.com/"`).
+  Property  | Description
+  ----------| -----------
+  `to`      | Required, a partial absolute path, URL with protocol and host, or pattern that specifies the target destination for the redirect rule.
+  `regexp`| Optional, defaults to `false`. Specifies whether the path key should be interpreted as a PCRE regular expression.
+  `prefix` | Specifies whether the redirect applies to both the path and all its children, or just the path itself. Defaults to `true`. This value is not supported if `regexp` is `true`.
+  `append_suffix`| Determines if the suffix is carried over with the redirect. Defaults to `true`. This value is not supported if the `regexp` key is `true` *or* if the `prefix` key is `false`.
+  `code`    | Specifies the HTTP status code. Valid status codes are [`301` (Moved Permanently)](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2), [`302`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3), [`307`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8), and [`308`](https://tools.ietf.org/html/rfc7238). Defaults to `302`.
+  `expires`| Optional, specifies the amount of time to cache the redirect in the browser. Defaults to the `expires` value defined directly under the `redirects` key, but at this level you can fine-tune the cache expiration for individual partial redirects.
 
-### `regexp` {#cloud-route-partial-regexp}
+### Examples
 
-Optional, defaults to `false`. Specifies whether the path key should be interpreted asa PCRE regular expression.
+The following examples show how to specify partial-route redirects in the `routes.yaml` file using various `paths` configuration options.
 
-{% collapsible Click to show/hide content %}
+#### Regular expression pattern matching {#redirect-with-regex}
 
-In the following example, a request to `http://example.com/regexp/a/b/c/match` redirects to `http://example.com/a/b/c`:
+Use the following format to configure redirect requests based on a regular expression.
 
 ```yaml
 http://{default}/:
     type: upstream
     redirects:
-        paths:
-            "/regexp/(.*)/match":
-                to: "http://example.com/$1"
-                regexp: true
+    paths:
+        "/regexp/(.*)/match": { to: "http://example.com/$1", regexp: true }
 ```
 
-{% endcollapsible %}
-
-### `prefix` {#cloud-route-partial-prefix}
-Specifies whether or not to redirect both the path and all its children or just the path itself. Defaults to `true`, but is not supported if `regexp` is `true`.
+This configuration filters request paths against a regular expression and redirects matching requests to `https://example.com`. For example, a request to `https://example.com/regexp/a/b/c/match` redirects to `https://example.com/a/b/c`.
 
-{% collapsible Click to show/hide content %}
+#### Prefix pattern matching {#redirect-with-prefix}
 
-For example,
+Use the following format to configure redirect requests for paths that begin with a specified prefix pattern.
 
 ```yaml
 http://{default}/:
     type: upstream
     redirects:
-        paths:
-            "/from":
-                to: "http://{default}/to"
-                prefix: true
+    paths:
+        "/from": { to: "https://{default}/to", prefix: true }
 ```
 
-In the preceding example, if `prefix` is set to `true`, `/from` redirects to `/to` and `/from/another/path` will redirect to `/to/another/path`
+This configuration works as follows:
 
-If `prefix` is set to `false`, `/from` triggers a redirect, but `/from/another/path` does not.
+- Redirects requests that match the pattern `/from` to the path `http://{default}/to`.
 
-{% endcollapsible %}
+- Redirects requests that match the pattern `/from/another/path` to `https://{default}/to/another/path`.
 
-### `append_suffix` {#cloud-route-partial-append}
-Determines if the suffix is carried over with the redirect. Defaults to `true`, but not supported if `regexp` is `true` *or* if `prefix` is `false`.
+- If you change the `prefix` property to `false`, requests that match the pattern  `/from` trigger a redirect, but requests that match the pattern `/from/another/path` does not.
 
-{% collapsible Click to show/hide content %}
+#### Suffix pattern matching {#redirect-with-suffix}
 
-For example,
+Use the following format to configure redirect requests which append the path suffix from the request to the target destination.
 
 ```yaml
 http://{default}/:
     type: upstream
     redirects:
-        paths:
-            "/from":
-                to: "http://{default}/to"
-                append_suffix: false
+    paths: { "/from": { to: "https://{default}/to", append_suffix: false }
 ```
 
-The preceding example results in `/from/path/suffix` redirecting to just `/to`.
+This configuration works as follows:
 
-If `append_suffix` is set to its default value of `true`, `/from/path/suffix` redirects to `/to/path/suffix`.
+- Redirects requests that match the pattern `/from/path/suffix` to the path `https://{default}/to`.
 
-{% endcollapsible %}
+- If you change the `append_suffix` property to `true`, then requests that match `/from/path/suffix`  redirect to the path `https://{default}/to/path/suffix`.
 
-### `code` {#cloud-route-partial-code}
+#### Path-specific cache configuration {#redirect-with-custom-cache}
 
-Specifies the HTTP status code. Valid status codes are [`301` (Moved Permanently)](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2), [`302`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3), [`307`](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8), and [`308`](https://tools.ietf.org/html/rfc7238). Defaults to `302`.
-
-### `expires` {#cloud-route-partial-expires}
-
-Optional, the duration to cache redirect. Defaults to the `expires` value defined directly under the `redirects` key, but at this level you can fine-tune the expiration of individual partial redirects:
+ Use the following format to customize the time to cache a redirect from a specific path:
 
 ```yaml
 http://{default}/:
     type: upstream
     redirects:
-        expires: 1d
-        paths:
-            "/from": { "to": "http://example.com/" }
-            "/here": { "to": "http://example.com/there", "expires": "2w" }
-```
+    expires: 1d
+    paths:
+        "/from": { to: "https://example.com/" }
+        "/here": { to: "https://example.com/there", expires: "2w" }
+  ```
+
+This configuration works as follows:
+
+- Redirects from the first path (`/from`) are cached for 1 day.
 
-In the preceding example, redirects from `/from` expire in one day, but redirects from `/here` expire in two weeks.
+- Redirects from the second path (`/here`) are cached for 2 weeks.

guides/v2.1/cloud/project/project-routes-more-ssi.md

@@ -6,9 +6,9 @@ functional_areas:
   - Setup
 ---
 
-[Server side includes](http://httpd.apache.org/docs/current/howto/ssi.html){:target="_site"} (SSI) are directives in [HTML](https://glossary.magento.com/html) pages that get evaluated on the server while the pages are being rendered. Use of [server side](https://glossary.magento.com/server-side) includes enables you to add dynamically generated content to an existing HTML page without having to serve the entire page.
+[Server side includes](http://nginx.org/en/docs/http/ngx_http_ssi_module.html) (SSI) are directives in [HTML](https://glossary.magento.com/html) pages that get evaluated on the server while the pages are being rendered. Use of [server side](https://glossary.magento.com/server-side) includes enables you to add dynamically generated content to an existing HTML page without having to serve the entire page.
 
-More information about [nginx SSI](http://nginx.org/en/docs/http/ngx_http_ssi_module.html).
+{% include cloud/note-route-all-placeholder.md %}
 
 You can activate or deactivate SSI on a per-route basis in your
 `.magento/routes.yaml`; for example: