Jobs - Concepts

Commands and arguments

The field command is deprecated in v1alpha1 in favor of startup_command and args in v1alpha2.

For more details see startup command and arguments and v1alpha2 migration guide.

Container Registry

Container Registry is the place where your images are stored before being deployed. We recommend using Scaleway Container Registry for optimal integration. See the migration guide for full details.

Environment variables

An environment variable is a variable whose value is set outside the program, typically through functionality built into the operating system. An environment variable is made up of a name/value pair, and any number may be created and available for reference at a point in time.

Ephemeral storage

In addition to CPU and RAM, Serverless Jobs also provide a storage volume for the duration of the task. This storage space allows to hold the data retrieved by the job, and disappears once the execution is complete.

Exit code

An exit code is an integer returned by a process when it finishes running. A value of 0 indicates success, while any non-zero value indicates an error. For Serverless Jobs, the exit code of a job run determines its outcome:

• 0 — the job run succeeds.
• Non-zero — the job run reaches the failed status, which may trigger a retry if the configured retry count is greater than zero. See Reason (exited_with_error) for more information about non-zero exit codes.
• null — the exit code is not set when the job run fails before the container process runs or exits. The job run still reaches the failed status, but no exit code is returned by the runtime. This typically happens for reasons such as image_not_found or technical_error.

GB-s

Unit used to measure the resource consumption of a container. It reflects the amount of memory consumed over time.

Job

Serverless Jobs is a fully managed solution that enables you to plan, schedule, queue and run batch processing workloads without worrying about provisioning and scaling. A job is a single instance of one of these batch processing workloads.

Job definition

A Job definition is a template for a Serverless Job. It contains all the information necessary to run the job, including the container image used, the resources allocated, and the command to execute. The definition acts as a blueprint for job runs.

Job name

The name of a job is part of the job definition and is used for informational purposes only.

Job run

A job run is the execution of a job definition. It can be in a running, succeeded, canceled, or failed status. Each job run has a unique identifier and can be individually monitored using Cockpit.

Job trigger

A job trigger allows you to invoke Jobs automatically at a specific time on a recurring cron schedule. It works similarly to a traditional Linux cron job, using the * * * * * format. Refer to our cron schedules reference for more information. You can add multiple triggers on the same Job Definition and also set startup commands and arguments specifically for one trigger to override the default command and arguments of your job at runtime.

Logging

Serverless offers a built-in logging system based on Scaleway Cockpit to track the activity of your resources: see monitoring Serverless Jobs.

Maximum duration

The maximum duration option allows you to define the maximum execution time before your job is automatically killed.

Metrics

Performance metrics for your Serverless resources are natively available: see monitoring Serverless Jobs.

Private Networks compatibility

Refer to the dedicated FAQ for more information on Serverless Jobs compatibility with Private Networks and Virtual Private Cloud (VPC).

Retries

Retries refer to the automatic re-execution of a failed job run. You can configure Serverless Jobs to automatically retry a job run after up to five failed attempts.

A retry is triggered when all the following conditions are met:

• The job run does not succeed and exits with an exit code other than zero.
• The maximum number of retry attempts has not been reached.

Note that succeeded and failed are final statuses. When a retry is configured and the job run encounters an error during execution, it does not transition through failed first. Instead, it goes directly from running to retrying, and only reaches failed once all retry attempts are exhausted (or succeeded if a retry succeeds). This means a job run that will be retried never passes through the failed status between attempts.

Learn how to manage the retry attempts of a Serverless Job.

Schedule (deprecated)

Job scheduling is deprecated in favor of Job triggers. Existing schedules remain active and associated jobs will continue to be invoked.

Serverless Containers

Serverless Containers is a fully managed service that enables you to run containerized applications in a scalable and serverless environment.

It automatically handles infrastructure management, scaling, and load balancing, allowing you to focus on writing code without worrying about servers or clusters. Serverless Containers supports any language, framework, or binary that can run in a container, and it integrates seamlessly with other Scaleway services, making it ideal for deploying modern, event-driven, and API-based applications.

Refer to the Serverless Containers Quickstart for more information on how to deploy and use a container.

Serverless Functions

Serverless Functions are fully managed compute services that allow you to run small, stateless code snippets or functions in response to HTTP requests or events.

These functions automatically scale based on demand and are designed to be lightweight, event-driven, and easily deployable, eliminating the need to worry about infrastructure management. Functions is built on top of Serverless Containers, meaning you can run your functions packaged in containers and have them scale efficiently.

Refer to the Serverless Functions Quickstart for more information on how to deploy and invoke a function.

Serverless Jobs

Serverless Jobs are similar to Serverless Containers but are better suited for running longer workloads. See the comparison between Serverless products for more information.

Refer to the Serverless Jobs Quickstart for more information on how to create and execute a job.

For more details about advantages of using Serverless, read the Serverless overview page.

Secrets reference

A secret reference is a mechanism that allows you to use a secret stored in Secret Manager within Serverless Jobs. It allows you to securely reference sensitive data, such as API secret keys, passwords, tokens, or certificates.

Startup commands and arguments

Serverless Jobs allows you to customize the startup_command and args instructions to override default image instructions.

• The startup_command instruction defines the command, process, or script executed when your job starts. It overrides the ENTRYPOINT of the image.
• The args instruction defines the arguments passed to the startup_command instruction. Arguments can be passed as environment variables, as shown in the example below.

Example:

env:
- name: MESSAGE
  value: "hello world"
startup_command: ["/bin/echo"]
args: ["$(MESSAGE)"]

Refer to the official Kubernetes documentation for more information on commands and arguments behavior.

Status

A Serverless Job run can have the following statuses, grouped into transient statuses (the job run is still progressing through its lifecycle) and final statuses (the job run has reached a terminal status and will not change anymore):

Transient statuses

• initialized: The job has been created in the system but has not yet entered the processing pipeline.
• validated: The job configuration and resources have been verified and are ready for scheduling.
• queued: The job is waiting for compute resources to become available.
• running: The job run is currently being executed.
• interrupting: A request to stop the job (via user action or system preemption) is currently being processed.
• retrying: The job run encountered an error during execution and is being automatically re-executed, based on the configured retry policy. Note that the job run transitions directly from running to retrying — it does not pass through failed, which is a final status only reached when all retry attempts are exhausted. See Retries for more information.

Final statuses

• succeeded: The job has successfully completed.
• failed: The job run finished with an error, see Reason for detailed information about the error. Check our troubleshooting documentation to solve the issue.
• interrupted: The job was stopped before it could finish naturally, see Reason for details about the interruption.

Typical successful flow is: initialized -> validated -> queued -> running -> succeeded.

When retries are configured, a job run that errors during execution transitions directly from running to retrying (not through failed, which is a final status), then is re-executed: initialized -> validated -> queued -> running -> retrying -> queued -> running -> succeeded. Only when all retry attempts are exhausted does the job run reach the final failed status: initialized -> validated -> queued -> running -> retrying -> queued -> running -> ... -> failed.

Reason

When a Job Run is in failed or interrupted state, the Reason field will be filled to give additional details.

Configuration and permissions

These errors typically occur even before the job starts running, often due to setup issues.

• invalid_request: The job configuration contains malformed parameters or incompatible settings.
• image_not_found: The specified container image could not be found. Check your image path and registry permissions.
• invalid_image: The image was found but could not be run (typically when it's built for the wrong CPU architecture, must be amd64).
• secret_not_found: A secret referenced in your environment variables does not exist in the Secret Manager.
• secret_disabled: The required secret exists but is currently in a disabled state.

Resource Limits

These errors occur when the job hits a defined ceiling for resources or billing.

• memory_usage_exceeded: The job was terminated because it attempted to use more RAM than allocated.
• storage_usage_exceeded: The job exceeded the allocated limit for local ephemeral storage.
• quota_exceeded: The job could not run because your project has reached its resource limits. Check Quotas documentation

Runtime and lifecycle

These errors occur during the actual execution of your code.

• exited_with_error: The application inside the container finished, but returned a non-zero exit code.
• timeout: The job exceeded the maximum execution time configured for the run.
• cancellation: The job run was manually terminated by a user or via an API request.
• technical_error: An internal platform issue occurred. If this persists, contact support.

Stateless

Refers to a system or application that does not maintain any persistent state between executions. In a stateless environment, each request or operation is independent, and no information is retained from previous interactions.

This means that each request is treated as a new and isolated event, and there is no need for the system to remember previous states or data once a task is completed. Statelessness is commonly used in serverless architectures where each function execution is independent of others.

To store data you can use Scaleway Object Storage, Scaleway Managed Databases, and Scaleway Serverless Databases.

Terraform/OpenTofu

Terraform is an infrastructure-as-code tool developed by HashiCorp, while OpenTofu is an open-source fork of Terraform. Serverless Jobs integrate easily with your infrastructure as code, via our Terraform/OpenTofu provider and resources.

Examples using Terraform/OpenTofu can be found in our Serverless Examples repository, such as our example using Terraform/OpenTofu with Serverless Jobs.

vCPU-s

Unit used to measure the resource consumption of a container. It reflects the amount of vCPU used over time.