NavigationContentFooter

Serverless Containers API

Introduction

Scaleway Serverless Containers is a «Container As A Service» product which gives users the ability to deploy atomic serverless workloads and only pay for resources used while containers are running.

It provides many advantages, such as:

  • Containers 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 container).
    • Automated Scaling to zero when a container is not executed, which is cost-effective for the user and saves computing resources for the cloud provider.
  • Endpoint-only scaling

Serverless Framework

This page explains how to use the Scaleway Containers API, including a quickstart and the full API documentation. However, you may prefer to use the Serverless Framework plugin enabling users to deploy their serverless workloads much more easily with a single serverless deploy command.

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 containers, and trigger your containers via HTTP and CRON.

Concepts

Refer to our dedicated concepts page to find definitions of the different terms referring to Serverless Containers.

Quickstart

  1. Configure your environment variables.

    export $SCW_SECRET_KEY="<Secret key of your token>"
    export SCW_DEFAULT_REGION="<Choose your location (pl-waw/nl-ams/fr-par)>"
    export SCW_PROJECT_ID="<Your Project ID>"
    Tip

    This is an optional step that seeks to simplify your usage of the Serverless Containers API. See Regions below for help choosing a region. You can find your Project ID in the Scaleway console.

  2. Set the name for your namespace and configure your Project ID:

    curl -X POST "https://api.scaleway.com/containers/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_PROJECT_ID\", \
    \"environment_variables\": {\"YOUR_VARIABLE\": \"content\"} \
    }"
  3. Copy the response's id field, you will need it for the next steps. For the sake of simplicity, we will save the ID to a variable, which will be used in the following examples:

    export NAMESPACE_ID="<your namespace id>"
    Note

    We suppose you already have a working image here. It can be anything which listens on a env variable $PORT variable. Note that we run your container as user 1000, not root, so it must be runnable under these conditions. For more information on how to push your image, refer to the Container Registry documentation.

  4. Edit the POST request payload to use in the next step to create an Elastic Metal server. Modify the values in the example according to your requirements, using the information in the payload values section to help. For container resource criteria and default values, please refer to the Containers Limitation documentation.

    {
    "namespace_id": "string",
    "name": "string",
    "environment_variables": {
    "<key>": "string"
    },
    "min_scale": "integer",
    "max_scale": "integer",
    "memory_limit": "integer",
    "cpu_limit": "integer",
    "timeout": "integer",
    "privacy": "unknown_privacy",
    "description": "string",
    "registry_image": "string",
    "max_concurrency": "integer",
    "protocol": "unknown_protocol",
    "port": "integer",
    "secret_environment_variables": [
    {
    "key": "string",
    "value": "string"
    }
    ],
    "http_option": "enabled"
    }
    ParameterDescription
    regionThe region you want to target. Possible values are fr-par, nl-ams and pl-waw.
    namespace_idUUID of the namespace the container belongs to.
    nameName of the container.
    environment_variablesNULLABLE Environment variables of the container.
    min_scaleNULLABLE Minimum number of instances to scale the container to.
    max_scaleNULLABLE Maximum number of instances to scale the container to.
    memory_limitNULLABLE Memory limit of the container in MiB.
    cpu_limitNULLABLE CPU limit of the container in mvCPU.
    timeoutNULLABLE Request processing time limit for the container. (in seconds).
    privacyPrivacy setting of the container.
    descriptionNULLABLE Description of the container.
    registry_imageNULLABLE Name of the registry image (e.g. "rg.fr-par.scw.cloud/something/image:tag").
    max_concurrencyNULLABLE Number of maximum concurrent executions of the container.
    protocolProtocol the container uses. Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.
    portNULLABLE Port the container listens on.
    secret_environment_variablesSecret environment variables of the container.
    http_optionConfigure how HTTP and HTTPS requests are handled. Possible values:
    - redirected: Responds to HTTP request with a 301 redirect to ask the clients to use HTTPS.
    - enabled: Serve both HTTP and HTTPS traffic.
    Important

    All parameters are required, except for those marked as nullable.

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

    export REGISTRY_IMAGE="rg.fr-par.scw.cloud/myregistrynamespace/mycontainer:latest"
    curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/containers/v1beta1/regions/$SCW_DEFAULT_REGION/containers" \
    -d "{
    "name": MyContainer, \
    "registry_image": "$REGISTRY_IMAGE", \
    "namespace_id": "$NAMESPACE_ID", \
    "memory_limit": 300, \
    "cpu_limit": 200, \
    "min_scale": 0, \
    "max_scale": 20 \
    }"
  6. Run the following command to deploy your container:

    curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/containers/v1beta1/regions/$SCW_DEFAULT_REGION/containers/$CONTAINER_ID/deploy" \
    -d "{}"
  7. Run the following command to trigger your container.

    curl -X GET \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/containers/v1beta1/regions/$SCW_DEFAULT_REGION/containers/$CONTAINER_ID"
    export CONTAINER_ENDPOINT="<endpoint>"
    curl -X GET "$CONTAINER_ENDPOINT"
  8. (optional) Connect to your Cockpit (Serverless Containers Logs dashboard) to see your logs: https://www.scaleway.com/en/docs/observability/cockpit/how-to/access-grafana-and-managed-dashboards/.

  9. (optional) Use the following call to destroy a namespace (along with all containers and crons):

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

To perform the following steps, you must first ensure that:

  • You have a Scaleway account
  • You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page
  • You have installed curl
  • You have installed jq to improve readability of the API outputs

Technical information

A Container in Scaleway Containers consists of multiple components:

  • Environment variables: Users may configure specific environment variables (Database host/credentials for example) which are safely encrypted in our Database, and will be mounted inside your containers. Note that environment variables set at namespace level will also be mounted (in every container). Environment variables written at container level override the ones set at namespace level (if two of them bear the same name for example).
  • Docker image: A Docker image contains all the elements required to run your software: code, a runtime environment, tools, scripts, libraries, etc.
  • Resources: Users may decide how much computing resource to allocate to each container -> Memory Limit (in MB). We will then allocate the right amount of CPU based on Memory Limit choice. The right choice for your container's resources is very important, as you will be billed based on compute usage over time and the number of Containers executions.

Product features

  • Fully isolated environments
  • Scaling to zero (saves money and computing resources while the code is not executed)
  • High Availability and scalability (automated and configurable, each container may scale automatically according to incoming workloads)
  • Multiple event sources:
    • HTTP (request on our gateway will execute the container)
    • CRON (time-based job, runs according to configurable cron schedule)
  • Integrated to the Scaleway Container Registry product:
    • Deploy any docker image from one of your registry namespace
  • Flexible resources: you can choose values separately for your memory and CPU within a range in respect with maximum and minimum allowed values in Containers Limitation documentation.

Regions

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

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

CRON

A CRON is a type of event which triggers a Scaleway Container: it is an add-on to your container.

CRONs inside Scaleway Containers have the following properties:

  • schedule: UNIX Formatted CRON schedule. Your container will be executed based on this schedule. For example, 5 4 * * 0 means "execute my container at 04:05 AM every Sunday" (see this page from Ubuntu's official documentation). The timezone is UTC+0.
  • args: JSON object passed to your container. You can use this property to define data that will be passed to your container's event.body object. For Containers, you might handle these arguments as the HTTP request's body.

Under the hood, CRON Triggers are Kubernetes JOBs sending HTTP POST requests to your container.

Authentication

By default new containers are public meaning that no credentials are required to invoke them.

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

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

Logs

Containers logs are sent to the project's Cockpit.

The Serverless Containers Logs dashboard in Grafana can be used to see containers logs. More complex queries can be done using the "Explore" section of Grafana, and LogQL queries:

{resource_type="serverless_container"}

Additionally, the loki endpoint (https://logs.cockpit.fr-par.scw.cloud) can be used to query programmatically the containers logs using a token.

Going further

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

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

Namespaces

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

GET
/containers/v1beta1/regions/{region}/namespaces
POST
/containers/v1beta1/regions/{region}/namespaces
GET
/containers/v1beta1/regions/{region}/namespaces/{namespace_id}
PATCH
/containers/v1beta1/regions/{region}/namespaces/{namespace_id}
DELETE
/containers/v1beta1/regions/{region}/namespaces/{namespace_id}

Containers

A container is a package of software that includes all dependencies: code, runtime, configuration, and system libraries so that it can run on any host system. Scaleway provides you with custom Docker images that are entirely handled for you in the cloud. With Containers, you can rely on your favorite technologies such as Django or Ruby On Rails.

GET
/containers/v1beta1/regions/{region}/containers
POST
/containers/v1beta1/regions/{region}/containers
GET
/containers/v1beta1/regions/{region}/containers/{container_id}
PATCH
/containers/v1beta1/regions/{region}/containers/{container_id}
DELETE
/containers/v1beta1/regions/{region}/containers/{container_id}
POST
/containers/v1beta1/regions/{region}/containers/{container_id}/deploy

Crons

Crons allow you to schedule the execution of your containers.

GET
/containers/v1beta1/regions/{region}/crons
POST
/containers/v1beta1/regions/{region}/crons
GET
/containers/v1beta1/regions/{region}/crons/{cron_id}
PATCH
/containers/v1beta1/regions/{region}/crons/{cron_id}
DELETE
/containers/v1beta1/regions/{region}/crons/{cron_id}

Domains

You can customize the domain for your container by associating your container to a (sub)domain.

GET
/containers/v1beta1/regions/{region}/domains
POST
/containers/v1beta1/regions/{region}/domains
GET
/containers/v1beta1/regions/{region}/domains/{domain_id}
DELETE
/containers/v1beta1/regions/{region}/domains/{domain_id}

Tokens

Tokens allow you to manage access to your containers.

GET
/containers/v1beta1/regions/{region}/tokens
POST
/containers/v1beta1/regions/{region}/tokens
GET
/containers/v1beta1/regions/{region}/tokens/{token_id}
DELETE
/containers/v1beta1/regions/{region}/tokens/{token_id}

Triggers

Triggers enable to launch your containers using events from a message queue.

GET
/containers/v1beta1/regions/{region}/triggers
POST
/containers/v1beta1/regions/{region}/triggers
GET
/containers/v1beta1/regions/{region}/triggers/{trigger_id}
PATCH
/containers/v1beta1/regions/{region}/triggers/{trigger_id}
DELETE
/containers/v1beta1/regions/{region}/triggers/{trigger_id}
API DocsScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCareers
© 2023-2024 – Scaleway