Scaleway plugin for Serverless Framework

Plugin for using Scaleway Serverless Functions and Serverless Containers with Serverless Framework.

Requirements

• Serverless Framework v3 CLI installed on your local computer (e.g. run npm install [email protected] -g). V4 is not supported.
• Scaleway CLI installed on your local computer

If you are using Scaleway IAM, you need to be the Owner of the Scaleway Organization in which the deployment will take place, or be an IAM user of the Organization with a policy granting you the necessary Permission Sets. See the IAM Overview for more information.

Quick start

1. Export the template you wish to use (see the list here). We will use python3:

export TEMPLATE=python3

2. Create a function from this template:

serverless create \
  --path ${TEMPLATE}-func \
  --template-url https://github.com/scaleway/serverless-scaleway-functions/tree/master/examples/${TEMPLATE}

3. Install dependencies:

cd ${TEMPLATE}-func
npm i

4. Deploy the function:

serverless deploy

5. Invoke the function (note that first is the function name in this example):

serverless invoke --function first

Contents

• Quick start
• Configuration
• Supported commands
• Unsupported commands
• Useful links
• Contributing
• License

More detailed documentation can be found in the docs folder, including:

• Managing containers
• Configuring custom domains
• Handling events (e.g. CRONs)
• Security and secret management
• Troubleshooting

There are also language-specific notes for Serverless Functions:

• Golang functions
• Javascript functions
• PHP functions
• Python functions
• Rust functions

Configuration

With Serverless Framework, your functions and containers are defined in a serverless.yml file.

Each serverless.yml file corresponds to one function or container namespace.

General configuration

The following configuration is common to both functions and containers:

# The name of your namespace
service: my-namespace

# Read environment variables from a .env file
useDotenv: false

# Use of this plugin. This must not be changed
plugins:
  - serverless-scaleway-functions

# Scaleway-specific configuration
provider:
  # Must not change
  name: scaleway

  # Runtime used for functions (unless overridden)
  # List: https://www.scaleway.com/en/docs/serverless/functions/reference-content/functions-lifecycle/#available-runtimes
  runtime: python310

  # Global environment variables, used in every function/container in this namespace
  env:
    MY_VAR: "some var"
    MY_OTHER_VAR: "some other var"

  # Global secrets, used in every function/container in this namespace
  secret:
    MY_SECRET: "some secret"
    MY_OTHER_SECRET: "some other secret"

  # Optional override of Scaleway credentials
  scwToken: <scw-token>
  scwProject: <scw-project-id>

  # Scaleway region for the deploy
  scwRegion: fr-par

# Include/exclude directories
package:
  patterns:
    - "!node_modules/**"
    - "!.gitignore"
    - "!.git/**"

Function-specific configuration

To define functions, you can include a functions block:

functions:
  my-func:
    # Handler entrypoint
    handler: handler.py

    # Minimum and maximum number of instances
    minScale: 0
    maxScale: 10

    # Memory limit (in MiB)
    # Limits: https://www.scaleway.com/en/docs/serverless/functions/reference-content/functions-limitations/
    memoryLimit: 1024

    # Maximum duration a request will wait to be served before it times out (in seconds)
    # Value in string format ex: "300s" (default: 300 seconds)
    timeout: 300s

    # Runtime for this function, allows overriding provider.runtime
    runtime: node20

    # How to handle HTTP. Options: enabled (allow HTTP), or redirected (redirect HTTP -> HTTPS)
    httpOption: enabled

    # Execution environment to use when running the function. Options: v1 (legacy), v2 (recommended, with improved cold starts)
    sandbox: v2

    # Controls privacy of the function. Options: public (no authentication), private (token-based authentication)
    privacy: public

    # Local environment variables, used only in this function
    env:
      LOCAL_VAR: "local var"

    # Local secrets, used only in this function
    secret:
      LOCAL_SECRET: "local secret"

    # Custom domains configured for the function
    # https://www.scaleway.com/en/docs/compute/functions/how-to/add-a-custom-domain-name-to-a-function/
    custom_domains:
      - my-func.some.domain.com

    # List of events to trigger the function
    events:
      - schedule:
          rate: "1 * * * *"
          # Data passed as input in the request
          input:
            key-a: "value-a"
            key-b: "value-b"

Container-specific configuration

To define containers, you can include a custom.containers block (note that you can only have functions or custom.containers).

custom:
  containers:
    my-container:
      # Subdirectory holding the Dockerfile, cannot be used with registryImage
      directory: container/

      # Name of the registry image, cannot be used with directory
      registryImage: nginx:latest

      # Minimum and maximum number of instances
      minScale: 0
      maxScale: 10

      # Configuration used to decide when to scale the container up or down
      scalingOption:
        # Can be one of: concurrentRequests, cpuUsage, memoryUsage
        type: concurrentRequests
        # Value to trigger scaling up
        # It's expressed in:
        # - concurrentRequests: number of requests
        # - cpuUsage: percentage of CPU usage
        # - memoryUsage: percentage of memory usage
        # Note that cpu and memory scaling are only available for minScale >= 1 containers
        threshold: 50

      # Memory limit (in MiB)
      # Limits: https://www.scaleway.com/en/docs/serverless/containers/reference-content/containers-limitations/
      memoryLimit: 1024

      # CPU limit for the container in mvCPU, chosen based on resource tiers if not set
      # Limits and tiers: https://www.scaleway.com/en/docs/serverless/containers/reference-content/containers-limitations/
      cpuLimit: 1000

      # Maximum duration a request will wait to be served before it times out (in seconds)
      # Value in string format ex: "300s" (default: 300 seconds)
      timeout: 300s

      # How to handle HTTP. Options: enabled (allow HTTP), or redirected (redirect HTTP -> HTTPS)
      httpOption: enabled

      # Execution environment to use when running the container. Options: v1 (legacy), v2 (recommended, with improved cold starts)
      sandbox: v2

      # Controls privacy of the container. Options: public (no authentication), private (token-based authentication)
      privacy: public

      # Local environment variables, used only in this container
      env:
        LOCAL_VAR: "local var"

      # Local secrets, used only in this container
      secret:
        LOCAL_SECRET: "local secret"

      # Custom domains configured for the function
      # https://www.scaleway.com/en/docs/serverless/containers/how-to/add-a-custom-domain-to-a-container/
      custom_domains:
        - my-container.some.domain.com

      # Health check configuration
      healthCheck:
        type: http # Or tcp if you only want to check that the port is open
        httpPath: /health
        interval: 10s
        failureThreshold: 3

      # List of events to trigger the container
      events:
        - schedule:
            rate: "1 * * * *"
            # Data passed as input in the request
            input:
              key-a: "value-a"
              key-b: "value-b"

      # Deprecated: number of simultaneous requests to handle
      # Please use scalingOption of type concurrentRequests instead
      # maxConcurrency: 20

Supported commands

serverless deploy

Note that by default serverless deploy applies the configuration located in your serverless.yml and removes functions in that namespace that are not in the file.

This can be switched off by setting the singleSource option to false.

serverless logs

Warning

This command is deprecated and will be removed on March 12, 2024. Please refer to the documentation (for functions and containers) to continue getting your logs. TL;DR: You can still access function and container logs conveniently via the Cockpit interface. Dedicated dashboards called "Serverless Functions Logs" and "Serverless Containers Logs" are accessible there.

The serverless logs command lets you watch the logs of a specific function or container.

You can fetch the logs of a specific function for with the --function option. You must specify the name of your function in the command.

serverless logs --function <function_or_container_name>

serverless info

The serverless info command gives you information about your functions' or containers' current deployement state in JSON format.

Unsupported commands

serverless invoke local

serverless invoke local is not supported directly but instead we provide additional packages to install close to your handler.

Documentation is available through runtimes frameworks for:

• Go
• Python
• Node

Useful links

• Scaleway Serverless Functions Documentation
• Scaleway Serverless Containers Documentation
• Serverless Framework documentation
• Scaleway Serverless example projects

Contributing

This plugin is developed and maintained by the Scaleway Serverless Team, but we welcome pull requests and issues, and are available to chat on our Community Slack Channels: #serverless-containers and #serverless-functions.

If you are looking for a way to contribute please read CONTRIBUTING.md. You can also look at the development documentation.

For general information about developing Serverless Framework, refer to the Serverless Framework plugins documentation.

Help & support

• Scaleway support is available on Scaleway Console.
• Additionally, you can join our Slack Community

Reach Us

We love feedback. Feel free to:

• Open a Github issue
• Send us a message on the Scaleway Slack community, in the #serverless-functions channel.

License

This project is MIT licensed.