Edge Services API

Introduction

Edge Services allows you to easily, securely and reliably expose your HTTP service to the internet via a single entry point. With Edge Services, you can enhance performance by enabling caching on Scaleway Object Storage buckets (S3) or Scaleway Load Balancers, security by enabling WAF (Web Application Firewall) as well as customize your endpoints with your own domain and SSL/TLS certificate.

Quickstart

This quickstart shows you how to set up Edge Services on a Scaleway Load Balancer with Caching and WAF enabled.

1. Configure your environment variables.

   Note

   This is an optional step that seeks to simplify your usage of the Edge Services API.

   export SCW_SECRET_KEY="<API secret key>"
   export SCW_PROJECT_ID="<Scaleway Project ID>"
   

2. Create a Pipeline: run the following command to create an empty pipeline. This pipeline is the main Edge Services object and represents how an HTTP request to your Object Storage bucket or Load Balancer via Edge Services will be processed.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/edge-services/v1beta1/pipelines" \
     -d '{
       "project_id":"'$SCW_PROJECT_ID'",
       "name":"mypipeline",
       "description":"my-pipeline"
     }'
   

3. Create a Backend Stage: run the following command to create a backend stage, which defines the origin service which Edge Services will point to. In this example, we point to a Scaleway Load Balancer. We need to define the Load Balancer id, the frontend_id and the zone where the LB is located, as well as the domain (Host Header) to be used by Edge Services when fetching content from it. Ensure that you replace <PIPELINE_ID> in the URL with the ID of the pipeline.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>/backend-stages" \
     -d '{
       "scaleway_lb": {
         "lbs": [
           {
             "id": "<LOAD_BALANCER_ID>",
             "zone": "fr-par-1",
             "frontend_id": "<LB_FRONTEND_ID>",
             "is_ssl": true,
             "domain_name": "mydomain.com"
           }
         ]
       }
     }'
   

4. Create a WAF Stage: run the following command to create a WAF (Web Application Firewall) stage, in order to protect your origin (defined by the backend stage) from malicious requests. In this example, we configure the WAF in a log_only mode, resulting in having malicious requests being logged into Cockpit but not rejected. This behavior is useful for pre-production environments. The paranoia_level settings allows to define the WAF sensitivity. With a high level, requests are more likely to be classed as malicious, and false positives are expected. With a lower level, requests are more likely to be classed as benign. Ensure that you replace <BACKEND_STAGE_ID> with the ID of the previously created backend stage and <PIPELINE_ID> in the URL with the ID of the pipeline.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>/waf-stages" \
     -d '{
       "mode":"log_only",
       "paranoia_level":1,
       "backend_stage_id":"<BACKEND_STAGE_ID>"
     }'
   

5. Create a Cache Stage: run the following command to create a cache stage, which defines the caching configuration for Edge Services to distribute the content from the defined origin (the previously-defined backend stage). The example below sets the a custom TTL of 30 minutes for the cache. Ensure that you replace <WAF_STAGE_ID> with the ID of the previously created WAF stage and <PIPELINE_ID> in the URL with the ID of the pipeline. If you don't need WAF to protect your origin, then directly specify the backend_stage_id.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>/cache-stages" \
     -d '{
       "fallback_ttl":"1800s",
       "waf_stage_id":"<WAF_STAGE_ID>"
     }'
   

6. Create a TLS Stage: run the following command to create a TLS stage, which defines the SSL/TLS certificate for Edge Services on the previously-defined backend stage (origin). In the example below, an auto-created Saleway-managed Let's Encrypt certificate is configured. Ensure that you replace <CACHE_STAGE_ID> with the ID of the previously created cache stage and <PIPELINE_ID> in the URL with the ID of the pipeline. If you don't need caching, then directly specify the backend_stage_id or the waf_stage_id.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>/tls-stages" \
     -d '{
       "managed_certificate":true,
       "cache_stage_id":"<CACHE_STAGE_ID>"
     }'
   

7. Create a DNS Stage: run the following command to create a DNS stage, which defines a custom domain as an endpoint for Edge Services on your backend stage (origin). You must already own the domain. In the example below we use myendpoint.example.com. Ensure that you replace <TLS_STAGE_ID> with the ID of the previously created TLS stage and <PIPELINE_ID> in the URL with the ID of the pipeline.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>/dns-stages" \
     -d '{
       "fqdns":["myendpoint.example.com"],
       "tls_stage_id":"<TLS_STAGE_ID>"
     }'
   

8. Define the Head of the Pipeline: run the following command to set the previously created DNS stage as first stage or Head of the Pipeline, to trigger the Pipeline configuration. Ensure that you replace <PIPELINE_ID> in the URL with the ID of the pipeline.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>/set-head-stage" \
     -d '{
       "add_new_head_stage":{
         "new_stage_id":"<DNS_STAGE_ID>"
       }
     }'
   

9. Access your endpoint: Once you have created a CNAME record pointing towards the Edge Services default endpoint, yan can run the following command to test your pipeline. Ensure that you customize the URL according to the domain you set in step 7, and that you replace path/to/my/content with an appropriate URL path that is actually reachable through your Load Balancer. You can also test the URL through your web browser. Edge Services will serve the requested object. Once your content is cached, you can inspect the HTTP header X-Cache and see that the response is hit-fresh.

   curl -i https://myendpoint.example.com/path/to/my/content
   

10. Delete your pipeline: run the following command to delete a pipeline. Ensure that you replace <PIPELINE_ID> in the URL with the ID of the pipeline you want to delete. Note that it will also delete all of the associated stages.

    curl -X DELETE \
      -H "X-Auth-Token: $SCW_SECRET_KEY" \
      "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>"
    

Technical information

Availability

Scaleway Edge Services is currently available globally. Find out about product availability in our dedicated documentation.

Edge Services is currently available for Scaleway Object Storage and Load Balancer backends only.

Pipeline Stages

An Edge Services pipeline contains a set of interlinked stages.

The following links are possible :

• Pipeline > DNS stage > TLS stage > Cache stage > Route stage > WAF stage > Backend stage
• Pipeline > DNS stage > TLS stage > Cache stage > WAF stage > Backend stage
• Pipeline > DNS stage > TLS stage > Cache stage > Backend stage
• Pipeline > DNS stage > TLS stage > WAF stage > Backend stage
• Pipeline > DNS stage > TLS stage > Backend stage

If you wish to set up Edge Services without customizing the domain (that is, using the default endpoint), you can create empty TLS and DNS stages.

• Create the TLS stage with only the pipeline_id and backend_stage_id (or cache_stage_id if caching feature is needed) parameters.
• Create the DNS stage with only the pipeline_id and tls_stage_id parameters.

If you use the WAF stage and need to exclude some requests from being inspected by the WAF (that is, bypass the WAF), define a route stage pointing towards the WAF stage, and setup route rules to override the default route stage behavior: requests matching the defined route rules will be directly sent to the backend stage and won't be inspected by the WAF. The route stage must be referenced by either a cache stage or TLS stage to be part of the pipeline.

Technical limitations

• A backend stage must point either to a Scaleway Object Storage bucket (scalewayS3) or to a Scaleway Load Balancer (scalewayLb)
• Only one pipeline is allowed per Object Storage bucket
• The TLS stage currently only supports one SSL/TLS certificate
• The DNS stage currently only supports one FQDN (Fully Qualified Domain Name)

Going further

For more help using Scaleway Edge Services, check out the following resources:

• Our main documentation
• The #edge-services channel on our Slack Community
• Our support ticketing system.