Containers APIv1beta1

Scaleway 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 a 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 container 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 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 with the Scaleway Container Registry product
  • Deploy any docker image from one of your registry namespace

A Container in Scaleway Containers consists of multiple components:

• Environment Variables: You 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 env var have the same name for example).
• Docker Image
• Resources: users may decide how much computing resources 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.

Representation of given CPU resources based on configured Memory Limit (in MB) for a container:

Where 560mCPU accounts roughly for half of one CPU power of a Scaleway General Purpose instance

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" on each Sunday (see this page from Ubuntu's official documentation).
• 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.

By default, creating a container will make it public, meaning that anybody knowing the endpoint could execute it.

A container can be made private with the privacy parameter.

Here is the workflow used to authenticate to a private Scaleway Container:

• Create a container with privacy private
• Deploy your container
• Generate a specific token from our API
• Send a request to your container and provide the generated token (all unauthenticated requests will be rejected).

Privacy works with JWT tokens. A JWT Token can be retrieved from the endpoint GET /issue-jwt. Depending on the parameters, a jwt token can be valid for either a container, or a namespace:

• /issue-jwt?namespace_id=1: issues JWT valid for all containers inside namespace with ID 1.
• /issue-jwt?container_id=1: issues JWT valid only for container with id 1.

Note that you may (optional) provide an expiration date (formatted "yyyy-mm-ddT00:00:00Z") for the token: example /issue-jwt?expires_at=2022-01-02T00:00:00Z&namespace_id=1 will generate a token, valid for all containers inside Namespace with id 1, and this token will be valid until January 2nd 2022.

The token will have the following claims:

{
  "application_claim": [
    {
      "namespace_id": "string",
      "container_id": "string" // optional: id of the container
    }
  ]
}

Tokens are not stored by Scaleway and can not be retrieved if lost (but new tokens can be generated).

Token revocation is not yet supported, the best way to reset the tokens is to destroy and recreate the namespaces and all of its containers.

It will set the following environment variables, which you can use in your application to validate incoming requests (token provided by our APIs):

• SCW_PUBLIC: true or false based on your privacy settings
• SCW_PUBLIC_KEY: PEM-encoded public Key used to decrypt tokens
• SCW_NAMESPACE_ID: Current Namespace ID
• SCW_APPLICATION_ID: Current Container ID

As described above, tokens generated from our API will contain either namespace id or application id in its claims, so you may verify it's validity (after decrypting the JWT with the inject SCW_PUBLIC_KEY).

Containers output logs can be retrieved from the endpoint GET /logs. You need to pass its ID as an container_id parameter.

Quick Start Guide

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 then as variables to use them with curl

export TOKEN="<Secret key of your token>"
# Only available in fr-par at the moment
export REGION="<choose your location (nl-ams/fr-par)>"
export PROJECT_ID="<your project ID>"

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

Customize the name and set your project ID

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

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:

export NAMESPACE_ID="<your namespace id>"

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

curl -s -H "X-Auth-Token: $TOKEN" -X DELETE "https://api.scaleway.com/containers/v1beta1/regions/$REGION/namespaces/$NAMESPACE_ID"

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.

To push your image, we invite you to check the container registry documentation.

export REGISTRY_IMAGE="rg.fr-par.scw.cloud/myregistrynamespace/mycontainer:latest"
curl -X POST \
-H "X-Auth-Token: $TOKEN" \
"https://api.scaleway.com/containers/v1beta1/regions/$REGION/containers" \
-d "{\"name\": \"container-name\", \"registry_image\": \"$REGISTRY_IMAGE\",\"namespace_id\": \"$NAMESPACE_ID\", \"memory_limit\": 128, \"min_scale\": 0, \"max_scale\": 20}"

curl -X POST -H "X-Auth-Token: $TOKEN" "https://api.scaleway.com/containers/v1beta1/regions/$REGION/containers/$CONTAINER_ID/deploy" -d "{}"

curl -X GET -H "X-Auth-Token: $TOKEN" "https://api.scaleway.com/containers/v1beta1/regions/$REGION/containers/$CONTAINER_ID"
export CONTAINER_ENDPOINT="<endpoint>"
curl -X GET "$CONTAINER_ENDPOINT"

To retrieve the containers output logs:

curl -X GET -H "X-Auth-Token: $TOKEN" "https://api.scaleway.com/containers/v1beta1/regions/$REGION/logs?container_id=$CONTAINER_ID"

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 container associated with the given id.

Update the container associated with the given id.

Delete the container associated with the given id.

Deploy a container associated with the given id.