Functions APIv1beta1

Scaleway Functions is a Function As A Service product that gives users the ability to deploy atomic serverless workloads and only pay for resources used.

It provides many advantages, such as:

• Functions are only executed when an event is triggered, which allows users to save money while code is not running
• Auto-Scalability:
  • Automated Scaling up and down based on user configuration (e.g. min: 0, max: 100 replicas of my function).
  • Automated Scaling to zero when function is not executed, which saves some money for the user and save Computing resources for the cloud provider.
• Scale only the endpoint

• 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

This page focuses on working with the Scaleway API, for detailed information about functions you can dive into the Scaleway Documentation for Functions.

You can deploy Functions using the API but also we have a list of [common deployment methods](TODO ADD LINK)

You can find all information about runtimes and functions in the reference content.

Whether you decide to use Serverless Framework or directly our API, you'll need your Scaleway project ID and a Scaleway project API Key.

• Install curl
• Install jq will make it easier to manage JSON output from our APIs

To call Scaleway API, you need an X-Auth-Token. If you don't have one yet, you can create it on the credentials page of your Scaleway account (must be done via web interface).

In order to retrieve your Project ID and your API Key, you must go to your console's credentials page:

• Login/Register to Scaleway console
• Go to your credentials management page
• Retrieve your project ID and generate a token (see following picture):
• Retrieve your token's secret key:

Then, export them as variables to use them with curl:

The following sections explain how to use our API, with a tutorial and the auto-generated API documentation. However, we developed a Serverless Framework plugin enabling users to deploy their serverless workloads much more easily with a single serverless deploy command. No magic there, it's just a nice tool calling our API.

If what you are looking for is an easy way to deploy your code, you may prefer Serverless Framework.

Below, you will find a step-by-step guide on how to create a namespace, configure and deploy functions, and trigger your functions via HTTP and CRON.

Customize the name and set your project ID:

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

To destroy a namespace (along with all functions and crons) use the following call:

When creating a function, you may customize multiple fields:

• 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
• memory_limit: 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: 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: 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: Holds the max duration (in seconds) the function is allowed for responding to a request
• handler (More details with examples in each language/runtime section below):
  • Python: Path to function handler's file and the function to use as the handler: src/handler.my_handler => file handler.py defining a my_handler function, inside src folder.
  • Node: Path to function handler's file, suffixed the name of the function to use as the handler: src/handler.myHandler => file handler.js exporting a myHandler function, inside src directory.
  • Go: Path to the package containing the handler: my_handler: the code containing the handler is located inside a my_handler directory (must be package main, and exposing a main function).

These steps only apply if you use a Scaleway runtime. In this section, you will upload your code to a S3 bucket, which we'll package and build into a container image.

This container image will then be available in a registry namespace associated to your functions namespace.

You may then create a zip archive with your code:

Please Note that if you wish to use external dependencies, you will have to package them inside the zip archive as well:

You need to get the size of your archive in bytes, in order to ask for a presigned URL to upload your source code:

As you can see, the url is not properly formatted (\u0026...), in order to use it properly to upload your code, you must copy the full URL with quotes (otherwise your terminal might add unwanted \ in the url string):

Note: that you will get an error in the following step if you do not Copy the url with wrapping quotes and save inside a variable using echo -n to replace \u0026 expressions

If you use postman, you can usually export the presigned url as it is, as long as you copy/paste the quotes too.

Then, run the following command to deploy your function:

The process may take a little bit of time, as we have to build your source code into an executable function (wrapped by our runtimes), and deploy it to our cloud platform.

Once your function has been properly deployed, you may retrieve your function's HTTP(s) endpoint with the following command:

And then, call your function via its endpoint:

To retrieve the functions output logs:

As described above, CRON triggers are a way to execute your applications (Functions and Containers) periodically, based on a given Schedule.

It means that we can execute our function every day at 1PM for example, with a given set of data.

In order to add a CRON Trigger to your function, you need to retrieve your function ID (Done previously if you followed the guide), and create a new CRON associated to your function:

The above request will create and deploy a Kubernetes CRON Job in charge of executing your function every day at 13:00, with the data {"key": "value"}, retrieved from the event.body object in your handler.

Runtimes are environment that you may use to develop their cloud functions.

Scaleway Runtimes are Lambda Compatible -> For API Gateway Proxy event types (as we only support HTTP and CRON, but cron basically sends HTTP requests to deployed functions).

In a common use case with Serverless Framework for example, in which a user has multiple functions in the same repository and would like to upload them all at the same time with a single command, we need a way to know, which file (Python/JavaScript) or package (Go) to use to execute our functions.

Please Note that in some runtimes, this decision is made at runtime (Python and JavaScript, as they are interpreted languages, so our runtime will only import the handler), while in some others (Go), it is done at compile/build time (when user deploys a function) as we need to build user's package.

For Node code samples you can have a look at the code samples page

The Handler name is basically a path to the handler file.

For example, let's say I have two handlers hello.js and world.js inside src/handlers folder:

Then, you need to provide a custom handler name for each of these handlers, so each of your functions will know which handler file to run: hello -> src/handlers/hello.sayHello and world -> src/handlers/world.toTheWorld.

By default, the handler path is handler.handle (module.exports.handle in handler.js).

If you ever need to push external dependencies for your node.js functions, you will have to package your node_modules directory into your deployment archive.

Tools like webpack or NCC allow you to package your code into a single file. You are then able to upload your compiled handler file which reduces the size of your bundle.

Example:

Then, set up your function handler to be: build/handler.js if you package the whole build directory. Don't forget to point the function handler property to the path of your built handler in your archive (if build/handler.myHandler then handler must be build/handler.js)

Node has two module systems: CommonJS modules and ECMAScript (ES) modules. By default, Node treats your code files as CommonJS modules, however ES modules have also been available since the release of node16 runtime on Scaleway Serverless Functions. ES modules give you a more modern way to re-use your code.

According to the official documentation, to use ES modules you can specify the module type in package.json, as in the following example:

This then enables you to write your code for ES modules:

The use of ES modules is encouraged, since they are more efficient and make setup and debugging much easier.

Note that using "type": "module" or "type": "commonjs" in your package.json will enable/disable some features in Node runtime. For a comprehensive list of differences, please refer to the official documentation, the following is a summary only:

• commonjs is used as default value
• commonjs allows you to use require/module.exports (synchronous code loading, it basically copies all file contents)
• module allows you to use import/export ES6 instructions (asynchronous loading, more optimized as it imports only thie pieces of code you need)

For Go code samples you can have a look at the code samples page.

The handler name is the name of your handler function (example: Handle for the function defined above).

If your code is in a subfolder, like this:

The handler name must be composed of the folder name and the handler function name, separated by /. For the example above, subfolder/Handle is the right handler name.

If you need external dependencies for your code, you may provide these dependencies in your go.mod.

Function runtimes automatically install dependencies at build time (once you start the function deployment). Note that dependencies installation at build-time will result in higher build times.

• you can package your dependencies with the go mod vendor command and provide your generated vendor directory to the function archive. This approach will save you some time during builds:

Moreover if you have private dependencies you must vendor your dependencies because otherwise, our build process will not be able to retrieve those private dependencies.

For Python code samples you can have a look at the code samples page.

The Handler name is basically a path to the handler file, suffixed with the function name to use as a handler.

For example, let's say you have two handlers hello.py and world.py inside src/handlers folder:

Then, you need to provide a custom handler name for each of these handlers, so each of your functions will know which handler file to run: hello -> src/handlers/hello.say_hello and world -> src/handlers/world.to_the_world.

By default, the handler path is handler.handle (def handle in handler.py).

Additional dependencies must be included inside a package directory at the root of your archive/project:

Standard dependencies

You may install your dependencies to the package directory:

Or with a requirements.txt file:

Specific libraries (with needs for specific C compiled code)

In some cases, you might need to install libraries which require specific C compiled code such as (for example):

• numpy
• tensorflow
• pandas
• scikit-learn
• ...

Our Python runtimes run on top of alpine linux environments, for these specifics dependencies, you will have to install your dependencies inside a docker container, with a specific image, that we are providing to our users.

You may run the following command from the root of your project to install your dependencies before uploading your source code and deploying your function:

This command will run pip install with given requirements.txt file inside a docker container compatible with our function runtimes, and pull the installed dependencies locally to your package directory. As these dependencies have been installed on top of alpine linux with our compatible system libraries, you will be able to upload your source code and deploy your function properly.

Note that the example below uses python3 runtime, but you can easily change the docker image from rg.fr-par.scw.cloud/scwfunctionsruntimes/python-dep:3.10 to rg.fr-par.scw.cloud/scwfunctionsruntimes/python-dep:3.8

For RUST code samples you can have a look at the code samples page

For PHP code samples you can have a look at the code samples page

When deleting a Functions Namespace, we take care of removing all sub-resources such as Functions and CRONs deployed in this namespace.

• With Serverless Framework:

• With curl:

Please note that deleting a Scaleway Functions namespace will not automatically delete Scaleway Container Registry namespaces linked to your FAAS project. It is your responsibility to manually remove your Registry namespaces via Scaleway Console or API.

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.

To get all tokens associated with a function:

Note that tokens can only be read at creation time, and are not stored, hence they can't be retrieved if lost.

To generate a token for a function:

expire_at is optional, and in this example is set to 90 days from today (see EXPIRE_AT). If you don't set expire_at, your token will never expire.

To revoke a token you need to delete it:

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:

Functions and containers output logs can be retrieved from the endpoint GET /logs. You need to pass its ID as a function_id parameter.

To speedup your developments and testing you can test your functions locally with the following tools:

• Go Local Testing
• Python Local Testing.

Get the namespace associated with the given id.

Update the space associated with the given id.

Delete the namespace associated with the given id.

Get the function associated with the given id.

Update the function associated with the given id.

Delete the function associated with the given id.

Deploy a function associated with the given id.

Get a download URL for a function associated with the given id.

Get an upload URL of a function associated with the given id.

List available function runtimes.

Get the cron associated with the given id.

Update the cron associated with the given id.

Delete the cron associated with the given id.