Serverless Functions API

Introduction

Deploying applications to the cloud becomes simpler with Serverless Functions. Instead of provisioning and maintaining servers, you just need to install a "function" of your business logic on the Scaleway cloud platform. The platform executes this function on demand, managing resource allocation for you. If the system needs to accommodate a hundred simultaneous requests, it creates a hundred (or more) copies of your service. Conversely, if demand drops to two concurrent requests, it destroys the unneeded ones. You only pay for the resources your functions use when they need them.

The benefits of Scaleway Serverless Functions include:

• Saving money while code is not running, as functions are only executed when an event is triggered
• Auto-scalability:
  • Scaling up and down automatically based on user configuration (e.g., min: 0, max: 100 replicas of my function).
  • Scaling to zero when the function is not executed, which saves money for the user and computing resources for the cloud provider.
• Endpoint-only scaling.

Deploying functions

This page explains how to use the Scaleway Serverless Functions API, including a quickstart and the full API documentation. However, we provide several methods to deploy functions.

Concepts

Refer to our dedicated concepts page to find definitions of all terminology related to Scaleway Serverless Functions.

Quickstart

1. Configure your environment variables.

   export SCW_SECRET_KEY="<your secret key>"
   export SCW_DEFAULT_REGION="<choose your location (fr-par/nl-ams/pl-waw)>"
   export SCW_DEFAULT_PROJECT_ID="<your project ID>"
   

   Note

   A namespace is a project that allows you to group your functions. Functions in the same namespace can share environment variables and access tokens, defined at the namespace level.

2. Set the name for your namespace and set your Project ID.

   curl -X POST \
     "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/namespaces" \
     -H "accept: application/json" \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
         name: your-namespace-name, \ 
         project_id: "$SCW_DEFAULT_PROJECT_ID", \
         environment_variables: \
           {
             YOUR_VARIABLE: content
           } \
         }'
   

3. Copy the id field of the response to use in the next steps. For the sake of simplicity, we will save the ID to a variable, which we will use in the following examples.

   export SCW_NAMESPACE_ID="<your namespace id>"
   

4. Edit the POST request payload that we will use in the next step to create a function. Modify the values in the example according to your needs, using the information in the table to help.

   {
     "name": "string",
     "namespace_id": "string",
     "environment_variables": {
       "<key>": "string"
     },
     "min_scale": "integer",
     "max_scale": "integer",
     "runtime": "unknown_runtime",
     "memory_limit": "integer",
     "timeout": "2.5s",
     "handler": "string",
     "privacy": "unknown_privacy",
     "description": "string",
     "secret_environment_variables": [
       {
         "key": "string",
         "value": "string"
       }
     ],
     "http_option": "enabled"
   }
   

   Parameter	Description
   name	The name of your function
   namespace_id	ID of the namespace in which you want to create your function
   runtime	Your function's runtime, check the supported runtimes above
   environment_variables	NULLABLE Environment variables of the function.
   memory_limit	NULLABLE Memory (in MB) allocated to your function, see the table of memory/CPU allocation above (increasing the memory limit will increase the cost of your function executions as we allocate more resources to your functions).
   min_scale	NULLABLE Minimum replicas for your function, defaults to 0, Note that a function is billed when it gets executed, and using a min_scale greater than 0 will cause your function to run all the time.
   max_scale	NULLABLE Maximum replicas for your function (defaults to 20), our system will scale your functions automatically based on incoming workload, but will never scale the number of replicas above the configured max_scale.
   timeout	NULLABLE Holds the max duration (in seconds) the function is allowed for responding to a request
   description	NULLABLE Description of the function.
   handler	NULLABLE More details with examples in each language/runtime section below

Note that the meaning of the value set in handler will change depending on the runtime parameter:

• Node, PHP and Python runtimes: handler is the path to the function file, followed by the name of the function to call. For example, src/handler.handle specifies a function file at src/handler.js, src/handler.php and src/handler.py respectively, with a function called handle.

• Go and Rust runtimes: handler is the path to the package containing the handler. For example, my_handler specifies that the function file is located in a my_handler directory. The functions must then be part of a main package, exposing a main function.

  Note

  All parameters, except the ones marked with nullable are required.

5. Run the following command to create your function. Make sure you include the payload you edited in the previous step.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY"\
     "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/functions"\
     -d '{
           name: function-name, \
           namespace_id: "$SCW_NAMESPACE_ID", \
           memory_limit: 128, \
           min_scale: 0, \
           max_scale: 20, \
           runtime: node16", \
           handler: handler.myHandler \
         }'
   export SCW_FUNCTION_ID = "<your-function-id>"
   

6. Upload your code from the console or directly via the API. Refer to the dedicated documentation for more information.

7. Run the following command to deploy your function.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/functions/$SCW_FUNCTION_ID/deploy" \
     -d "{}"
   

   Note

   The process may take some minutes, as we have to build your source code into an executable function (wrapped by our runtimes), and deploy it to the Scaleway cloud platform.

8. Retrieve your function's HTTP(s) endpoint with the following command once your function has been properly deployed.

   curl -X GET \
     -H "X-Auth-Token: $SCW_SECRET_KEY" "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/functions/$SCW_FUNCTION_ID"
   export FUNCTION_ENDPOINT="<endpoint>"
   

9. Call your function via its endpoint.

   curl -X GET "$FUNCTION_ENDPOINT"
   

10. (optional) Connect to your Cockpit, and access the Serverless Functions Logs dashboard to see your logs.

11. (optional) Destroy the namespace (along with all functions and cron jobs) by using the following call:

    curl -s \
      -H "X-Auth-Token: $SCW_SECRET_KEY" -X DELETE "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/namespaces/$SCW_NAMESPACE_ID"
    

Technical information

• Functions are fully isolated environments
• Scaling to zero (save money and computing resources while code is not executed)
• High Availability and Scalability (Automated and configurable, each function may scale automatically according to incoming workloads)
• Different programming languages supported
• Multiple event sources:
  • HTTP (request on our Gateway will execute the function)
  • CRON (time-based job, runs according to configurable cron schedule)
• Integrated with the Scaleway Container Registry product
  • Each of your functions namespace has an associated registry namespace
  • All your functions are available as docker image in this registry namespace
  • Each version of your function matches a tag of this image

Token management

To get all tokens associated with a function:

export SCW_SECRET_KEY=<your_secret_key>
export SCW_DEFAULT_REGION="<Scaleway default region>"
export SCW_FUNCTION_ID=<funcion_id_you_want_to_inspect>
curl -X GET \
  "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/tokens?function_id=$SCW_FUNCTION_ID" \
  -H "accept: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json"

To generate a token for a function:

export SCW_SECRET_KEY="<API secret key>"
export SCW_DEFAULT_REGION="<Scaleway default region>"
export SCW_FUNCTION_ID=<funcion_id_you_want_to_add_token>
export EXPIRE_AT=$(date -d "+90 days" +%Y-%m-%dT%H:%M:%S.000Z)
curl -X POST \
  "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/tokens" \
  -H "accept: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      descrption:desc, \
      expire_at:"$EXPIRE_AT", \
      function_id:"$SCW_FUNCTION_ID"
      }'

To revoke a token you need to delete it:

export SCW_ACCESS_KEY="<API access key>"
export SCW_SECRET_KEY="<API secret key>"
export TOKEN_ID=<token_you_want_to_delete>
curl -X DELETE \
  "https://api.scaleway.com/functions/v1beta1/regions/$SCW_DEFAULT_REGION/tokens/$SCW_ACCESS_KEY" \
  -H "accept: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json"

Authentication

By default, new functions are public meaning that no credentials are required to invoke functions.

A function can be private or public. This can be configured through the privacy parameter.

Calling a private function without authentication will return HTTP code 403.

Authentication for private functions

A private function will:

• Reject a call without an X-Auth-Token header, returning HTTP status Code 403
• Validate the token before invoking your code if it is provided via the X-Auth-Token header

For example, to execute a private function by providing a token using curl, you may run the following command:

curl \
  -H "X-Auth-Token: <generated-token>" <your-function-host>

Logs

Functions logs are sent to the project's Cockpit.

The Serverless Functions Logs dashboard allows you to see functions logs. You can perform complex queries using the Explore section of Grafana, and with LogQL queries:

{resource_type="serverless_function"}

Additionally, you can use the Grafana Loki endpoint (https://logs.cockpit.fr-par.scw.cloud) to query programmatically the functions logs using a token.

Pagination

Most listing requests receive a paginated response. Requests against paginated endpoints accept two query arguments:

• page, a positive integer to choose which page to return.
• page_size, an positive integer lower or equal to 100 to select the number of items to return per page. The default value is 20.

Paginated endpoints usually also accept filters to search and sort results. These filters are documented along each endpoint documentation.

Regions

Serverless Functions is available in the Paris, Amsterdam and Warsaw regions, which are represented by the following path parameters:

• fr-par
• nl-ams
• pl-waw

Technical limitations

Supported runtimes and function lifecyle

You can find all information about runtimes and functions in the Functions' lifecycle reference page.

Going further

For more help using Scaleway Serverless functions, check out the following resources:

• Our main documentation
• The #serverless-functions channel on our Slack Community
• Our support ticketing system

Local testing

Scaleway provides a number of open-source tools for offline testing. The details can be found in the local testing docs.

Namespaces

Functions

Crons

Domains

Tokens

Triggers