feat(edge): add Edge Services how tos and concepts

menu/navigation.json

@@ -2809,7 +2809,7 @@
                   },
                   {
                     "label": "Create a Load Balancer pipeline",
-                    "slug": "create-pipeine-lb"
+                    "slug": "create-pipeline-lb"
                   },
                   {
                     "label": "Configure a custom domain",
@@ -3772,10 +3772,6 @@
                     "label": "Use Object Storage with Private Networks",
                     "slug": "use-obj-stor-with-private-networks"
                   },
-                  {
-                    "label": "Use Object Storage with Edge Services",
-                    "slug": "get-started-edge-services"
-                  },
                   {
                     "label": "Delete an object",
                     "slug": "delete-an-object"

network/edge-services/concepts.mdx

@@ -11,4 +11,55 @@ dates:
   validation: 2024-07-24
 categories:
   - networks
----
+---
+
+## Cache
+
+The storage location where Edge Services stores copies of content that it has retrieved from a given origin. When users request content from the Edge Services endpoint, it serves content directly from the cache wherever possible, in accordance with the caching rules defined by the user. This reduces load on the origin bucket or Load Balancer/backend servers.
+
+Note that if an object has a caching directive, the caching directive always takes precedence over any lifetime setting defined in Edge Services.
+
+## Certificate
+
+The SSL/TLS certificate for your subdomain to enable Edge Services to serve content over HTTPS, if you have customized your [Edge Services endpoint](#endpoint). You can choose between uploading your own certificate held in Scaleway Secret Manager, or letting Edge Services generate a fully-managed Let's Encrypt certificate.
+
+## CNAME record
+
+The CNAME record pointing your subdomain to the Edge Services endpoint, if you have customized your [Edge Services endpoint](#endpoint). This is necessary to ensure that traffic for your customized subdomain is correctly directed towards the Edge Services endpoint by DNS servers.
+
+## Edge Services
+
+Edge Services is an additional feature for Scaleway Load Balancers and Object Storage buckets, currently available in [Public Beta](https://www.scaleway.com/en/betas/). It provides a [caching service](/network/edge-services/how-to/configure-cache/) to improve performance by reducing load on your [origin](#origin), and a customizable and secure [endpoint](#endpoint) for accessing content via Edge Services, which can be set to a subdomain of your choice.
+
+## Endpoint
+
+The endpoint from which a given Edge Services pipeline can be accessed, e.g. `https://pipeline-id-or-bucket-name.svc.edge.scw.cloud`. When a client requests content from the Edge Services endpoint, it is served by Edge Services and its cache, rather than from the origin (Object Storage bucket or Load Balancer backend servers) directly. Edge Services automatically manages redirection from HTTP to HTTPS.
+
+The endpoint can be customized with a user-defined subdomain, allowing you to replace the standardized endpoint with the subdomain of a domain you already own, e.g. `http://my-own-domain.com`. An associated [certificate](#certificate), and [CNAME record](#cname) will be required, in this case.
+
+## Origin
+
+The primary source from which a Scaleway Edge Services pipeline retrieves and caches data. An origin can consist of either:
+
+- An [Object Storage bucket](/storage/object/how-to/create-a-bucket/), or
+- A [Load Balancer](#origin-load-balancer) and frontend port that Edge Services connects to to request content, and (optionally) a specified [host](#origin-host) associated with the Load Balancer, used in the HTTP request Host Header.
+
+## Origin host
+
+In the case of a Load Balancer origin, the specific host for which Edge Services requests and caches data. This is an optional setting: when specified, this host (e.g. `mydomain.com`) is used in the HTTP Host Header when Edge Services requests data from the Load Balancer. If no origin host is specified, the Load Balancer's IP address is used in the Host Header. 
+
+The origin host must be associated with the origin Load Balancer / its backend servers, and only one host may be set per pipeline. If your Load Balancer is in front of multiple hosts, you can create a separate Edge Services pipeline for each. Each host will therefore get its own Edge Services endpoint and cache.
+
+## Origin Load Balancer
+
+The Load Balancer defined by the user as origin for a given Edge Services pipeline. The pipeline connects to this Load Balancer, on the specified frontend port to request content.
+
+## Pipeline
+
+An Edge Services pipeline consists of an [origin](#origin) for which Edge Services requests and [caches](#cache) content, and an [endpoint](#endpoint) from which this content is served via Edge Services. The pipeline's endpoint can be customized with a user-defined [subdomain](#subdomain) and associated [certificate](#certificate) so that Edge Services can serve content over HTTPS. 
+
+You can create one or more Edge Services pipelines for each of your Object Storage buckets or Load Balancer origins. 
+
+## Protocol
+
+The protocol (HTTP or HTTPS) that the Edge Services pipeline should use when sending requests to an origin Load Balancer. HTTPS is recommended, but you should choose the protocol that corresponds with your Load Balancer setup.

network/edge-services/how-to/configure-cache.mdx

@@ -0,0 +1,103 @@
+---
+meta:
+  title: How to configure an Edge Services cache
+  description: Learn how to configure a cache for Edge Services. Enhance performance and finely control your cached objects via purging (cache invalidation).
+content:
+  h1: How to configure an Edge Services cache
+  paragraph: Learn how to configure a cache for Edge Services. Enhance performance and finely control your cached objects via purging (cache invalidation).
+dates:
+  validation: 2024-07-24
+  posted: 2024-07-24
+tags: object-storage edge-services cdn network cache purge
+categories:
+  - network
+---
+
+The cache feature allows you to cache your origin's content with Edge Services. This means that content can be served directly to users from Edge Services' servers, instead of from your Object Storage bucket or Load Balancer origin, enhancing performance.
+
+You can disable and enable caching at will, as well as control the lifetime of an object in the cache. You can also purge your entire cache, or specific objects within it. A log is displayed to help you track your purge events.
+
+## How to enable the cache
+
+1. In the Scaleway console, navigate to the Edge Services dashboard for the Object Storage bucket or Load Balancer origin for which you want to enable caching:
+
+    TODO INSERT SCREENSHOT
+
+2. In the **Cache** panel, use the <Icon name="toggle" /> icon to enable the cache.
+
+    The **Lifetime** configuration box displays. This enables you to define, in seconds, how long an object can be stored in the cache before it must be retrieved freshly from the origin (Object Storage bucket or Load Balancer).
+
+    <Lightbox src="scaleway-edge-services-cache.webp" /> TODO CHECK
+
+    <Message type="tip">
+    As an example, a value of 0 means that objects will not be cached, unless they have a separately-defined caching directive. Note that in any case, if an object has a caching directive, the caching directive always takes precedence over any lifetime setting defined here in Edge Services.
+    </Message>
+
+3. Leave the default value of 1 hour in place, or enter another value.
+
+The cache is now enabled.
+
+## How to purge all objects from your cache
+
+Purging objects clears all objects from your cache. Afterward, Edge Services will retrieve fresh copies from the origin (Object Storage bucket or Load Balancer) before it stores them again in the cache.
+
+1. In the Scaleway console, navigate to the Edge Services dashboard for the Object Storage bucket or Load Balancer origin whose cache you want to purge:
+
+    TODO INSERT SCREENSHOT
+
+2. In the **Purge cache** panel, click **Purge all**.
+
+    <Lightbox src="scaleway-edge-services-purge-cache.webp" /> TODO CHECK
+
+    A screen displays, warning you that your cache will be emptied, and Edge Services will have to retrieve objects from your origin before re-caching them.
+
+3. Click **Purge cache** to confirm.
+
+## How to purge specific objects from your cache
+
+This allows you to specify the precise objects that you want to clear from the cache. Afterward, Edge Services will retrieve fresh copies from the origin (Object Storage bucket or Load Balancer) before it stores them again in the cache.
+
+1. In the Scaleway console, navigate to the Edge Services dashboard for the Object Storage bucket or Load Balancer origin whose cache you want to purge:
+
+    TODO INSERT SCREENSHOT
+
+2. In the **Purge cache** panel, click **Purge by object**.
+
+    <Lightbox src="scaleway-edge-services-purge-cache.webp" /> TODO CHECK
+
+    A screen displays prompting you to enter the path of each object you want to purge from the cache.
+
+    <Lightbox src="scaleway-edge-services-purge-object.webp" /> TODO CHECK
+
+3. Enter the path of each object you want to purge. You can purge a maximum of 5 objects at a time.
+
+      <Message type="tip">
+
+      The path for each object should be defined from the root and must start with a slash, e.g. `/videos/my-video.mp4`.
+
+      You **cannot** purge entire directories by simply specifying the path to the directory, e.g. `/videos`. Purging objects must be done strictly object-by-object, so `/videos/my-video1.mp4`, `/videos/my-video2.mp4`, `/videos/my-video3.mp4` etc. Watch this space for updates to this feature in the future.
+
+      For example, if we imagine an Object Storage bucket containing one file at the root level called `object1.jpg`, and a subfolder at root level called `videos` containing an item called `my-video.mp4`, we would enter the object paths as follows:
+
+      - `/object1.jpg`
+      - `/videos/my-video.mp4`
+
+      </Message>
+
+4. Click **Purge objects from cache**.
+
+    The specified objects are purged from your cache and you are returned to the Edge Services dashboard.
+
+## How to disable your cache
+
+1. In the Scaleway console, navigate to the Edge Services dashboard for the Object Storage bucket or Load Balancer origin whose cache you want to disable:
+
+    TODO INSERT SCREENSHOT
+
+2. In the **Cache** panel, use the <Icon name="toggle" /> icon to disable the cache.
+
+    A pop-up displays, asking you to confirm the action.
+
+3. Click **Disable cache**.
+
+    Your cache is purged and disabled. Edge Services will now serve content by fetching it from your origin (Object Storage bucket or Load Balancer) directly. If you reenable your cache at a later point, you will begin with an empty cache.

network/edge-services/how-to/configure-custom-domain.mdx

@@ -0,0 +1,123 @@
+---
+meta:
+  title: How to configure a custom domain for Edge Services
+  description: Learn how to configure an Edge Services endpoint with a custom subdomain. Access your Object Storage bucket or Load Balancer origin via your own domain name instead of the standardized endpoint.
+content:
+  h1: How to configure a custom domain for Edge Services
+  paragraph: Learn how to configure an Edge Services endpoint with a custom subdomain. Access your Object Storage bucket or Load Balancer origin via your own domain name instead of the standardized endpoint.
+dates:
+  validation: 2024-07-24
+  posted: 2024-07-24
+tags: object-storage edge-services cdn network domain ssl tls https
+categories:
+  - network
+---
+
+If you already own a domain, you can customize an Edge Services pipeline endpoint with a subdomain of your choice. This means you can access your Object Storage bucket or Load Balancer origin through Edge Services via your own subdomain rather than the standardized Edge Services endpoint.
+
+For example, if you own `beautiful-domain.com`, you can customize the endpoint to be `whatever-i-want.beautiful-domain.com`. You must also add an SSL/TLS certificate so that Edge Services can securely serve your content via HTTPS.
+
+You cannot customize your endpoint with a primary domain directly (e.g. `beautiful-domain.com`), only with a subdomain of it.
+
+## How to configure a custom domain
+
+The procedure for adding a customized endpoint is as follows:
+
+1. In the Scaleway console, navigate to the Edge Services dashboard for the Object Storage bucket or Load Balancer origin whose domain you want to customize:
+
+        TODO INSERT SCREENSHOT
+
+2. In the **Endpoint** panel, click **Configure domain**. The following screen displays:
+
+    TODO SCREENSHOT
+
+3. Set a subdomain from which your Object Storage bucket or Load Balancer origin will be accessible via its Edge Services pipeline. You must already own the primary domain. For example, if you own `beautiful-domain.com`, choose any subdomain you like and enter `my-chosen-subdomain.beautiful-domain.com` into the box.
+
+    <Message type="important">
+    It is **not** possible to use only a root domain (aka primary domain or apex domain), you must use a subdomain. This is because CNAME records, essential to point your domain to your Edge Services endpoint, cannot by definition be created for root domains, only for subdomains.
+    ✅ blog.example.com
+    ❌ example.com
+    </Message>
+
+4. This step depends on whether the domain used in the previous step is managed with [Scaleway Domains and DNS](/network/domains-and-dns/), or an external domain provider. Choose the appropriate tab below.
+
+    <Tabs id="edge-cname">
+
+        <TabsTab label="Domains and DNS">
+        The domain you are using for Edge Services is considered to be managed with Scaleway Domains and DNS if:
+        - You [registered the domain](/network/domains-and-dns/how-to/register-internal-domain/) with Domains and DNS, or
+        - You [transferred an externally-registered domain](/network/domains-and-dns/how-to/transfer-external-domain/) to Domains and DNS
+
+        If either of the above is true, Scaleway will auto-detect that the domain is managed by Domains and DNS, and a message will display confirming that you do not need to create a CNAME record. We will auto-generate the appropriate CNAME record in your domain's [DNS records](/network/domains-and-dns/how-to/manage-dns-records/), to point your subdomain to the Edge Services endpoint. This record is generated when you click `Customize domain` in step 6.
+
+        You should not attempt to modify or delete the CNAME record, which will be visible among your [DNS records](/network/domains-and-dns/how-to/manage-dns-records/) in the Scaleway console.
+        </TabsTab>
+
+        <TabsTab label="External provider">
+        Scaleway cannot itself create the appropriate CNAME record to point your subdomain to Edge Services if your domain is managed by an external provider. You must create the CNAME record yourself.
+
+        Log in to your domain provider, and locate the DNS settings for your domain. Create a new CNAME record pointing your subdomain to the Edge Services pipeline endpoint displayed in the Scaleway console. For help setting up CNAME records and troubleshooting any problems, [check out our dedicated documentation](/network/edge-services/reference-content/cname-record/).
+
+        Back in the Scaleway console, click the `Verify CNAME` button to check whether your CNAME record has been correctly configured. Edge Services will carry out a check, and if it is successful the following message displays:
+
+        <Lightbox src="scaleway-cname-success.webp" alt="Verification passed: Your DNS record has been correctly configured" /> TODO CHECK
+
+        If the check fails, an error message will display. See the documentation linked above for help troubleshooting such errors.
+        </TabsTab>
+    </Tabs>
+
+5. Provide an SSL/TLS certificate for your subdomain so that Edge Services can serve traffic for it over HTTPS. You have three options for this:
+    - Generate a free Let's Encrypt certificate, managed by Scaleway, including automatic renewals.
+    - Select an existing certificate that you have stored in [Scaleway Secret Manager](/identity-and-access-management/secret-manager/quickstart/).
+    - Manually import a certificate into Scaleway Secret Manager:
+      - Enter a name for your certificate (alphanumeric characters only)
+      - Optionally, add tags by typing each tag and then pressing enter
+      - Copy and paste the full PEM-formatted certificate chain into the box.
+      Your certificate will be automatically stored in Secret Manager and [billed accordingly](https://www.scaleway.com/en/pricing/security-and-account/).
+
+    <Message type="tip">
+    For help with SSL/TLS certificates for Edge Services, and/or dealing with any errors you encounter importing a certificate into Secret Manager, see our [dedicated documentation](/network/edge-services/reference-content/ssl-tls-certificate/).
+    </Message>
+
+6. Click **Customize domain** to finish.
+
+Your customized domain is set up, and you are returned to the Edge Services dashboard. The customized domain displays in the Endpoint panel. When you access your Object Storage or Load Balancer origin through this domain, its content will be served via Edge Services.
+
+<Message type="note">
+If you chose to generate a managed Let's Encrypt certificate, allow a few minutes for the certificate to finish creating. When the process is complete and the certificate is ready, you will see a green status light for **SSL/TLS certificate** on your endpoint dashboard.
+
+<Lightbox src="scaleway-edge-services-certificate-complete.webp" alt="" /> TODO CHECK
+
+</Message>
+
+## How to edit your customized domain or its certificate
+
+After customizing your domain, you can edit it (or its certificate) at any time as follows:
+
+1. In the Scaleway console, navigate to the Edge Services dashboard for the Object Storage bucket or Load Balancer origin whose domain you want to customize:
+
+        TODO INSERT SCREENSHOT
+
+2. In the **Endpoint** panel, click **Edit**. The **Edit Domain** screen displays.
+
+3. Edit the subdomain as desired - do not forget to also set up a new CNAME record, if necessary.
+
+4. Edit your certificate options as required - choose to generate a managed Let's Encrypt certificate, managed by Scaleway including automatic renewals, or select a different certificate from Secret Manager, or manually import a new certificate for your custom domain.
+
+5. Click **Edit domain** to finish.
+
+## How to reset your customized domain
+
+Even though the original Edge Services endpoint (e.g. `https://pipeline-id-or-bucket-name.svc.edge.scw.cloud`) will continue to work after you add a customized domain, you can choose to remove your customized domain completely and go back to the original Edge Services endpoint only. This is done via the reset function:
+
+1. In the Scaleway console, navigate to the Edge Services dashboard for the Object Storage bucket or Load Balancer origin whose domain you want to reset:
+
+        TODO INSERT SCREENSHOT
+
+2. In the **Endpoint** panel, click **Reset**.
+
+    A screen displays, warning you that this will reset the pipeline's domain back to the default Edge Services endpoint. Edge Services will consider your customized subdomain as unknown. You should also remember to:
+        - Delete your CNAME record from your domain provider, unless your domain is managed with Scaleway Domains and DNS, in which case we take care of deletion for you.
+        - Delete any SSL/TLS certificates you imported into Secret Manager (if no longer required elsewhere, so that you are no longer billed for it). If you generated a managed Let's Encrypt certificate however, Scaleway takes care of the deletion for you.
+
+3. Click **Reset domain** to finish.