📝 Update DNS configuration instructions (#2447)

* 🚧 Refactoring + adding vars + rephrasing * 🚧 Rebase from main * 📝 Smaller fixes * 🚧 Refactoring + adding vars + rephrasing * 📝 Smaller fixes + fix linting issuest * 🐛 Fix linting issues * 📝 Apply recommendations from review * 🐛 Fix links * 📝 Fix linting * 📝 Update DNS configuration instructions * 📝 Fix links * 📝 Smaller fixes * 🐛 Fix linting issues * 🚧 Apply recommendations from review + refactoring 🚧 Refactoring + adding vars 📝 Test * 🚧 Refactoring + adding vars + rephrasing * 🚧 Rebase from main * 📝 Smaller fixes * 🚧 Refactoring + adding vars + rephrasing 📝 Smaller fixes + fix linting issuest 🐛 Fix linting issues 📝 Apply recommendations from review 🐛 Fix links 📝 Fix linting 📝 Update DNS configuration instructions 📝 Fix links 📝 Smaller fixes 🐛 Fix linting issues 🚧 Apply recommendations from review + refactoring 🚧 Refactoring + adding vars 📝 Test * 📝 Applying recommendations and further improvements * 📝 (re-)applied recommendations + smaller rephrasing and improvements * 📝 Apply suggestions from code review Co-authored-by: Aaron Collier <[email protected]> * 📝 Apply feedback from review + fix previous mistakes * 📝 Apply suggestions from code review Co-authored-by: Aaron Collier <[email protected]> * 📝 Apply suggestions from code review Co-authored-by: Aaron Collier <[email protected]> * 📝 Apply suggestions from code review Co-authored-by: Aaron Collier <[email protected]> * 📝 Further changes from review * 🎨 Styling changes * 🐛 Add alias for deleted page * 📝 Add link to explanation on apex domains Co-authored-by: Aaron Collier <[email protected]>
platformsh · Nov 8, 2022 · 27f4b2b · 27f4b2b
1 parent 03ad14a
commit 27f4b2b
Show file tree

Hide file tree

Showing 19 changed files with 646 additions and 536 deletions.
diff --git a/docs/src/define-routes/_index.md b/docs/src/define-routes/_index.md
@@ -130,7 +130,7 @@ Each route in your configuration file is defined in one of two ways:
 * A URL with a placeholder such as `https://{default}/blog`
 
 The available placeholders are `{default}` and `{all}`.
-They stand in for the [custom domains](../domains/quick-start.md) you've defined in your project.
+They stand in for the [custom domains](../domains/steps/_index.md) you've defined in your project.
 
 These domains can be top-level domains (`example.com`) or subdomains (`app.example.com`).
 
@@ -272,7 +272,7 @@ In projects created before November 2017, the `.` in subdomains was replaced wit
 It was switched to preserve `.` to simplify SSL handling and improve support for longer domains.
 If your project was created before November 2017, it still uses `---` to the left of the environment name.
 If you wish to switch to dotted-domains, please file a support ticket and we can do that for you.
-Doing so may change the domain name that your production domain name should CNAME to.
+Doing so may change the domain name that your production domain name should `CNAME` to.
 
 {{< /note >}}
 

diff --git a/docs/src/define-routes/https.md b/docs/src/define-routes/https.md
@@ -14,21 +14,11 @@ The Let’s Encrypt TLS Certificates are:
 - automatically renewed 28 days before expiration
 
 If a renewal is available and needed, the environment is automatically redeployed to renew the certificate.
-As no new build is required the process should take at most a few seconds.
+As no code changes are made, the build image is reused and build books are not run.
 The deploy and post-deploy hook are run during this process.
-
-{{< note >}}
-Platform.sh provides managed service and runtime containers for your projects --
-security and system upgrades to those containers are applied automatically by us in the background.
-Whether or not an upgrade needs to be applied is judged during redeploys, but also during this renewal process.
+During the redeploy, security and system upgrades are automatically applied to your containers when required.
 That means that most of the time renewals take a few seconds *unless* upgrades are available for your containers.
-In those cases, containers are rebooted and the process takes a little longer. 
-{{< /note >}}
-
-If you are using a custom TLS certificate, seven days before it expires
-Platform.sh issues a Let's Encrypt certificate and replaces the custom certificate with it to avoid interruption in service.
-If you wish to continue using the custom certificate,
-replace it with an updated certificate more than seven days before it expires.
+In those cases, containers are rebooted and the process takes a little longer.
 
 {{< note >}}
 TLS certificates are often still called SSL certificates.
@@ -40,7 +30,7 @@ In practice, they mean the same thing today, but TLS is the more correct term.
 
 {{% lets_encrypt_limitations %}}
 
-If you need more hostnames than that, obtain additional certificates or a wildcard certificate from another TLS provider. 
+If you need more hostnames than that, obtain additional certificates or a wildcard certificate from a [third-party issuer](../domains/steps/tls.md).
 Alternatively, consider splitting your project up into multiple Platform.sh projects.
 
 ## Using HTTPS

diff --git a/docs/src/domains/_index.md b/docs/src/domains/_index.md
@@ -1,6 +1,6 @@
 ---
-title: "Custom Domains"
+title: "Custom domains"
 weight: -70
 description: |
-  By default, a Platform.sh app is available at its Platform.sh domain. The following resources help you take your application live with the domain that you wish.
+  By default, a Platform.sh app is available at its Platform.sh domain. The following resources help you take your app live with the domain that you wish.
 ---
diff --git a/docs/src/domains/cdn/_index.md b/docs/src/domains/cdn/_index.md
@@ -1,39 +1,35 @@
 ---
-title: "Content Delivery Networks (CDNs)"
-sidebarTitle: "Content Delivery Networks"
+title: "Content delivery networks (CDNs)"
+sidebarTitle: "Content delivery networks"
 weight: 3
+description: Improve performance for distributed end-users of your website with a content delivery network (CDN).
 layout: single
 ---
 
+Effective caching can mean a huge difference in the perceived performance of an app by its users.
+Placing the caches closer to your users (wherever they may be) is the best solution currently available.
+
 Dedicated plans include a Fastly CDN account by default, which is managed by Platform.sh.
-Our experience has shown that effective caching can mean a huge difference in the perceived performance of an application by its users,
-and that placing the caches closer to your users (wherever they may be) is the best solution currently available.
 
-Self-Service Grid plans do not include a CDN by default, but you are welcome to configure one yourself.
+Self-Service Grid plans don't include a CDN by default, but you are welcome to configure one yourself.
 See our [guidelines](../../bestpractices/http-caching.md) for when and if to use a CDN for HTTP caching.
 
-We have partnerships with a variety of CDN vendors depending on your application’s needs.
 Our recommended CDN provider is [Fastly](./fastly.md).
 
 ## DNS management
 
 The distributed nature of most CDNs means that for proper functioning,
-any domains that you intend to make use of the CDN are required to use CNAME records for pointing the DNS entries.
-Pointing the root domain (example.com) at a CNAME record isn't possible for all DNS hosts,
-so you need to confirm this functionality or migrate to a new DNS host.
-CloudFlare has a [more detailed writeup](https://blog.cloudflare.com/introducing-cname-flattening-rfc-compliant-cnames-at-a-domains-root/)
-of the challenges of root CNAMEs.
+any domains that you intend to make use of the CDN are required to use `CNAME` records for DNS entries.
+Not all DNS registrars support pointing from an apex domain such as `example.com` to a hostname with a `CNAME` record.
+Ideally, your registrar supports [`CNAME` records for apex domains](../steps/dns.md#handling-apex-domains).
 
-In the event that you and your team choose a pure Fastly solution,
-this is negated by their providing a set of Anycast IP addresses for you.
-This allows you to create A records for your root domain that point to Fastly’s CDN.
+CDNs have different methods to overcome this issue.
+CloudFlare uses [`CNAME` flattening](https://blog.cloudflare.com/introducing-cname-flattening-rfc-compliant-cnames-at-a-domains-root/).
+Fastly provides a set of Anycast IP addresses so you can [create A records for your root domain pointing to Fastly’s CDN](https://docs.fastly.com/en/guides/using-fastly-with-apex-domains).
 
 ## Initial setup
 
-For Dedicated plans, CDN setup is handled by Platform.sh as part of your onboarding.
-After the application is stood up on its Dedicated virtual machines,
-we can begin the collaborative process of provisioning the CDN and configuring DNS and caching setup.
-We provide CDN services for both staging and production.
+For Dedicated plans, a CDN is set up automatically for both Staging and Production environments as part of your onboarding.
 
 For self-service Grid plans, the setup can be done at any time by the customer.
 
@@ -44,27 +40,26 @@ there may be varying levels of flexibility with regard to caching and ongoing ca
 This should be discussed between your sales representative and senior technical members of your team
 if there are concerns with CDN configuration and functionality.
 
-If using Fastly as a CDN, you can provide either custom VCL snippets or a full custom VCL file.
-Platform.sh grants customers access to do so upon request.
+If using Fastly as a CDN, you can provide custom VCL snippets or a full custom VCL file through a [support ticket](../../overview/get-support.md).
 Be aware that downtime caused by custom VCL configuration isn't covered by the SLA,
-just as application code in your repository isn't covered by the SLA.
+just as app code in your repository isn't covered by the SLA.
 
 ## TLS encryption
 
 Security and the related topic of encryption of data are fundamental principles at Platform.sh,
-and as such we provide TLS certificates in the default Dedicated package.
-This allows for encryption of all traffic between your users and your application.
+and so Dedicated packages include TLS certificates by default.
+This allows for encryption of all traffic between your users and your app.
 By default, a shared certificate is provisioned with the chosen CDN vendor.
 If you opt for the Global Application Cache, certificates are provisioned for both the site subdomain (`www`) and the asset/CDN subdomain.
-We use wildcard certificates to secure production, staging, and any other subdomains simultaneously.
+Wildcard certificates are used to secure Production and Staging environments and any other subdomains simultaneously.
 If you need Extended Validation TLS certificates,
-you need to provide your own from an issuer of your choice that we can install for you.
+you need to provide your own from an issuer of your choice that can then be installed for you.
 
 If you need to provide your own TLS certificate, place the certificate, the unencrypted private key,
-and the necessary certificate chain supplied by your TLS provider in your application's `private` directory (not web accessible),
+and the necessary certificate chain supplied by your TLS provider in your app's `private` directory (not web accessible),
 and then open a ticket to let our team know to install it.
 
-Dedicated supports a single TLS certificate on the origin.
+Dedicated plans support a single TLS certificate on the origin.
 Support for multiple certificates is offered only through a CDN such as CloudFront or Fastly.
 Self-signed certificates can optionally be used on the origin for development purposes or for enabling TLS between the CDN and origin.
 
@@ -81,28 +76,28 @@ So it uses the origin name provided by Platform.sh.
 To ensure your TLS certificates are valid for both requests from clients to the CDN and from the CDN to the server on Platform.sh,
 you need to take two additional steps:
 
-1. Configure your CDN to set the `X-Forwarded-Host` HTTP header to the public domain (`example.com`).
+1. Configure your CDN to set the `X-Forwarded-Host` HTTP header to your domain, for example: `example.com`.
    That allows the request from the CDN to Platform.sh to still carry the original requested domain.
    The specific way to do so varies by the CDN.
-2. Ensure your application can read from the `X-Forwarded-Host` header should it need the Host information.
-   Many popular applications already do so,
-   but if you have a custom application make sure that it checks for that header
+2. Ensure your app can read from the `X-Forwarded-Host` header should it need the Host information.
+   Many popular apps already do so,
+   but if you have a custom app make sure that it checks for that header
    and uses it instead of `Host` as appropriate.
 
 ## Web Application Firewall & Anti-DDoS
 
 All Platform.sh-hosted sites, either Grid or Dedicated, live on infrastructure provided by major cloud vendors.
-These vendors include their own Level 3 DDoS protection that is sufficient for the vast majority of cases.
+These vendors include their own Level 3 DDoS protection that is sufficient for the majority of cases.
 
 Customers are welcome to put their own WAF in front of a Dedicated cluster or add other security measures not included in the offering.
 
 ## The router cache
 
 When using a CDN the Platform.sh router's HTTP cache becomes redundant.
 In most cases it's best to disable it outright.
-Modify your route in `.platform/routes.yaml` like so to disable the cache:
+Modify your route like so to disable the cache:
 
-```yaml
+```yaml {location=".platform/routes.yaml"}
 "https://{default}/":
     type: upstream
     upstream: "app:http"
@@ -114,79 +109,75 @@ Modify your route in `.platform/routes.yaml` like so to disable the cache:
 ## Preventing direct access
 
 When using a CDN, you might not want users to access your Platform.sh origin directly.
-There are three ways to secure your origin.
-
-### Password protected HTTP Authentication
-
-You can password protect your project using [HTTP access control](../../environments/http-access-control.md).
-
-Make sure that you generate a password of sufficient strength.
-You can then share the password with your CDN provider.
-Make sure the CDN adds a header to authenticate correctly to your origin.
+There are three ways to secure your origin:
 
-Add a custom header to the origin request with the base64 encoded username:password.
+- **Password protected HTTP Authentication**: Restrict access to your project with the [HTTP access control](../../environments/http-access-control.md).
+- **Allowing and denying IP addresses**: If your CDN doesn't support adding headers to the request to origin, you can allow the IP addresses of your CDN.
+- **Client-authenticated TLS**.
 
-For example: `Aladdin:OpenSesame` would become `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l`.
+### Password protected HTTP authentication
 
-Be aware that this approach applies the same user and password to all development environments, too.
+This approach applies the same username and password to your production and all development environments.
 You can have developers enter credentials through their browser,
 or override the access control setting for each child environment.
 
-{{< note >}}
+To use password protected HTTP Authentication:
 
-This is the recommended approach for CloudFlare.
-
-{{< /note >}}
+1. Consult your CDN's documentation to ensure it supports that feature.
+2. Generate a password of sufficient strength.
+3. Password protect your project using [HTTP access control](../../environments/http-access-control.md).
+4. Share the password with your CDN provider.
+5. Make sure the CDN adds a header to authenticate correctly to your origin by adding a custom header to the origin request with the base64 encoded `username:password` you chose in step 2.
+   For example: `Aladdin:OpenSesame` would become `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l`.
 
 ### Allowing and denying IP addresses
 
-If your CDN doesn't support adding headers to the request to origin, you can allow the IP addresses of your CDN.
-
-{{< note >}}
-You *WILL* have to update your configuration when your CDN updates their IP addresses.
-{{< /note >}}
-
-List of IP ranges for:
-
-- [CloudFlare](https://www.cloudflare.com/ips/)
-- [Fastly](https://docs.fastly.com/en/guides/accessing-fastlys-ip-ranges)
-
-Be aware that this approach applies the same IP restrictions to all development environments, too.
+This approach applies the same IP restrictions to your production and all development environments.
 To remove it from development environments, you need to disable it on each environment
-or else create a single child of the default environment where it is disabled,
+or else create a single child of the default environment where it is disabled
 and them make all development branches off of that environment.
 
-### Client authenticated TLS
+You also have to update your configuration when your CDN updates their IP addresses.
 
-If your CDN offers this option, an alternative way of securing the connection is [client authenticated TLS](../../define-routes/https.md#client-authenticated-tls).
+To allow and deny IP addresses:
 
-**note**: Remember to permit your developers to access the origin by creating your own certificate
-or else they won't be able to access the project URL directly (see below).
+1. Set up your CDN.
+2. Get the IP range for your CDN provider:
 
-CloudFlare has [a very good article](https://developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/)
-on what client authenticated TLS is and how to set this up.
+    - [CloudFlare](https://www.cloudflare.com/ips/)
+    - [Fastly](https://docs.fastly.com/en/guides/accessing-fastlys-ip-ranges)
 
-To activate authenticated TLS follow the following steps:
+3. Allow only these IPs for your project using [HTTP access control](../../environments/http-access-control.md#filter-ip-addresses).
 
-- Download the correct certificate from your CDN provider.
-     - [CloudFlare](https://developers.cloudflare.com/ssl/static/authenticated_origin_pull_ca.pem)
-         - *Caveat! an attacker could make a Cloudflare account to bypass your origin restriction. For CloudFlare, using the HTTP access control described above is the recommended way of securing your origin.*
-     - [Fastly](https://docs.fastly.com/products/waf-tuning-plus-package#authenticated-tls-to-origin)
-- Make sure you have a `.crt` file. If you have a `.pem` file, rename it to `cdn.crt`
-- Add the `cdn.crt` to your git repository
-- Add the relevant configuration to your `.platform.app.yaml` file
-```
-tls:
-    client_authentication: "require"
-    client_certificate_authorities:
-        - !include
-            type: string
-            path: cdn.crt
-```
+### Client-authenticated TLS
 
-{{< note >}}
+If your CDN offers this option, an alternative way of securing the connection is [client-authenticated TLS](../../define-routes/https.md#client-authenticated-tls).
+Note: Remember to permit your developers to access the origin by creating your own certificate
+or else they can't access the project URL directly.
 
-The steps above are generally similar but can vary for different CDN providers.
-Contact your CDN provider's support department for specific assistance.
+To activate authenticated TLS follow the following steps:
 
-{{< /note >}}
+1. Download the certificate from your CDN provider:
+    - [CloudFlare](https://developers.cloudflare.com/ssl/static/authenticated_origin_pull_ca.pem).
+      Using client-authenticated TLS with Cloudflare is the recommended approach.
+      It avoids the possibility that an attacker could make a Cloudflare account to bypass your origin restriction.
+      Use the authenticated origin pull method to secure your origin.
+    - [Fastly](https://docs.fastly.com/products/waf-tuning-plus-package#authenticated-tls-to-origin)
+
+2. Make sure you have a `.crt` file.
+   If you have a `.pem` file, rename it to `cdn.crt`.
+3. Add the `cdn.crt` file to your Git repository
+4. Add the relevant configuration:
+
+   ```yaml {location=".platform/routes.yaml"}
+   https://{default}:
+       tls:
+           client_authentication: "require"
+           client_certificate_authorities:
+               - !include
+                 type: string
+                 path: cdn.crt
+   ```
+
+These steps are generally similar but can vary for different CDN providers.
+Contact your CDN provider's support for specific assistance.