|
| 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