Skip to content

Commit 524e219

Browse files
v-ccolinv-ccolin
authored
Merge pull request #291291 from Padmalathas/BatchContainerTask
ConfigureBatchContainerIsolationTask
2 parents 020971a + 3e313d7 commit 524e219

File tree

2 files changed

+117
-0
lines changed

2 files changed

+117
-0
lines changed

‎articles/batch/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,8 @@
238238
- name: Job preparation and completion tasks
239239
displayName: release, job release
240240
href: batch-job-prep-release.md
241+
- name: Configure Container Data Isolation Task
242+
href: batch-container-isolation-task.md
241243
- name: Concurrent node tasks
242244
displayName: variable, maximize
243245
href: batch-parallel-node-tasks.md

‎articles/batch/batch-container-isolation-task.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: Configure container isolation in Azure Batch task
3+
description: Learn how to configure isolation at task level in Azure Batch.
4+
ms.topic: how-to
5+
ms.date: 12/02/2024
6+
ms.devlang: csharp
7+
ms.custom: batch
8+
---
9+
10+
# Batch Container Isolation Task
11+
12+
Azure Batch offers an isolation configuration at the task level, allowing tasks to avoid mounting the entire ephemeral disk or the entire `AZ_BATCH_NODE_ROOT_DIR`. Instead, you can customize the specific Azure Batch data paths you want to attach to the container task.
13+
14+
> [!Note]
15+
> **Azure Batch Data Path** refers to the specific paths on an Azure Batch node designated for tasks and applications. All these paths are located under `AZ_BATCH_NODE_ROOT_DIR`.
16+
17+
## Why we need isolation feature in container task
18+
19+
In a Windows container task workload, the entire ephemeral disk (D:) is attached to the task's container. For a Linux container task workload, Azure Batch attaches the entire `AZ_BATCH_NODE_ROOT_DIR` to the task's container, both in ReadWrite mode. However, if you want to customize your container volumes, this setup may cause some data to be shared across all containers running on the node. To address the same, we support the ability to customize the Azure Batch data paths that you want to attach to the task container.
20+
21+
- **Security**: Prevents the container task data from leaking into the host machine or altering data on the host machine.
22+
- **Customize**: You can customize your container task volumes as needed.
23+
24+
> [!Note]
25+
> To use this feature, please ensure that your node agent version is greater than 1.11.11.
26+
27+
## Configuring host data path attachments for containers
28+
29+
* For Linux node: We can just attach the same path into container.
30+
* For Windows node: Since Windows containers don't have a D: disk, we need to mount the path. Refer to the listed paths that you can choose to mount.
31+
32+
| Azure Batch Data Path | Path in Host Machine | Path in Container |
33+
|-----------------------------------|--------------------------------------------------------------------------|--------------|
34+
|**AZ_BATCH_APP_PACKAGE_**| D:\\batch\\tasks\\applications | C:\\batch\\tasks\\applications |
35+
|**AZ_BATCH_NODE_SHARED_DIR**| D:\\batch\\tasks\\shared | C:\\batch\\tasks\\shared |
36+
|**AZ_BATCH_NODE_STARTUP_DIR**| D:\\batch\\tasks\\startup | C:\\batch\\tasks\\startup |
37+
|**AZ_BATCH_NODE_MOUNTS_DIR**|D:\\batch\\tasks\\fsmounts|C:\\batch\\tasks\\fsmounts|
38+
|**AZ_BATCH_NODE_STARTUP_WORKING_DIR**| D:\\batch\\tasks\\startup\\wd | C:\\batch\\tasks\\startup\\wd |
39+
|**AZ_BATCH_JOB_PREP_DIR** | C:\\batch\\tasks\\workitems\\{workitemname}\\{jobname}\\{jobpreptaskname} | D:\\batch\tasks\workitems\\{workitemname}\\{jobname}\\{jobpreptaskname} |
40+
|**AZ_BATCH_JOB_PREP_WORKING_DIR** | C:\\batch\\tasks\\workitems\\{workitemname}\\{jobname}\\{jobpreptaskname}\\wd | D:\\batch\tasks\workitems\\{workitemname}\\{jobname}\\{jobpreptaskname}\\wd |
41+
|**AZ_BATCH_TASK_DIR**| D:\\batch\\tasks\\workitems\\{workitemname}\\{jobname}\\{taskname} | C:\batch\tasks\workitems\\{workitemname}\\{jobname}\\{taskname} |
42+
|**AZ_BATCH_TASK_WORKING_DIR** | D:\\batch\\tasks\\workitems\\{workitemname}\\{jobname}\\{taskname}\\wd | C:\\batch\\tasks\\workitems\\{workitemname}\\{jobname}\\{taskname}\\wd |
43+
44+
45+
Refer to the listed data paths that you can choose to attach to the container. Any unselected data paths have their associated environment variables removed.
46+
47+
|Data Path Enum|Data Path with be attached to container|
48+
|:--------:|------------|
49+
|**Shared**| AZ_BATCH_NODE_SHARED_DIR |
50+
|**Applications**| AZ_BATCH_APP_PACKAGE_* |
51+
|**Startup**| AZ_BATCH_NODE_STARTUP_DIR, AZ_BATCH_NODE_STARTUP_WORKING_DIR |
52+
|**Vfsmounts**|AZ_BATCH_NODE_MOUNTS_DIR|
53+
|**JobPrep**| AZ_BATCH_JOB_PREP_DIR, AZ_BATCH_JOB_PREP_WORKING_DIR |
54+
|**Task**| AZ_BATCH_TASK_DIR, AZ_BATCH_TASK_WORKING_DIR |
55+
56+
## Run a container isolation task
57+
58+
> [!Note]
59+
> * If you use an empty list, the NodeAgent will not mount any data paths into the task's container. If you use null, the NodeAgent will mount the entire ephemeral disk (in Windows) or `AZ_BATCH_NODE_ROOT_DIR` (in Linux).
60+
> * If you don't mount the task data path into the container, you must set the task's property [workingDirectory](/rest/api/batchservice/task/add?tabs=HTTP#containerworkingdirectory) to containerImageDefault.
61+
62+
Before running a container isolation task, you must create a pool with a container. For more information on how to create it, see this guide [Docker container workload](batch-docker-container-workloads.md).
63+
64+
# [REST API](#tab/restapi)
65+
66+
The following example describes how to create a container task with data isolation using REST API:
67+
```http
68+
POST {batchUrl}/jobs/{jobId}/tasks?api-version=2024-07-01.20.0
69+
```
70+
71+
```json
72+
{
73+
"id": "taskId",
74+
"commandLine": "bash -c 'echo hello'",
75+
"containerSettings": {
76+
"imageName": "ubuntu",
77+
"containerHostBatchBindMounts": [
78+
{
79+
"source": "Task",
80+
"isReadOnly": true
81+
}
82+
]
83+
},
84+
"userIdentity": {
85+
"autoUser": {
86+
"scope": "task",
87+
"elevationLevel": "nonadmin"
88+
}
89+
}
90+
}
91+
```
92+
93+
# [SDK / C#](#tab/csharp)
94+
95+
The following code snippet shows an example of how to use the [Batch .NET](https://www.nuget.org/packages/Microsoft.Azure.Batch/) client library to create a container data isolation task using C#. For more details about Batch .NET, see the [reference documentation](/dotnet/api/microsoft.azure.batch).
96+
97+
```csharp
98+
private async Task CreateExampleContainerIsolationTask(BatchServiceClient client, string jobId)
99+
{
100+
var containerIsolationTask = new CloudTask("test-container-isolation", "printenv")
101+
{
102+
ContainerSettings = new TaskContainerSettings("docker.io/ubuntu:22.04")
103+
{
104+
ContainerHostBatchBindMounts = new List<ContainerHostBatchBindMountEntry>()
105+
{
106+
new()
107+
{
108+
Source = Microsoft.Azure.Batch.Protocol.Models.ContainerHostDataPath.Task,
109+
}
110+
}
111+
}
112+
};
113+
await client.JobOperations.AddTaskAsync(jobId, containerIsolationTask);
114+
}
115+
```

0 commit comments

Comments
 (0)