docs(srv): how to run complex commands with Jobs and Secrets MTA-6354

macros/serverless-jobs/automate-resources-management.mdx

@@ -7,6 +7,10 @@ import Requirements from '@macros/iam/requirements.mdx'
 
 [Scaleway Serverless Jobs](/serverless-jobs/quickstart/) allows you to create and automate recurring tasks. This page shows how to create jobs to perform any operation available with the [Scaleway CLI](https://github.com/scaleway/scaleway-cli/blob/master/docs/commands/config.md) to automate the management of your Scaleway resources.
 
+<Message type="note">
+To automate complex commands, such as piped or `xargs` commands, refer to the [dedicated documentation](/serverless-jobs/how-to/execute-complex-commands/).
+</Message>
+
 Serverless Jobs are perfectly adapted for these autonomous tasks, as we do not need autoscaling or exposure via a web server. Refer to the [documentation on differences between jobs, containers, and functions](/serverless-jobs/reference-content/difference-jobs-functions-containers/) for more information.
 
 <Requirements />

menu/navigation.json

@@ -4871,6 +4871,10 @@
                     "label": "Manage the scheduling of a job",
                     "slug": "manage-job-schedule"
                   },
+                  {
+                    "label": "Execute complex startup commands",
+                    "slug": "execute-complex-commands"
+                  },
                   {
                     "label": "Reference secrets in a job",
                     "slug": "reference-secret-in-job"

pages/serverless-jobs/how-to/execute-complex-commands.mdx

@@ -0,0 +1,112 @@
+---
+title: How to execute complex startup commands using Serverless Jobs
+description: Learn how to run complex commands at job run start and scripts using Scaleway Serverless Jobs and Secrets Manager.
+tags: run execute start serverless job scaleway script startup secret bash complex command pipe
+dates:
+  validation: 2025-08-19 
+  posted: 2025-08-19
+---
+import Requirements from '@macros/iam/requirements.mdx'
+
+Scaleway Serverless Jobs allows you to execute specific startup commands when running a job. Due to technical specifications, complex commands (e.g. piped commands, `xargs` commands) may fail occasionally, preventing jobs from running successfully.
+
+You can bypass this limitation by passing complex commands and scripts to a Serverless Job via a [secret reference](/serverless-jobs/concepts/#secrets-reference). You can then inject this secret as a file in your job, and call it at startup to execute the commands it contains.
+
+<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
+- Created a [Serverless Job](/serverless-jobs/how-to/create-job/)
+
+## How to create a secret containing your command
+
+1. Click **Secret Manager** in the **Security & Identity** section of the [Scaleway console](https://console.scaleway.com/) side menu.
+
+2. In the **Region** drop-down, select the [region](/secret-manager/concepts/#region) in which you want to store your secret. Secrets cannot be moved from one region to another after creation.
+
+3. Click **+ Create secret**.
+
+4. Select **Import secret**, choose the **Opaque** secret type, then drag and drop your file to the dedicated area. The maximum file size for your secret is 64 KiB.
+    <Message type="note">
+    We recommend using a shell script (`.sh`) file containing your command. Refer to the [section below](#complex-commands-examples) for example commands.
+    </Message>
+
+5. Choose the **Scaleway-managed encryption key**, as it requires no configuration on your side.
+
+6. Choose a [path](/secret-manager/concepts/#path) for your secret.
+
+7. Enter a name for your secret, and, optionally, add a description and tags.
+
+8. Click **Create secret** to confirm.
+
+Your file can now be passed to your Serverless Job as a secret reference.
+
+## Create a Serverless Job referencing your command as a secret
+
+1. Click **Jobs** in the **Serverless** section of the side menu. The jobs page displays.
+
+2. Click **Create job**. The job creation wizard displays.
+
+3. Select the **external** container registry.
+
+4. Enter the following image URL:
+    ```sh
+    scaleway/cli:latest
+    ```
+
+5. Enter a name, select the desired region, and choose the smallest **resources** available.
+
+6. From the **Data** tab, add your command file as a [secrets reference](/serverless-functions/concepts/#secrets). Refer to the [dedicated documentation](/serverless-jobs/how-to/reference-secret-in-job/) on secrets for more information.
+
+7. From the **Execution** tab, add the following startup command to call your file:
+    ```sh
+    bash /complex_command.sh start
+    ```
+
+8. Click **Create job** to finish.
+
+You job is now ready to run.
+
+## Complex commands examples
+
+Below are examples of commands that must be passed via a secret referenced as a file in Serverless Jobs. You can find more complex command examples on the [Scaleway CLI repository](/https://github.com/scaleway/scaleway-cli/blob/master/docs/cookbook.md).
+
+**Retrieve a specific field from the output using jq**
+
+```bash
+## Retrieve all available instance type names
+
+# Using jq
+scw -o json instance server-type list | jq -r '.[].name'
+# Using CLI templates
+scw instance server-type list -o template="{{ .Name }}"
+```
+
+**Filter command output using jq**
+
+```bash
+# Retrieve all available instance type with GPUs
+scw -o json instance server-type list | jq '.[] | select (.gpu > 0)'
+```
+
+**Parallelize actions using xargs**
+
+```bash
+## Reboot all listed servers at the same time, 8 max concurrent actions
+
+# Using jq
+scw -o json instance server list | jq -r '.[].id' | xargs -L1 -P8 scw instance server reboot
+# Using CLI templates
+scw instance server list -o template="{{ .ID }}" | xargs -L1 -P8 scw instance server reboot
+```
+
+**Create arguments for a CLI command and use it in xargs**
+
+```bash
+## List private-nics of all listed servers
+
+# Using jq
+scw -o json instance server list | jq -r '.[] | "server-id=\(.id)"' | xargs -L1 scw instance private-nic list
+# Using CLI templates
+scw instance server list -o template="server-id={{ .ID }}" | xargs -L1 scw instance private-nic list
+```

pages/serverless-jobs/troubleshooting/index.mdx

@@ -52,3 +52,4 @@ productIcon: ServerlessJobsProductIcon
 - [My Job run is in an error state](/serverless-jobs/troubleshooting/job-in-error-state)
 - [Missing metrics for my Job Run](/serverless-jobs/troubleshooting/missing-metrics)
 </LinksList>
+- [Job startup command fails](/serverless-jobs/troubleshooting/job-startup-command-fails/)

pages/serverless-jobs/troubleshooting/job-startup-command-fails.mdx

@@ -0,0 +1,20 @@
+---
+title: My job run fails when executing the startup command
+description: Troubleshoot job run failures due to startup commands for your Scaleway Serverless Jobs.
+tags: serverless jobs troubleshooting issue error state message fail execution log faliure does not run command
+dates:
+  validation: 2025-08-20
+  posted: 2025-08-20
+---
+
+## Problem
+
+My job run fails due to its startup command.
+
+## Cause
+
+Complex commands, such as piped or `xargs` commands may lead to failures due to techical limitations of Serverless Jobs.
+
+## Possible solutions
+
+You can bypass this issue by using [Secret Manager](/secret-manager/) to pass complex commands in a shell script file via a [secret reference](/serverless-jobs/concepts/secrets-references). Refer to the [dedicated documentation](/serverless-jobs/how-to/execute-complex-commands/) for more information