Serverless Framework: Deploy on Scaleway Functions
The Scaleway functions plugin for Serverless Framework allows users to deploy their functions and containers to Scaleway Functions with a simple serverless deploy.
Serverless Framework handles everything from creating namespaces to function/code deployment by calling APIs endpoint under the hood.
Requirements
- Install node.js
- Install Serverless CLI (
npm install serverless -g
)
Let's work into ~/my-srvless-projects
# mkdir ~/my-srvless-projects
# cd ~/my-srvless-projects
Create a Project
The easiest way to create a project is to use one of our templates. The list of templates is here
Let's use python3
serverless create --template-url https://github.com/scaleway/serverless-scaleway-functions/tree/master/examples/python3 --path myService
Once it's done, we can install mandatory node packages used by serverless
cd mypython3functions
npm i
Note: these packages are only used by serverless, they are not shipped with your functions.
Configure your functions
Your functions are defined in the serverless.yml
file created:
service: scaleway-python3
configValidationMode: off
provider:
name: scaleway
runtime: python310
# Global Environment variables - used in every functions
env:
test: test
scwToken: <scw-token>
scwProject: <scw-project-id>
# region in which the deployment will happen, (default fr-par)
scwRegion: <scw-region>
plugins:
- serverless-scaleway-functions
package:
patterns:
- '!node_modules/**'
- '!.gitignore'
- '!.git/**'
functions:
first:
handler: handler.py
# Local environment variables - used only in given function
env:
local: local
Note: provider.name
and plugins
MUST NOT be changed, they enable us to use the scaleway provider
This file contains the configuration of one namespace containing one or more functions (in this example, only one)
of the same runtime (here python3
)
The different parameters are:
service
: your namespace nameprovider.runtime
: the runtime of your functions (check the supported runtimes above)provider.env
: environment variables attached to your namespace are injected to all your namespace functionsprovider.secret
: secret environment variables attached to your namespace are injected to all your namespace functions, see this example projectscwToken
: Scaleway token you got in prerequisitesscwProject
: Scaleway org id you got in prerequisitesscwRegion
: Scaleway region in which the deployment will take place (default:fr-par
)package.patterns
: usually, you don't need to configure it. Enable to include/exclude directories to/from the deploymentfunctions
: Configure of your fonctions. It's a yml dictionary, with the key being the function namehandler
(Required): file or function which will be executed. See the next section for runtime specific handlersenv
(Optional): environment variables specific for the current functionsecret
(Optional): secret environment variables specific for the current function, see this example projectminScale
(Optional): how many function instances we keep running (default: 0)maxScale
(Optional): maximum number of instances this function can scale to (default: 20)memoryLimit
: ram allocated to the function instances. See the introduction for the list of supported valuestimeout
: is the maximum duration in seconds that the request will wait to be served before it times out (default: 300 seconds)runtime
: (Optional) runtime of the function, if you need to deploy multiple functions with different runtimes in your Serverless Project. If absent,provider.runtime
will be used to deploy the function, see this example project.events
(Optional): List of events to trigger your functions (e.g, trigger a function based on a schedule withCRONJobs
). Seeevents
section below
Functions Handler
Based on the chosen runtime, the handler
variable on function might vary.
Node
Path to your handler file (from serverless.yml), omit ./
, ../
, and add the exported function to use as a handler:
- src
- handlers
- firstHandler.js => module.exports.myFirstHandler = ...
- secondHandler.js => module.exports.mySecondHandler = ...
- serverless.yml
In serverless.yml:
provider:
# ...
runtime: node16 # or node10, node14, node17
functions:
first:
handler: src/handlers/firstHandler.myFirstHandler
second:
handler: src/handlers/secondHandler.mySecondHandler
Python
Similar to node
, path to handler file src/testing/handler.py
:
- src
- handlers
- firstHandler.py => def my_first_handler
- secondHandler.py => def my_second_handler
- serverless.yml
In serverless.yml:
provider:
# ...
runtime: python310 # or python37, python38, python39
functions:
first:
handler: src/handlers/firstHandler.my_first_handler
second:
handler: src/handlers/secondHandler.my_second_handler
Golang
Path to your handler's package, for example if I have the following structure:
- src
- testing
- handler.go -> package main in src/testing subdirectory
- second
- handler.go -> package main in src/second subdirectory
- serverless.yml
- handler.go -> package main at the root of project
Your serverless.yml functions
should look something like this:
provider:
# ...
runtime: go118
functions:
main:
handler: "."
testing:
handler: src/testing
second:
handler: src/second
Events
With events
, you may link your functions with specific triggers, which might include CRON Schedule (Time based)
, MQTT Queues
(Publish on a topic will trigger the function), S3 Object update
(Upload an object will trigger the function).
Note that we do not include HTTP triggers in our event types, as a HTTP endpoint is created for every function. Triggers are just a new way to trigger your Function, but you will always be able to execute your code via HTTP.
Here is a list of supported triggers on Scaleway Serverless, and the configuration parameters required to deploy them:
- schedule: Trigger your function based on CRON schedules
rate
: CRON Schedule (UNIX Format) on which your function will be executedinput
: key-value mapping to define arguments that will be passed into your function's event object during execution.
To link a Trigger to your function, you may define a key events
in your function:
functions:
handler: myHandler.handle
events:
# "events" is a list of triggers, the first key being the type of trigger.
- schedule:
# CRON Job Schedule (UNIX Format)
rate: '1 * * * *'
# Input variable are passed in your function's event during execution
input:
key: value
key2: value2
You may link Events to your Containers too (See section Managing containers
below for more informations on how to deploy containers):
custom:
containers:
mycontainer:
directory: my-directory
# Events key
events:
- schedule:
rate: '1 * * * *'
input:
key: value
key2: value2
You may refer to the follow examples:
Managing containers
Requirements: You need to have Docker installed to be able to build and push your image to your Scaleway registry.
You must define your containers inside the custom.containers
field in your serverless.yml manifest.
Each container must specify the relative path of its application directory (containing the Dockerfile, and all files related to the application to deploy):
custom:
containers:
mycontainer:
directory: my-container-directory
# port: 8080
# Environment only available in this container
env:
MY_VARIABLE: "my-value"
Here is an example of the files you should have, the directory
containing your Dockerfile and scripts is my-container-directory
.
.
├── my-container-directory
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── server.py
│ └── (...)
├── node_modules
│ ├── serverless-scaleway-functions
│ └── (...)
├── package-lock.json
├── package.json
└── serverless.yml
Scaleway's platform will automatically inject a PORT environment variable on which your server should be listening for incoming traffic. By default, this PORT is 8080. You may change the port
in your serverless.yml
.
You may use the container example to getting started.
Logs
The serverless logs
command lets you watch the logs of a specific function or container.
Pass the function or container name you want to fetch the logs for with --function
:
serverless logs --function <function_or_container_name>
Documentation and useful Links
- Official Scaleway Serverless Functions Documentation
- Official Scaleway Serverless Containers Documentation
- Scaleway Functions Golang Runtime (you
MUST
use this library if you plan to develop with Golang). - Serverless Framework documentation
- Scaleway Cloud Provider
- Examples/Templates for different runtimes on Scaleway Functions
Contributing
This plugin is mainly developed and maintained by Scaleway Serverless Team
but you are free to open issues or discuss with us on our Community Slack Channels #serverless-containers and #serverless-functions.
License
This project is MIT licensed.