You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/container-apps/jobs.md
+32-16Lines changed: 32 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ author: craigshoemaker
6
6
ms.service: container-apps
7
7
ms.custom: build-2023, devx-track-azurecli
8
8
ms.topic: conceptual
9
-
ms.date: 08/17/2023
9
+
ms.date: 04/02/2024
10
10
ms.author: cshoe
11
11
---
12
12
@@ -33,12 +33,22 @@ The following table compares common scenarios for apps and jobs:
33
33
| An HTTP server that serves web content and API requests | App | Configure an [HTTP scale rule](scale-app.md#http). |
34
34
| A process that generates financial reports nightly | Job | Use the [*Schedule* job type](#scheduled-jobs) and configure a cron expression. |
35
35
| A continuously running service that processes messages from an Azure Service Bus queue | App | Configure a [custom scale rule](scale-app.md#custom). |
36
-
| A job that processes a single message or a small batch of messages from an Azure queue and exits | Job | Use the *Event* job type and [configure a custom scale rule](tutorial-event-driven-jobs.md) to trigger job executions. |
36
+
| A job that processes a single message or a small batch of messages from an Azure queue and exits | Job | Use the *Event* job type and [configure a custom scale rule](tutorial-event-driven-jobs.md) to trigger job executions when there are messages in the queue. |
37
37
| A background task that's triggered on-demand and exits when finished | Job | Use the *Manual* job type and [start executions](#start-a-job-execution-on-demand) manually or programmatically using an API. |
38
38
| A self-hosted GitHub Actions runner or Azure Pipelines agent | Job | Use the *Event* job type and configure a [GitHub Actions](tutorial-ci-cd-runners-jobs.md?pivots=container-apps-jobs-self-hosted-ci-cd-github-actions) or [Azure Pipelines](tutorial-ci-cd-runners-jobs.md?pivots=container-apps-jobs-self-hosted-ci-cd-azure-pipelines) scale rule. |
39
39
| An Azure Functions app | App |[Deploy Azure Functions to Container Apps](../azure-functions/functions-container-apps-hosting.md). |
40
40
| An event-driven app using the Azure WebJobs SDK | App |[Configure a scale rule](scale-app.md#custom) for each event source. |
41
41
42
+
## Concepts
43
+
44
+
A Container Apps environment is a secure boundary around one or more container apps and jobs. Jobs involve a few key concepts:
45
+
46
+
***Job:** A job defines the default configuration that is used for each job execution. The configuration includes the container image to use, the resources to allocate, and the command to run.
47
+
***Job execution:** A job execution is a single run of a job that is triggered manually, on a schedule, or in response to an event.
48
+
***Job replica:** A typical job execution runs one replica defined by the job's configuration. In advanced scenarios, a job execution can run multiple replicas.
49
+
50
+
:::image type="content" source="media/jobs/azure-container-apps-jobs-overview.png" alt-text="Azure Container Apps jobs overview.":::
51
+
42
52
## Job trigger types
43
53
44
54
A job's trigger type determines how the job is started. The following trigger types are available:
@@ -49,7 +59,7 @@ A job's trigger type determines how the job is started. The following trigger ty
49
59
50
60
### Manual jobs
51
61
52
-
Manual jobs are triggered on-demand using the Azure CLI or a request to the Azure Resource Manager API.
62
+
Manual jobs are triggered on-demand using the Azure CLI, Azure portal, or a request to the Azure Resource Manager API.
53
63
54
64
Examples of manual jobs include:
55
65
@@ -66,7 +76,7 @@ To create a manual job using the Azure CLI, use the `az containerapp job create`
@@ -223,7 +233,7 @@ Event-driven jobs are triggered by events from supported [custom scalers](scale-
223
233
224
234
Container apps and event-driven jobs use [KEDA](https://keda.sh/) scalers. They both evaluate scaling rules on a polling interval to measure the volume of events for an event source, but the way they use the results is different.
225
235
226
-
In an app, each replica continuously processes events and a scaling rule determines the number of replicas to run to meet demand. In event-driven jobs, each job typically processes a single event, and a scaling rule determines the number of jobs to run.
236
+
In an app, each replica continuously processes events and a scaling rule determines the number of replicas to run to meet demand. In event-driven jobs, each job execution typically processes a single event, and a scaling rule determines the number of job executions to run.
227
237
228
238
Use jobs when each event requires a new instance of the container with dedicated resources or needs to run for a long time. Event-driven jobs are conceptually similar to [KEDA scaling jobs](https://keda.sh/docs/latest/concepts/scaling-jobs/).
229
239
@@ -237,7 +247,7 @@ To create an event-driven job using the Azure CLI, use the `az containerapp job
@@ -341,13 +351,13 @@ To start a job execution using the Azure Resource Manager REST API, make a `POST
341
351
The following example starts an execution of a job named `my-job` in a resource group named `my-resource-group`:
342
352
343
353
```http
344
-
POST https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/my-resource-group/providers/Microsoft.App/jobs/my-job/start?api-version=2022-11-01-preview
354
+
POST https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/my-resource-group/providers/Microsoft.App/jobs/my-job/start?api-version=2023-05-01
345
355
Authorization: Bearer <TOKEN>
346
356
```
347
357
348
358
Replace `<SUBSCRIPTION_ID>` with your subscription ID.
349
359
350
-
To authenticate the request, replace `<TOKEN>` in the `Authorization` header with a valid bearer token. For more information, see [Azure REST API reference](/rest/api/azure).
360
+
To authenticate the request, replace `<TOKEN>` in the `Authorization` header with a valid bearer token. The identity used to generate the token must have `Contributor` permission to the Container Apps job resource. For more information, see [Azure REST API reference](/rest/api/azure).
351
361
352
362
# [Azure portal](#tab/azure-portal)
353
363
@@ -357,6 +367,9 @@ To start a job execution in the Azure portal, select **Run now** in the job's ov
357
367
358
368
When you start a job execution, you can choose to override the job's configuration. For example, you can override an environment variable or the startup command to run the same job with different inputs. The overridden configuration is only used for the current execution and doesn't change the job's configuration.
359
369
370
+
> [!IMPORTANT]
371
+
> When overriding the configuration, the job's entire template configuration is replaced with the new configuration. Ensure that the new configuration includes all required settings.
372
+
360
373
# [Azure CLI](#tab/azure-cli)
361
374
362
375
To override the job's configuration while starting an execution, use the `az containerapp job start` command and pass a YAML file containing the template to use for the execution. The following example starts an execution of a job named `my-job` in a resource group named `my-resource-group`.
@@ -367,6 +380,8 @@ Retrieve the job's current configuration with the `az containerapp job show` com
367
380
az containerapp job show --name "my-job" --resource-group "my-resource-group" --query "properties.template" --output yaml > my-job-template.yaml
368
381
```
369
382
383
+
The `--query "properties.template"` option returns only the job's template configuration.
384
+
370
385
Edit the `my-job-template.yaml` file to override the job's configuration. For example, to override the environment variables, modify the `env` section:
To override the job's configuration, include a template in the request body. The following example overrides the startup command to run a different command:
398
413
399
414
```http
400
-
POST https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/my-resource-group/providers/Microsoft.App/jobs/my-job/start?api-version=2022-11-01-preview
415
+
POST https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/my-resource-group/providers/Microsoft.App/jobs/my-job/start?api-version=2023-05-01
401
416
Content-Type: application/json
402
417
Authorization: Bearer <TOKEN>
403
418
@@ -421,7 +436,7 @@ Authorization: Bearer <TOKEN>
421
436
}
422
437
```
423
438
424
-
Replace `<SUBSCRIPTION_ID>` with your subscription ID and `<TOKEN>` in the `Authorization` header with a valid bearer token. For more information, see [Azure REST API reference](/rest/api/azure).
439
+
Replace `<SUBSCRIPTION_ID>` with your subscription ID and `<TOKEN>` in the `Authorization` header with a valid bearer token. The identity used to generate the token must have `Contributor` permission to the Container Apps job resource. For more information, see [Azure REST API reference](/rest/api/azure).
425
440
426
441
# [Azure portal](#tab/azure-portal)
427
442
@@ -446,7 +461,7 @@ az containerapp job execution list --name "my-job" --resource-group "my-resource
446
461
To get the status of job executions using the Azure Resource Manager REST API, make a `GET` request to the job's `executions` operation. The following example returns the status of the most recent execution of a job named `my-job` in a resource group named `my-resource-group`:
447
462
448
463
```http
449
-
GET https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/my-resource-group/providers/Microsoft.App/jobs/my-job/executions?api-version=2022-11-01-preview
464
+
GET https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/my-resource-group/providers/Microsoft.App/jobs/my-job/executions?api-version=2023-05-01
450
465
```
451
466
452
467
Replace `<SUBSCRIPTION_ID>` with your subscription ID.
@@ -469,7 +484,7 @@ Container Apps jobs support advanced configuration options such as container set
469
484
470
485
### Container settings
471
486
472
-
Container settings define the containers to run in each replica of a job execution. They include environment variables, secrets, and resource limits. For more information, see [Containers](containers.md).
487
+
Container settings define the containers to run in each replica of a job execution. They include environment variables, secrets, and resource limits. For more information, see [Containers](containers.md). Running multiple containers in a single job is an advanced scenario. Most jobs run a single container.
473
488
474
489
### Job settings
475
490
@@ -478,10 +493,11 @@ The following table includes the job settings that you can configure:
| Job type |`triggerType`|`--trigger-type`| The type of job. (`Manual`, `Schedule`, or `Event`) |
481
-
| Parallelism |`parallelism`|`--parallelism`| The number of replicas to run per execution. For most jobs, set the value to `1`. |
482
-
| Replica completion count |`replicaCompletionCount`|`--replica-completion-count`| The number of replicas to complete successfully for the execution to succeed. For most jobs, set the value to `1`. |
483
496
| Replica timeout |`replicaTimeout`|`--replica-timeout`| The maximum time in seconds to wait for a replica to complete. |
497
+
| Polling interval |`pollingInterval`|`--polling-interval`| The time in seconds to wait between polling for events. Default is 30 seconds. |
484
498
| Replica retry limit |`replicaRetryLimit`|`--replica-retry-limit`| The maximum number of times to retry a failed replica. To fail a replica without retrying, set the value to `0`. |
499
+
| Parallelism |`parallelism`|`--parallelism`| The number of replicas to run per execution. For most jobs, set the value to `1`. |
500
+
| Replica completion count |`replicaCompletionCount`|`--replica-completion-count`| The number of replicas to complete successfully for the execution to succeed. Most be equal or less than the parallelism. For most jobs, set the value to `1`. |
Copy file name to clipboardExpand all lines: articles/container-apps/tutorial-event-driven-jobs.md
+5-8Lines changed: 5 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,13 +23,16 @@ In this tutorial, you learn how to work with [event-driven jobs](jobs.md#event-d
23
23
> * Deploy the job to the Container Apps environment
24
24
> * Verify that the queue messages are processed by the container app
25
25
26
-
The job you create starts an execution for each message that is sent to an Azure Storage Queue. Each job execution runs a container that performs the following steps:
26
+
The job you create starts an execution for each message that is sent to an Azure Storage queue. Each job execution runs a container that performs the following steps:
27
27
28
-
1.Dequeues one message from the queue.
28
+
1.Gets one message from the queue.
29
29
1. Logs the message to the job execution logs.
30
30
1. Deletes the message from the queue.
31
31
1. Exits.
32
32
33
+
> [!IMPORTANT]
34
+
> The scaler monitors the queue's length to determine how many jobs to start. For accurate scaling, don't delete a message from the queue until the job execution has finished processing it.
35
+
33
36
The source code for the job you run in this tutorial is available in an Azure Samples [GitHub repository](https://github.com/Azure-Samples/container-apps-event-driven-jobs-tutorial/blob/main/index.js).
0 commit comments