Merge pull request platformsh#3449 from platformsh/domains-context

Complete vendorization for domains section

sites/friday/config/_default/config.yaml

@@ -63,6 +63,7 @@ module:
               - "increase-observability/metrics/dedicated-generation-3.md"
               - "domains/cdn/managed-fastly.md"
               - "domains/security/web-application-firewall/fastly.md"
+              - "domains/steps/custom-domains-preview-environments.md"
               - "dedicated-gen-2/*"
               - "dedicated-gen-3/*"
               - "guides/*"

sites/friday/src/domains/steps/custom-domains-preview-environments.md

@@ -0,0 +1,287 @@
+---
+title: Set up a custom domain on a preview environment
+sidebarTitle: Preview environments
+weight: 3
+description: Learn how to set up custom domains on your preview environments
+---
+
+{{% version/specific %}}
+{{< partial "progressive-rollout/body.md" >}}
+<--->
+{{% /version/specific %}}
+
+[Preview environments](/glossary.md#preview-environment) in your project can't use the custom domain [set up on your production environment](../steps/_index.md).<br/>
+By default and for each preview environment,
+{{< vendor/name >}} automatically replaces the custom production domain
+with an automatically generated URL.
+
+If you don't want to use these default URLs,
+you can add a custom domain to each of your preview environments
+(`staging` or `development` [environment types](/glossary.md#environment-type)).
+
+To do so, no need to modify your [routes configuration](../../define-routes/_index.md).
+When you add a new custom domain for a preview environment,
+just attach it to the custom production domain it replaces.
+If you have multiple custom production domains,
+you need to select which one you're replacing.
+
+{{< note title="Example" >}}
+
+You have two environments, a production environment and a staging environment.
+You've added the `example.com` custom domain to your production environment.
+
+You want to add the `staging.example.com` custom domain to your staging environment.
+To do so, you need to attach the new `staging.example.com` custom domain
+to its corresponding custom production domain `example.com`. 
+
+You can then access your staging environment through `staging.example.com`,
+and still access your production environment through `example.com`.
+
+{{< /note >}}
+
+If you have multiple custom domains on your production environment,
+when you set up a custom domain on a preview environment,
+you don't need to update your [routes configuration](../../define-routes/_index.md) either.
+{{< vendor/name >}} automatically figures out the routing of your preview environment
+based on the following elements:
+
+- The custom production domains in your existing [routes configuration](../../define-routes/_index.md)
+- The custom domains for preview environments attached to each of those custom production domains
+
+## Before you start
+
+You need:
+
+{{% version/specific %}}
+- A Grid or {{% names/dedicated-gen-3 %}} project on which you have **admin rights** <BR> 
+
+  {{< note theme="warning" >}}
+
+  If you have a {{% names/dedicated-gen-2 %}} project,
+  currently you can only add a custom domain to the dedicated environments of your project (production and staging).
+  To do so, [contact Support](https://console.platform.sh/-/users/~/tickets/open).
+
+  {{< /note >}}
+
+  If you use a [Managed Fastly](../cdn/managed-fastly.md) CDN,
+  it needs to be configured to operate with custom domains for preview environments.
+  For more information, [contact Support](https://console.platform.sh/-/users/~/tickets/open).
+{{% /version/specific %}}
+- A production environment with at least one custom domain already set up
+- At least one preview (staging or development) environment
+- Optional: The [{{< vendor/name >}} CLI](../../administration/cli/_index.md) (v4.8.0+)
+
+To prevent abuse, by default you can add custom domains to up to 5 preview environments per project only.
+This limit doesn't include the production environment,
+and you can increase it without charge.
+To do so, [contact Support](/learn/overview/get-support.md).
+
+{{< note >}}
+If you delete a custom production domain,
+all of the attached custom domains for preview environments are deleted too.
+You need to rebuild the affected preview environments for the deletion to be complete.
+{{< /note >}}
+
+{{% version/specific %}}
+If you downgrade from an Elite or Enterprise plan to a Professional plan,
+all of the custom domains set up on preview environments are automatically removed.
+Downgrading your plan doesn't affect custom domains set up on your production environments.
+{{% /version/specific %}}
+
+## Add a custom domain to a preview environment
+
+To add a custom domain to a preview environment, follow these steps:
+
+{{< codetabs >}}
++++
+title=Using the CLI
++++
+
+1. To get the target for your preview environment,
+   run the following command:
+
+   ```bash
+   {{% vendor/cli %}} environment:info edge_hostname --environment {{< variable "ENVIRONMENT_NAME" >}}
+   ```
+
+2. [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider).
+   In particular, make sure your DNS record points to the target of your preview environment.
+
+   {{< note >}}
+
+   Using the target of your production environment to configure your DNS provider is technically possible,
+   but {{< vendor/name >}} recommends using the target of your preview environment as a best practice.
+
+   {{< /note >}}
+
+3. Run a command similar to the following:
+
+   ```bash
+   {{% vendor/cli %}} domain:add staging.example.com --environment {{< variable "STAGING_ENVIRONMENT_ID" >}} --attach {{< variable "PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH" >}}
+   ```
+
+<--->
++++
+title=In the Console
++++
+
+1.  Get the target for your preview environment.</br>
+    To do so, navigate to your preview environment and click **{{< icon settings >}} Settings**.</br>
+    Select the **Domains** tab.</br>
+    In the **Configure your domain** section, copy the content of the **CNAME record** field.</br>
+    Save it for later use at step 7.
+
+2.  Click **Add domain**.
+
+3.  Name the custom domain for your preview environment.
+
+4.  Attach the custom domain for your preview environment to the desired production custom domain.
+
+5.  Click **Add**.
+
+6.  Click **Okay**.
+
+7.  [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider).</br>
+    In particular, make sure your DNS record points to the target of your preview environment.
+
+{{< note >}}
+
+Using the target of your production environment to configure your DNS provider is technically possible,
+but {{< vendor/name >}} recommends using the target of your preview environment as a best practice.
+
+{{< /note >}}
+
+{{< /codetabs >}}
+
+{{< note >}}
+
+You can’t update a custom domain when it's used on a preview environment.
+You can only delete it and create a new one as a replacement.
+
+{{< /note >}}
+
+### Example
+
+You've added the `mysite.com` custom domain to your production environment.
+You now want to add the `mydev.com` custom domain to a preview environment called `Dev`.
+
+To do so, follow these steps:
+
+{{< codetabs >}}
++++
+title=Using the CLI
++++
+
+Run the following command:
+
+```bash
+{{% vendor/cli %}} domain:add mydev.com --environment Dev --attach mysite.com
+```
+
+<--->
++++
+title=In the Console
++++
+
+1.  Get the target for `Dev`.</br>
+    To do so, navigate to `Dev` and click **{{< icon settings >}} Settings**.</br>
+    Select the **Domains** tab.</br>
+    In the **Configure your domain** section, copy the content of the **CNAME record** field.</br>
+    Save it for later use at step 7.
+
+2.  Click **Add domain**.
+
+3.  Enter `mydev.com` as a name for the custom domain you want to add to `Dev`.
+
+4.  Select `mysite.com` as the production custom domain you want to attach `mydev.com` to.
+
+5.  Click **Add**.</br>
+
+6.  Click **Okay**.
+
+7.  [Configure your DNS provider](../steps/_index.md#3-configure-your-dns-provider).</br>
+    In particular, make sure your DNS record points to `Dev`'s target.
+
+{{< /codetabs >}}
+
+In the above example, the `Dev` environment needs to exist
+for you to add the `mydev.com` custom domain successfully.
+If the `Dev` environment is later removed,
+the `mydev.com` custom domain is removed too.
+
+## List the custom domains of a preview environment
+
+{{< codetabs >}}
++++
+title=Using the CLI
++++
+
+Run a command similar to the following:
+
+```bash
+{{% vendor/cli %}} domain:list --environment {{< variable "STAGING_ENVIRONMENT_ID" >}}
+```
+
+<--->
++++
+title=In the Console
++++
+
+1. Navigate to your preview environment and click **{{< icon settings >}} Settings**.
+2. Select the **Domains** tab.</br>
+   All the custom domains for your preview environment are displayed.
+
+{{< /codetabs >}}
+
+## Get a specific custom domain used on a preview environment
+
+{{< codetabs >}}
++++
+title=Using the CLI
++++
+
+Run a command similar to the following:
+
+```bash
+{{% vendor/cli %}} domain:get staging.example.com --environment {{< variable "STAGING_ENVIRONMENT_ID" >}}
+```
+
+<--->
++++
+title=In the Console
++++
+
+1. Navigate to your preview environment and click **{{< icon settings >}} Settings**.</br>
+2. Select the **Domains** tab.</br>
+   All the custom domains for the selected environment are displayed.
+3. To see which actions you can perform on a displayed custom domain,
+   click **{{< icon "more" >}} More** next to it.
+
+{{< /codetabs >}}
+
+## Remove a custom domain from a preview environment
+
+{{< codetabs >}}
++++
+title=Using the CLI
++++
+
+Run a command similar to the following:
+
+```bash
+{{% vendor/cli %}} domain:delete staging.example.com --environment {{< variable "STAGING_ENVIRONMENT_ID" >}}
+```
+
+<--->
++++
+title=In the Console
++++
+
+1. Navigate to your preview environment and click **{{< icon settings >}} Settings**.
+2. Select the **Domains** tab.</br>
+   All the custom domains for the selected environment are displayed.
+3. Click **{{< icon "more" >}} More** on the custom domain you want to delete.
+4. Click **Delete**.
+5. Click **Yes, delete**.
+
+{{< /codetabs >}}

sites/platform/src/domains/cdn/_index.md

@@ -62,6 +62,8 @@ see your CDN provider's official documentation.
 When you use a CDN, the {{< vendor/name >}} router [HTTP caching](../../define-routes/cache.md) becomes redundant.
 To disable it, change your cache configuration for the routes behind a CDN to the following:
 
+{{< version/specific >}}
+<!-- Platform.sh -->
 ```yaml {configFile="routes"}
 "https://{default}/":
    type: upstream
@@ -70,8 +72,20 @@ To disable it, change your cache configuration for the routes behind a CDN to th
        # Disable the HTTP cache on this route. It's handled by the CDN instead.
        enabled: false
 ```
+<--->
+<!-- Upsun -->
+```yaml {configFile="routes"}
+routes:
+  "https://{default}/":
+     type: upstream
+     upstream: "app:http"
+     cache:
+         # Disable the HTTP cache on this route. It's handled by the CDN instead.
+         enabled: false
+```
+{{< /version/specific >}}
 
-{{< version/only "1" >}}
+{{< version/specific >}}
 ## Configure your CDN to support high SLA
 
 {{< premium-features/tiered "Enterprise and Elite" >}}
@@ -85,7 +99,9 @@ If you want {{< vendor/name >}} to limit checks to one or more of the following
 - Europe
 - East Asia / Oceania
 
-{{< /version/only >}}
+<--->
+
+{{< /version/specific >}}
 
 ## Prevent direct access to your server
 
@@ -139,15 +155,32 @@ To enable client-authenticated TLS, follow these steps:
 
 4.  Change your routing configuration for the routes behind a CDN to the following:
 
-    ```yaml {configFile="routes"}
-    https://{default}:
+    {{< version/specific >}}
+
+```yaml {configFile="routes"}
+"https://{default}":
+    tls:
+        client_authentication: "require"
+        client_certificate_authorities:
+            - !include
+                type: string
+                path: cdn.crt
+```
+
+    <--->
+
+```yaml {configFile="routes"}
+routes:
+    "https://{default}":
         tls:
             client_authentication: "require"
             client_certificate_authorities:
                 - !include
-                  type: string
-                  path: cdn.crt
-    ```
+                    type: string
+                    path: cdn.crt
+```
+
+    {{< /version/specific >}}
 
 The procedure can vary depending on your CDN.
 Contact your CDN provider for specific assistance.

sites/platform/src/domains/cdn/cloudflare.md

@@ -22,7 +22,7 @@ To properly configure your Cloudflare CDN,
 see the Cloudflare official documentation on [how to get started](https://developers.cloudflare.com/cache/get-started/).
 Then set up a [custom domain](../steps/_index.md).
 To get the [DNS challenge to succeed](../troubleshoot.md#ownership-verification),
-have your CDN point to your [project's target URL](../../domains/steps/_index.md#2-get-the-target-for-your-project).
+have your CDN point to your [project's target URL](../../domains/steps/_index.md#1-get-the-target-for-your-project).
 
 ## 3. Handle apex domains
 

sites/platform/src/domains/cdn/fastly.md

@@ -35,7 +35,7 @@ To properly configure your Fastly CDN,
 see the Fastly official documentation on [how to get started](https://docs.fastly.com/en/guides/getting-started#_basics).
 Then set up a [custom domain](../steps/_index.md).
 To get the [DNS challenge to succeed](../troubleshoot.md#ownership-verification),
-have your CDN point to your [project's target URL](../../domains/steps/_index.md#2-get-the-target-for-your-project).
+have your CDN point to your [project's target URL](../../domains/steps/_index.md#1-get-the-target-for-your-project).
 
 ## 3. Handle apex domains