Edge Services API

Download schema

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), Scaleway Load Balancers or Scaleway Serverless Containers and Functions. You can also increase 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.

Configure your environment variables.

Note
This is an optional step that seeks to simplify your usage of the Edge Services API.
```
Code
export SCW_SECRET_KEY="<API secret key>"
export SCW_PROJECT_ID="<Scaleway Project ID>"
```

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.

Code
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"
  }'

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.

Code
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"
        }
      ]
    }
  }'

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.
```
Code
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>"
  }'
```
Create a Route Stage: run the following command to create a Route stage, in order to define where the requests will be forwarded to by default (waf_stage_id or backend_stage_id). 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.
```
Code
curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>/route-stages" \
  -d '{
    "waf_stage_id":"<WAF_STAGE_ID>"
  }'
```
Configure the Route rules: run the following command to configure routing rules. For each rule, a condition (based on host, method and path) and a target stage (waf_stage_id or backend_stage_id) are defined. Requests matching the condition will be directly forwarded to the specified stage. Requests that do not match will be checked by the next rule's condition. If no rules are matched, the request is forwarded to the default stage defined in the route stage. Route rules can be used to conditionally bypass the WAF stage. Ensure that you replace <ROUTE_STAGE_ID> with the ID of the previously created Route stage and the<BACKEND_STAGE_ID> with the ID of the previously created Backend stage
```
Code
curl -X PUT \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/edge-services/v1beta1/route-stages/<ROUTE_STAGE_ID>/route-rules" \
  -d '{
    "route_rules":[
      {"rule_http_match":{"method_filters":["get","post"],"path_filter":{"path_filter_type":"regex","value":"my_url_path"}},"backend_stage_id":"<BACKEND_STAGE_ID>"},
      {"rule_http_match":{"host_filter":{"host_filter_type":"regex","value":"www.mydomain.com"}},"backend_stage_id":"<BACKEND_STAGE_ID>"}
    ]
  }'
```
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 <ROUTE_STAGE_ID> with the ID of the previously created Route stage and <PIPELINE_ID> in the URL with the ID of the pipeline.
```
Code
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":"<ROUTE_STAGE_ID>"
  }'
```
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 route_stage_id or the backend_stage_id or the waf_stage_id.
```
Code
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>"
  }'
```
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.
```
Code
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>"
  }'
```

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.

Code
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>"
    }
  }'

Access your endpoint: Once you have created a CNAME recordOpen in new context 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.
```
Code
curl -i https://myendpoint.example.com/path/to/my/content
```
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.
```
Code
curl -X DELETE \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/edge-services/v1beta1/pipelines/<PIPELINE_ID>"
```

Requirement

You have a Scaleway accountOpen in new context
You have created an API keyOpen in new context and that the API key has sufficient IAM permissionsOpen in new context to perform the actions described on this page
You have installed curlOpen in new context
You have created a Scaleway Load BalancerOpen in new context

Technical information

Availability

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

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 (non-exhaustive list):

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 > Route stage > Backend stage
Pipeline > DNS stage > TLS stage > WAF stage > Backend stage
Pipeline > DNS stage > TLS stage > Backend stage
Pipeline > DNS 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, a Scaleway Load Balancer or a Scaleway Serverless container/function
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)
Wildcard managed certificates (via Let's Encrypt) are not supported

Going further

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

Our main documentationOpen in new context
The #edge-services channel on our Slack CommunityOpen in new context
Our support ticketing systemOpen in new context.