docs(srv): jobs commands and args MTA-6609 (#6000)

* docs(srv): jobs commands and args MTA-6609

* docs(srv): update

* docs(srv): update

* docs(srv): add link to api migration doc

* docs(srv): correction

* docs(srv): add note + deprecated and reference for startup command

* docs(srv): typo correction

* Apply suggestions from code review

Co-authored-by: Jessica <113192637+jcirinosclwy@users.noreply.github.com>
Co-authored-by: Néda <87707325+nerda-codes@users.noreply.github.com>

* upgrade command and startup command

* fixes

* closer dates

* changes in migration guide

* changes in migration guide

* fix broken links - typos and corrections

---------

Co-authored-by: Loic KHAMDY <lkhamdy@scaleway.com>
Co-authored-by: Jessica <113192637+jcirinosclwy@users.noreply.github.com>
Co-authored-by: Néda <87707325+nerda-codes@users.noreply.github.com>
Co-authored-by: Thomas Tacquet <thomas@tacquet.net>

Author: 5 people

pages/serverless-containers/concepts.mdx

@@ -48,7 +48,7 @@ The startup process steps are:
 
 ## Commands and arguments
 
-Serverless Containers allows you to customize the `command` and `args` instructions of your container image directly from the [Scaleway console](https://console.scaleway.com) and from the [Scaleway API](https://www.scaleway.com/en/developers/api/serverless-containers/).
+Serverless Containers allows you to customize the `command` and `args` instructions of your container image directly from the [Scaleway console](https://console.scaleway.com) and via the [Scaleway API](https://www.scaleway.com/en/developers/api/serverless-containers/).
 
 - The `command` instruction defines the command, process, or script executed when your container starts.
 - The `args` instruction defines the arguments passed to the `command` instruction. Arguments can be passed as environment variables, as shown in the example below.
@@ -109,7 +109,7 @@ Some names are reserved. [See details about reserved names](/serverless-containe
 
 ## Ephemeral storage
 
-In addition to vCPU and RAM, Serverless Containers also provide a storage volume for the duration of the task. This storage space allows you to hold data during the life of the Servlerless Container instance and disappears once the execution is complete.
+In addition to vCPU and RAM, Serverless Containers also provide a storage volume for the duration of the task. This storage space allows you to hold data during the life of the Serverless Container instance and disappears once the execution is complete.
 
 The maximum size of the ephemeral storage is tied to the allocated memory.
 

pages/serverless-jobs/concepts.mdx

@@ -8,6 +8,12 @@ dates:
 ---
 import ServerlessConcepts from '@macros/serverless/serverless-concepts.mdx'
 
+## Commands and arguments
+
+The field `command` is deprecated in favor of `startup_command` in `v1alpha2`.
+
+For more details see [startup command and arguments](/serverless-jobs/concepts/#startup-commands-and-arguments) and [v1alpha2 migration guide](/serverless-jobs/reference-content/v1alpha1-to-v1alpha2/).
+
 ## 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](/serverless-jobs/api-cli/migrate-external-image-to-scaleway-registry/) for full details.
@@ -68,13 +74,35 @@ For more details about advantages of using Serverless, [read the Serverless over
 
 A secret reference is a mechanism that allows you to use a secret stored in [Secret Manager](/secret-manager/) within Serverless Jobs. It allows you to securely reference sensitive data, such as API secret keys, passwords, tokens, or certificates.
 
-## Startup command
+## Startup commands and arguments
+
+Serverless Jobs allows you to customize the `startup_command` and `args` instructions to override default image instructions.
+
+<Message type="note">
+  * The field `command` is deprecated in favor of `startup_command`.
+  * If `startup_command` is already filled then the `command` instruction is ignored.
+  * `startup_command` and `args` can interpret environment variables, allowing for easier automations.
+</Message>
+
+- 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:**
+
+```yaml
+env:
+- name: MESSAGE
+  value: "hello world"
+startup_command: ["/bin/echo"]
+args: ["$(MESSAGE)"]
+```
 
-This optional field allows you to specify a custom command executed upon starting your job if your container image does not have one already, or if you use a public container image.
+Refer to the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/) for more information on commands and arguments behavior.
 
 ## Status
 
 A Serverless Job run can have the following statuses:
+* **Running**: your Serverless Job run is currently executing.
 * **Succeeded**: your Serverless Job run finished in a successful state.
 * **Queued**: your Serverless Job run is waiting for resources to run.
 * **Error**: your Serverless Job run finished with an error or timeout. [Check our troubleshooting documentation](/serverless-jobs/troubleshooting/job-in-error-state/) to solve the issue.
@@ -90,7 +118,7 @@ To store data you can use [Scaleway Object Storage](/object-storage/), [Scaleway
 
 ## Terraform/OpenTofu
 
-Terraform/OpenTofu is an infrastructure-as-code tool, owned by Hashicorp. Serverless Jobs integrate easily with your infrastructure as code, via our [Terraform/OpenTofu provider and resources](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/resources/job_definition).
+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](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/resources/job_definition).
 
 Examples using Terraform/OpenTofu can be found in our [Serverless Examples repository](https://github.com/scaleway/serverless-examples), such as our [example using Terraform/OpenTofu with Serverless Jobs](https://github.com/scaleway/serverless-examples/blob/main/jobs/terraform-hello-world).
 

pages/serverless-jobs/how-to/create-job.mdx

@@ -58,7 +58,7 @@ Scaleway's Serverless Jobs allows you to create jobs from several container [reg
     - Customize the ephemeral storage for your job according to your requirements. The data stored in your job is not retained once it is finished.
     </TabsTab>
     <TabsTab label="Execution">
-    1. Add a **startup command** to your job. It will be executed every time your job is run.
+    1. Add [commands and arguments](/serverless-jobs/concepts/#commands-and-arguments) to your job. They will be executed every time your job is run.
     2. Set a **maximum duration** to your job to stop it automatically if it does not complete within this limit.
     </TabsTab>
 </Tabs>

pages/serverless-jobs/how-to/migrate-command-to-startup-command.mdx

@@ -0,0 +1,76 @@
+---
+title: How to migrate from command to startup command and arguments
+description: Learn how to migrate from the legacy command system to the modern startup command and arguments for Scaleway Serverless Jobs.
+tags: containers
+dates:
+  validation: 2026-02-24
+  posted: 2025-02-24
+---
+
+import Requirements from '@macros/iam/requirements.mdx'
+
+The Serverless Jobs `v1alpha2` API introduces a new startup execution mechanism based on [commands and arguments](/serverless-jobs/concepts/#startup-commands-and-arguments), replacing the legacy `command`.
+
+The Scaleway console allows you to quickly and easily migrate your existing jobs to the new system.
+
+Migration from `command` field to `startup_command` field is mostly transparent for customers using Scaleway Console but can require some attention of API, CLI and other devtools users.
+
+The change allows for:
+- More customization for executing complex commands, by separating `startup_command` and `args`.
+- Better alignment with our underlying [Kubernetes implementation](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/).
+- The ability to compute environment variables used in command and argument strings.
+- `startup_command` is now an array of commands instead of a single string.
+
+<Requirements />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+- An existing job that uses the legacy command field
+
+## How to migrate from command to startup commands and arguments
+
+1. Click **Jobs** in the **Serverless** section of the side menu. The jobs page displays.
+
+2. Click the name of the job you want to manage, then click the **Settings** tab.
+
+3. Scroll down to the **Configure advanced options**, then click the **Execution** tab.
+
+4. Click the **Upgrade** button. A pop-up displays.
+
+5. Split your existing startup command into a command (which corresponds to the `ENTRYPOINT` Docker instruction), and arguments (which correspond to the `CMD` Docker instruction).
+
+6. Click **Upgrade to the new format** to finish.
+
+Your Serverless Job now uses the command and arguments mechanism.
+
+## Migration examples
+
+### Simple command
+
+**Legacy command**
+
+```bash
+sleep 60s
+```
+
+**Corresponding command and arguments**
+
+```yaml
+startup_command: [sleep]
+args: [60s]
+```
+
+### Complex command
+
+**Legacy command**
+
+```bash
+/app/migrate up --database "$DB_URL" --password "$DB_PASSWORD" --port 3002
+```
+
+**Corresponding command and arguments**
+
+```yaml
+startup_command: [/app/migrate]
+args: [up, --database, "$(DB_URL)", --password, "$(DB_PASSWORD)", --port, 3002]
+```

pages/serverless-jobs/menu.ts

@@ -58,6 +58,10 @@ export const serverlessJobsMenu = {
           label: 'Configure alerts for a job',
           slug: 'configure-alerts-jobs',
         },
+        {
+          label: 'Migrate from command to startup command and arguments',
+          slug: 'migrate-command-to-startup-command',
+        },
         {
           label: 'Delete a job',
           slug: 'delete-job',

pages/serverless-jobs/reference-content/v1alpha1-to-v1alpha2.mdx

@@ -28,6 +28,8 @@ It is replaced by two new fields, designed to give you more control and align wi
 
 This separation allows for a cleaner definition of entry points and arguments, mirroring standard container practices.
 
+Refer to the [dedicated documentation](/serverless-jobs/how-to/migrate-command-to-startup-command/) for more information on how to migrate from the legacy **command** to **startup command and arguments**.
+
 ### Job run troubleshooting
 
 To assist with debugging, `v1alpha2` adds a **Job Run Reason** field.
@@ -42,7 +44,7 @@ If you currently use `v1alpha1` in your automation tools, we recommend updating
 
 Ensure you update your [Scaleway Provider](/terraform/quickstart/) or [Scaleway CLI](/scaleway-cli/quickstart/) to the latest version to access `v1alpha2` fields.
 
-When defining Jobs, replace the deprecated `command` field with the new structure.
+When defining Jobs, replace the deprecated `startup_command` field with the new structure.
 
 **Example configuration (Terraform-style pseudocode):**
 
@@ -55,5 +57,5 @@ resource "scaleway_job_definition" "main" {
 # New (v1alpha2)
 resource "scaleway_job_definition" "main" {
   startup_command = ["python"]
-  args            = ["app.py", "--verbose"]
+  args    = ["app.py", "--verbose"]
 }