Containers APIv1beta1

Download OpenAPI

Introduction

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

Main features

  • 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

This page focuses on working with the Scaleway API, for detailed informations about containers you can dive into the Scaleway Documentation for Containers.

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:

Memory (in MB)CPU
12870m
256140m
512280m
1024560m
20481120m
30721680m
40962240m

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). 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.

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:

Then, export then 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 containers, and trigger your containers 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 containers and crons) use the following call:

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.

Deploy a container

To retrieve the containers output logs:

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.

To get all tokens associated with a container:

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 container:

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 container 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 container by providing a token using curl, you may run the following command:

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

List all your namespaces

GET
/containers/v1beta1/regions/{region}/namespaces
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

page
integer
Page number. The default value is 1.

page_size
integer
Page size. The default value is 20.

order_by
string
Possible values are created_at_asc, created_at_desc, name_asc and name_desc. The default value is created_at_asc.

name
nullable string

organization_id
nullable string

project_id
nullable string
200 Response

namespaces
array

total_count
integer
Response Example
POST
/containers/v1beta1/regions/{region}/namespaces
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Body

name
string

environment_variables
nullable object

project_id
string

description
nullable string

secret_environment_variables
array
Request Example
200 Response

id
string

name
string

environment_variables
map

organization_id
string

project_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

registry_namespace_id
string

error_message
nullable string

registry_endpoint
string

description
nullable string

secret_environment_variables
array

region
string
Response Example

Get the namespace associated with the given id.

GET
/containers/v1beta1/regions/{region}/namespaces/{namespace_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

namespace_id
required string
200 Response

id
string

name
string

environment_variables
map

organization_id
string

project_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

registry_namespace_id
string

error_message
nullable string

registry_endpoint
string

description
nullable string

secret_environment_variables
array

region
string
Response Example

Update the space associated with the given id.

PATCH
/containers/v1beta1/regions/{region}/namespaces/{namespace_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

namespace_id
required string
Body

environment_variables
nullable object

description
nullable string

secret_environment_variables
array
Request Example
200 Response

id
string

name
string

environment_variables
map

organization_id
string

project_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

registry_namespace_id
string

error_message
nullable string

registry_endpoint
string

description
nullable string

secret_environment_variables
array

region
string
Response Example

Delete the namespace associated with the given id.

DELETE
/containers/v1beta1/regions/{region}/namespaces/{namespace_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

namespace_id
required string
200 Response

id
string

name
string

environment_variables
map

organization_id
string

project_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

registry_namespace_id
string

error_message
nullable string

registry_endpoint
string

description
nullable string

secret_environment_variables
array

region
string
Response Example
GET
/containers/v1beta1/regions/{region}/containers
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

page
integer
Page number. The default value is 1.

page_size
integer
Page size. The default value is 20.

order_by
string
Possible values are created_at_asc, created_at_desc, name_asc and name_desc. The default value is created_at_asc.

namespace_id
string

name
nullable string

organization_id
nullable string

project_id
nullable string
200 Response

containers
array

total_count
integer
Response Example
POST
/containers/v1beta1/regions/{region}/containers
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Body

namespace_id
string

name
string

environment_variables
nullable object

min_scale
nullable integer

max_scale
nullable integer

memory_limit
nullable integer

timeout
nullable string
(in seconds).

privacy
string
Possible values are unknown_privacy, public and private. The default value is unknown_privacy.

description
nullable string

registry_image
nullable string

max_concurrency
nullable integer

protocol
string
Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.

port
nullable integer

secret_environment_variables
array

http_option
string
Configure 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. Possible values are unknown_http_option, enabled and redirected. The default value is enabled.
Request Example
200 Response

id
string

name
string

namespace_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating, pending and created. The default value is unknown.

environment_variables
map

min_scale
integer

max_scale
integer

memory_limit
integer

cpu_limit
integer

timeout
nullable string
(in seconds).

error_message
nullable string

privacy
string
Possible values are unknown_privacy, public and private. The default value is unknown_privacy.

description
nullable string

registry_image
string

max_concurrency
integer

domain_name
string

protocol
string
Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.

port
integer

secret_environment_variables
array

http_option
string
Configure 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. Possible values are unknown_http_option, enabled and redirected. The default value is enabled.

region
string
Response Example

Get the container associated with the given id.

GET
/containers/v1beta1/regions/{region}/containers/{container_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

container_id
required string
200 Response

id
string

name
string

namespace_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating, pending and created. The default value is unknown.

environment_variables
map

min_scale
integer

max_scale
integer

memory_limit
integer

cpu_limit
integer

timeout
nullable string
(in seconds).

error_message
nullable string

privacy
string
Possible values are unknown_privacy, public and private. The default value is unknown_privacy.

description
nullable string

registry_image
string

max_concurrency
integer

domain_name
string

protocol
string
Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.

port
integer

secret_environment_variables
array

http_option
string
Configure 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. Possible values are unknown_http_option, enabled and redirected. The default value is enabled.

region
string
Response Example

Update the container associated with the given id.

PATCH
/containers/v1beta1/regions/{region}/containers/{container_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

container_id
required string
Body

environment_variables
nullable object

min_scale
nullable integer

max_scale
nullable integer

memory_limit
nullable integer

timeout
nullable string
(in seconds).

redeploy
nullable boolean

privacy
string
Possible values are unknown_privacy, public and private. The default value is unknown_privacy.

description
nullable string

registry_image
nullable string

max_concurrency
nullable integer

protocol
string
Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.

port
nullable integer

secret_environment_variables
array

http_option
string
Configure 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. Possible values are unknown_http_option, enabled and redirected. The default value is enabled.
Request Example
200 Response

id
string

name
string

namespace_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating, pending and created. The default value is unknown.

environment_variables
map

min_scale
integer

max_scale
integer

memory_limit
integer

cpu_limit
integer

timeout
nullable string
(in seconds).

error_message
nullable string

privacy
string
Possible values are unknown_privacy, public and private. The default value is unknown_privacy.

description
nullable string

registry_image
string

max_concurrency
integer

domain_name
string

protocol
string
Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.

port
integer

secret_environment_variables
array

http_option
string
Configure 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. Possible values are unknown_http_option, enabled and redirected. The default value is enabled.

region
string
Response Example

Delete the container associated with the given id.

DELETE
/containers/v1beta1/regions/{region}/containers/{container_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

container_id
required string
200 Response

id
string

name
string

namespace_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating, pending and created. The default value is unknown.

environment_variables
map

min_scale
integer

max_scale
integer

memory_limit
integer

cpu_limit
integer

timeout
nullable string
(in seconds).

error_message
nullable string

privacy
string
Possible values are unknown_privacy, public and private. The default value is unknown_privacy.

description
nullable string

registry_image
string

max_concurrency
integer

domain_name
string

protocol
string
Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.

port
integer

secret_environment_variables
array

http_option
string
Configure 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. Possible values are unknown_http_option, enabled and redirected. The default value is enabled.

region
string
Response Example

Deploy a container associated with the given id.

POST
/containers/v1beta1/regions/{region}/containers/{container_id}/deploy
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

container_id
required string
Body

Request Example
200 Response

id
string

name
string

namespace_id
string

status
string
Possible values are unknown, ready, deleting, error, locked, creating, pending and created. The default value is unknown.

environment_variables
map

min_scale
integer

max_scale
integer

memory_limit
integer

cpu_limit
integer

timeout
nullable string
(in seconds).

error_message
nullable string

privacy
string
Possible values are unknown_privacy, public and private. The default value is unknown_privacy.

description
nullable string

registry_image
string

max_concurrency
integer

domain_name
string

protocol
string
Possible values are unknown_protocol, http1 and h2c. The default value is unknown_protocol.

port
integer

secret_environment_variables
array

http_option
string
Configure 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. Possible values are unknown_http_option, enabled and redirected. The default value is enabled.

region
string
Response Example
GET
/containers/v1beta1/regions/{region}/containers/{container_id}/logs
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

container_id
required string
Query Parameters

page
integer
Page number. The default value is 1.

page_size
integer
Page size. The default value is 20.

order_by
string
Possible values are timestamp_desc and timestamp_asc. The default value is timestamp_desc.
200 Response

logs
array

total_count
integer
Response Example
GET
/containers/v1beta1/regions/{region}/crons
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

page
integer
Page number. The default value is 1.

page_size
integer
Page size. The default value is 20.

order_by
string
Possible values are created_at_asc and created_at_desc. The default value is created_at_asc.

container_id
string
200 Response

crons
array

total_count
integer
Response Example
POST
/containers/v1beta1/regions/{region}/crons
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Body

container_id
string

schedule
string

args
object

name
nullable string
Request Example
200 Response

id
string

container_id
string

schedule
string

args
object

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

name
string
Response Example

Get the cron associated with the given id.

GET
/containers/v1beta1/regions/{region}/crons/{cron_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

cron_id
required string
200 Response

id
string

container_id
string

schedule
string

args
object

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

name
string
Response Example

Update the cron associated with the given id.

PATCH
/containers/v1beta1/regions/{region}/crons/{cron_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

cron_id
required string
Body

container_id
nullable string

schedule
nullable string

args
object

name
nullable string
Request Example
200 Response

id
string

container_id
string

schedule
string

args
object

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

name
string
Response Example

Delete the cron associated with the given id.

DELETE
/containers/v1beta1/regions/{region}/crons/{cron_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

cron_id
required string
200 Response

id
string

container_id
string

schedule
string

args
object

status
string
Possible values are unknown, ready, deleting, error, locked, creating and pending. The default value is unknown.

name
string
Response Example
GET
/containers/v1beta1/regions/{region}/domains
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

page
integer
Page number. The default value is 1.

page_size
integer
Page size. The default value is 20.

order_by
string
Possible values are created_at_asc, created_at_desc, hostname_asc and hostname_desc. The default value is created_at_asc.

container_id
string
200 Response

domains
array

total_count
integer
Response Example
POST
/containers/v1beta1/regions/{region}/domains
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Body

hostname
string

container_id
string
Request Example
200 Response

id
string

hostname
string

container_id
string

url
string

status
string
Possible values are unknown, ready, deleting, error, creating and pending. The default value is unknown.

error_message
nullable string
Response Example
GET
/containers/v1beta1/regions/{region}/domains/{domain_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

domain_id
required string
200 Response

id
string

hostname
string

container_id
string

url
string

status
string
Possible values are unknown, ready, deleting, error, creating and pending. The default value is unknown.

error_message
nullable string
Response Example
DELETE
/containers/v1beta1/regions/{region}/domains/{domain_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

domain_id
required string
200 Response

id
string

hostname
string

container_id
string

url
string

status
string
Possible values are unknown, ready, deleting, error, creating and pending. The default value is unknown.

error_message
nullable string
Response Example
GET
/containers/v1beta1/regions/{region}/tokens
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

page
integer
Page number. The default value is 1.

page_size
integer
Page size. The default value is 20.

order_by
string
Possible values are created_at_asc and created_at_desc. The default value is created_at_asc.

container_id
nullable string

namespace_id
nullable string
200 Response

tokens
array

total_count
integer
Response Example
POST
/containers/v1beta1/regions/{region}/tokens
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Body

container_id
string
Only one of container_id and namespace_id may be set.

namespace_id
string
Only one of container_id and namespace_id may be set.

description
nullable string

expires_at
nullable string
(RFC 3339 format).
Request Example
200 Response

id
string

token
string

container_id
string
Only one of container_id and namespace_id may be set.

namespace_id
string
Only one of container_id and namespace_id may be set.

public_key
deprecated string

status
string
Possible values are unknown, ready, deleting, error and creating. The default value is unknown.

description
nullable string

expires_at
nullable string
(RFC 3339 format).
Response Example
GET
/containers/v1beta1/regions/{region}/tokens/{token_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

token_id
required string
200 Response

id
string

token
string

container_id
string
Only one of container_id and namespace_id may be set.

namespace_id
string
Only one of container_id and namespace_id may be set.

public_key
deprecated string

status
string
Possible values are unknown, ready, deleting, error and creating. The default value is unknown.

description
nullable string

expires_at
nullable string
(RFC 3339 format).
Response Example
DELETE
/containers/v1beta1/regions/{region}/tokens/{token_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

token_id
required string
200 Response

id
string

token
string

container_id
string
Only one of container_id and namespace_id may be set.

namespace_id
string
Only one of container_id and namespace_id may be set.

public_key
deprecated string

status
string
Possible values are unknown, ready, deleting, error and creating. The default value is unknown.

description
nullable string

expires_at
nullable string
(RFC 3339 format).
Response Example

MISC methods

IssueJWT

deprecated
GET
/containers/v1beta1/regions/{region}/issue-jwt
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

container_id
string
Only one of container_id and namespace_id may be set.

namespace_id
string
Only one of container_id and namespace_id may be set.

expires_at
string
(RFC 3339 format).
200 Response

id
string

token
string

container_id
string
Only one of container_id and namespace_id may be set.

namespace_id
string
Only one of container_id and namespace_id may be set.

public_key
deprecated string

status
string
Possible values are unknown, ready, deleting, error and creating. The default value is unknown.

description
nullable string

expires_at
nullable string
(RFC 3339 format).
Response Example