Skip to content

Commit f129957

Browse files
GitHubber17GitHubber17
authored
Merge pull request #84657 from laurenhughes/virtual-mount
Mount a virtual file system
2 parents cfc8d7d + a45a352 commit f129957

File tree

4 files changed

+199
-5
lines changed

4 files changed

+199
-5
lines changed

‎articles/batch/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,8 @@
8383
href: batch-custom-images.md
8484
- name: Create a pool in a virtual network
8585
href: batch-virtual-network.md
86+
- name: Mount a virtual file system
87+
href: virtual-file-mount.md
8688
- name: Mount an Azure file share
8789
href: pool-file-shares.md
8890
- name: Use RDMA or GPU instances

‎articles/batch/batch-compute-node-environment-variables.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@ ms.devlang: multiple
1111
ms.topic: article
1212
ms.tgt_pltfrm: vm-windows
1313
ms.workload: big-compute
14-
ms.date: 04/23/2019
14+
ms.date: 08/13/2019
1515
ms.author: lahugh
1616
---
1717

1818
# Azure Batch runtime environment variables
1919

2020
The [Azure Batch service](https://azure.microsoft.com/services/batch/) sets the following environment variables on compute nodes. You can reference these environment variables in task command lines, and in the programs and scripts run by the command lines.
2121

22-
For additional information about using environment variables with Batch, see [Environment settings for tasks](https://docs.microsoft.com/azure/batch/batch-api-basics#environment-settings-for-tasks).
22+
For more information about using environment variables with Batch, see [Environment settings for tasks](https://docs.microsoft.com/azure/batch/batch-api-basics#environment-settings-for-tasks).
2323

2424
## Environment variable visibility
2525

@@ -45,9 +45,9 @@ The command lines executed by tasks on compute nodes do not run under a shell. T
4545
|-----------------------------------|--------------------------------------------------------------------------|--------------|---------|
4646
| AZ_BATCH_ACCOUNT_NAME | The name of the Batch account that the task belongs to. | All tasks. | mybatchaccount |
4747
| AZ_BATCH_ACCOUNT_URL | The URL of the Batch account. | All tasks. | `https://myaccount.westus.batch.azure.com` |
48-
| AZ_BATCH_APP_PACKAGE | A prefix of all the app package environment variables. For example, if Application “Foo” version “1” is installed onto a pool, the environment variable is AZ_BATCH_APP_PACKAGE_FOO_1. AZ_BATCH_APP_PACKAGE_FOO_1 points to the location which the package was downloaded (a folder). | Any task with an associated app package. Also available for all tasks if the node itself has application packages. | AZ_BATCH_APP_PACKAGE_FOO_1 |
48+
| AZ_BATCH_APP_PACKAGE | A prefix of all the app package environment variables. For example, if Application “Foo” version “1” is installed onto a pool, the environment variable is AZ_BATCH_APP_PACKAGE_FOO_1. AZ_BATCH_APP_PACKAGE_FOO_1 points to the location that the package was downloaded (a folder). | Any task with an associated app package. Also available for all tasks if the node itself has application packages. | AZ_BATCH_APP_PACKAGE_FOO_1 |
4949
| AZ_BATCH_AUTHENTICATION_TOKEN | An authentication token that grants access to a limited set of Batch service operations. This environment variable is only present if the [authenticationTokenSettings](/rest/api/batchservice/task/add#authenticationtokensettings) are set when the [task is added](/rest/api/batchservice/task/add#request-body). The token value is used in the Batch APIs as credentials to create a Batch client, such as in the [BatchClient.Open() .NET API](https://docs.microsoft.com/dotnet/api/microsoft.azure.batch.batchclient.open#Microsoft_Azure_Batch_BatchClient_Open_Microsoft_Azure_Batch_Auth_BatchTokenCredentials_). | All tasks. | OAuth2 access token |
50-
| AZ_BATCH_CERTIFICATES_DIR | A directory within the [task working directory][files_dirs] in which certificates are stored for Linux compute nodes. Note that this environment variable does not apply to Windows compute nodes. | All tasks. | /mnt/batch/tasks/workitems/batchjob001/job-1/task001/certs |
50+
| AZ_BATCH_CERTIFICATES_DIR | A directory within the [task working directory][files_dirs] in which certificates are stored for Linux compute nodes. This environment variable does not apply to Windows compute nodes. | All tasks. | /mnt/batch/tasks/workitems/batchjob001/job-1/task001/certs |
5151
| AZ_BATCH_HOST_LIST | The list of nodes that are allocated to a [multi-instance task][multi_instance] in the format `nodeIP,nodeIP`. | Multi-instance primary and subtasks. | `10.0.0.4,10.0.0.5` |
5252
| AZ_BATCH_IS_CURRENT_NODE_MASTER | Specifies whether the current node is the master node for a [multi-instance task][multi_instance]. Possible values are `true` and `false`.| Multi-instance primary and subtasks. | `true` |
5353
| AZ_BATCH_JOB_ID | The ID of the job that the task belongs to. | All tasks except start task. | batchjob001 |
@@ -57,6 +57,7 @@ The command lines executed by tasks on compute nodes do not run under a shell. T
5757
| AZ_BATCH_NODE_ID | The ID of the node that the task is assigned to. | All tasks. | tvm-1219235766_3-20160919t172711z |
5858
| AZ_BATCH_NODE_IS_DEDICATED | If `true`, the current node is a dedicated node. If `false`, it is a [low-priority node](batch-low-pri-vms.md). | All tasks. | `true` |
5959
| AZ_BATCH_NODE_LIST | The list of nodes that are allocated to a [multi-instance task][multi_instance] in the format `nodeIP;nodeIP`. | Multi-instance primary and subtasks. | `10.0.0.4;10.0.0.5` |
60+
| AZ_BATCH_NODE_MOUNTS_DIR | The full path of the node level [file system mount](virtual-file-mount.md) location where all mount directories reside. Windows file shares use a drive letter, so for Windows, the mount drive is part of devices and drives. | All tasks including start task have access to the user, given the user is aware of the mount permissions for the mounted directory. | In Ubuntu, for example, the location is: `/mnt/batch/tasks/fsmounts` |
6061
| AZ_BATCH_NODE_ROOT_DIR | The full path of the root of all [Batch directories][files_dirs] on the node. | All tasks. | C:\user\tasks |
6162
| AZ_BATCH_NODE_SHARED_DIR | The full path of the [shared directory][files_dirs] on the node. All tasks that execute on a node have read/write access to this directory. Tasks that execute on other nodes do not have remote access to this directory (it is not a "shared" network directory). | All tasks. | C:\user\tasks\shared |
6263
| AZ_BATCH_NODE_STARTUP_DIR | The full path of the [start task directory][files_dirs] on the node. | All tasks. | C:\user\tasks\startup |

‎articles/batch/batch-quota-limit.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ ms.workload: big-compute
1313
ms.tgt_pltfrm: na
1414
ms.devlang: na
1515
ms.topic: article
16-
ms.date: 05/28/2019
16+
ms.date: 08/13/2019
1717
ms.author: lahugh
1818
ms.custom: seodec18
1919

@@ -67,6 +67,7 @@ Additional limits set by the Batch service. Unlike [resource quotas](#resource-q
6767
| Application packages per application | 40 |
6868
| Application packages per pool | 10 |
6969
| Maximum task lifetime | 180 days<sup>1</sup> |
70+
| [Mounts](virtual-file-mount.md) per compute node | 10 |
7071

7172
<sup>1</sup> The maximum lifetime of a task, from when it is added to the job to when it completes, is 180 days. Completed tasks persist for seven days; data for tasks not completed within the maximum lifetime is not accessible.
7273

‎articles/batch/virtual-file-mount.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
title: Mount a virtual file system on a pool - Azure Batch | Microsoft Docs
3+
description: Learn how to mount a virtual file system on a Batch pool.
4+
services: batch
5+
documentationcenter: ''
6+
author: laurenhughes
7+
manager: gwallace
8+
9+
ms.service: batch
10+
ms.workload: big-compute
11+
ms.tgt_pltfrm: na
12+
ms.devlang: na
13+
ms.topic: article
14+
ms.date: 08/13/2019
15+
ms.author: lahugh
16+
---
17+
18+
# Mount a virtual file system on a Batch pool
19+
20+
Azure Batch now supports mounting cloud storage or an external file system on Windows or Linux compute nodes in your Batch pools. When a compute node joins a pool, the virtual file system is mounted and treated as a local drive on that node. You can mount file systems such as Azure Files, Azure Blob storage, Network File System (NFS) including an [Avere vFXT cache](../avere-vfxt/avere-vfxt-overview.md), or Common Internet File System (CIFS).
21+
22+
In this article, you'll learn how to mount a virtual file system on a pool of compute nodes using the [Batch Management Library for .NET](https://docs.microsoft.com/dotnet/api/overview/azure/batch?view=azure-dotnet).
23+
24+
> [!NOTE]
25+
> Mounting a virtual file system is supported on Batch pools created on or after 2019-08-19. Batch pools created prior to 2019-08-19 do not support this feature.
26+
>
27+
> The APIs for mounting file systems on a compute node are part of the [Batch .NET](https://docs.microsoft.com/dotnet/api/microsoft.azure.batch?view=azure-dotnet) library.
28+
29+
## Benefits of mounting on a pool
30+
31+
Mounting the file system to the pool, instead of letting tasks retrieve their own data from a large data set, makes it easier and more efficient for tasks to access the necessary data.
32+
33+
Consider a scenario with multiple tasks requiring access to a common set of data, like rendering a movie. Each task renders one or more frames at a time from the scene files. By mounting a drive that contains the scene files, it's easier for compute nodes to access shared data. Additionally, the underlying file system can be chosen and scaled independently based on the performance and scale (throughput and IOPS) required by the number of compute nodes concurrently accessing the data. For example, an [Avere vFXT](../avere-vfxt/avere-vfxt-overview.md) distributed in-memory cache can be used to support large motion picture-scale renders with thousands of concurrent render nodes, accessing source data that resides on-premises. Alternatively, for data that already resides in cloud-based Blob storage, [blobfuse](../storage/blobs/storage-how-to-mount-container-linux.md) can be used to mount this data as a local file system. Blobfuse is only available on Linux nodes, however, [Azure Files](https://azure.microsoft.com/blog/a-new-era-for-azure-files-bigger-faster-better/) provides a similar workflow and is available on both Windows and Linux.
34+
35+
## Mount a virtual file system on a pool
36+
37+
Mounting a virtual file system on a pool makes the file system available to every compute node in the pool. The file system is configured either when a compute node joins a pool, or when the node is restarted or reimaged.
38+
39+
To mount a file system on a pool, create a `MountConfiguration` object. Choose the object that fits your virtual file system: `AzureBlobFileSystemConfiguration`, `AzureFileShareConfiguration`, `NfsMountConfiguration`, or `CifsMountConfiguration`.
40+
41+
All mount configuration objects need the following base parameters. Some mount configurations have parameters specific to the file system being used, which are discussed in more detail in the code examples.
42+
43+
- **Account name or source**: To mount a virtual file share, you need the name of the storage account or its source.
44+
- **Relative mount path or Source**: The location of the file system mounted on the compute node, relative to standard `fsmounts` directory accessible on the node via `AZ_BATCH_NODE_MOUNTS_DIR`. The exact location varies depending on the operating system used on the node. For example, the physical location on an Ubuntu node is mapped to `mnt\batch\tasks\fsmounts`, and on a CentOS node it is mapped to `mnt\resources\batch\tasks\fsmounts`.
45+
- **Mount options or blobfuse options**: These options describe specific parameters for mounting a file system.
46+
47+
Once the `MountConfiguration` object is created, assign the object to the `MountConfigurationList` property when you create the pool. The file system is mounted either when a node joins a pool or when the node is restarted or reimaged.
48+
49+
When the file system is mounted, an environment variable `AZ_BATCH_NODE_MOUNTS_DIR` is created which points to the location of the mounted file systems as well as log files, which are useful for troubleshooting and debugging. Log files are explained in more detail in the [Diagnose mount errors](#diagnose-mount-errors) section.
50+
51+
> [!IMPORTANT]
52+
> The maximum number of mounted file systems on a pool is 10. See [Batch service quotas and limits](batch-quota-limit.md#other-limits) for details and other limits.
53+
54+
## Examples
55+
56+
The following code examples demonstrate mounting a variety of file shares to a pool of compute nodes.
57+
58+
### Azure Files share
59+
60+
Azure Files is the standard Azure cloud file system offering. To learn more about how to get any of the parameters in the mount configuration code sample, see [Use an Azure Files share](../storage/files/storage-how-to-use-files-windows.md).
61+
62+
```csharp
63+
new PoolAddParameter
64+
{
65+
Id = poolId,
66+
MountConfiguration = new[]
67+
{
68+
new MountConfiguration
69+
{
70+
AzureFileShareConfiguration = new AzureFileShareConfiguration
71+
{
72+
AccountName = "AccountName",
73+
AzureFileUrl = "AzureFileShareUrl",
74+
AccountKey = "StorageAccountKey",
75+
RelativeMountPath = "RelativeMountPath",
76+
MountOptions = "-o vers=3.0,dir_mode=0777,file_mode=0777,sec=ntlmssp"
77+
},
78+
}
79+
}
80+
}
81+
```
82+
83+
### Azure Blob file system
84+
85+
Another option is to use Azure Blob storage via [blobfuse](../storage/blobs/storage-how-to-mount-container-linux.md). Mounting a blob file system requires an `AccountKey` or `SasKey` for your storage account. For information on getting these keys, see [View account keys](../storage/common/storage-account-manage.md#view-account-keys-and-connection-string), or [Using shared access signatures (SAS)](../storage/common/storage-dotnet-shared-access-signature-part-1.md). For more information on using blobfuse, see the blobfuse [Troubleshoot FAQ](https://github.com/Azure/azure-storage-fuse/wiki/3.-Troubleshoot-FAQ). To get default access to the blobfuse mounted directory, run the task as an **Administrator**. Blobfuse mounts the directory at the user space, and at pool creation it is mounted as root. In Linux all **Administrator** tasks are root. All options for the FUSE module is described in the [FUSE reference page](http://manpages.ubuntu.com/manpages/xenial/man8/mount.fuse.8.html).
86+
87+
In addition to the troubleshooting guide, GitHub issues in the blobfuse repository are a helpful way to check on current blobfuse issues and resolutions. For more information, see [blobfuse issues](https://github.com/Azure/azure-storage-fuse/issues).
88+
89+
> [!NOTE]
90+
> Blobfuse is not currently supported on Debian. See [Supported SKUs](#supported-skus) for more information.
91+
92+
```csharp
93+
new PoolAddParameter
94+
{
95+
Id = poolId,
96+
MountConfiguration = new[]
97+
{
98+
new MountConfiguration
99+
{
100+
AzureBlobFileSystemConfiguration = new AzureBlobFileSystemConfiguration
101+
{
102+
AccountName = "StorageAccountName",
103+
ContainerName = "containerName",
104+
AccountKey = "StorageAccountKey",
105+
SasKey = "",
106+
RelativeMountPath = "RelativeMountPath",
107+
BlobfuseOptions = "-o attr_timeout=240 -o entry_timeout=240 -o negative_timeout=120 "
108+
},
109+
}
110+
}
111+
}
112+
```
113+
114+
### Network File System
115+
116+
Network File Systems (NFS) can also be mounted to pool nodes allowing traditional file systems to be easily accessed by Azure Batch nodes. This could be a single NFS server deployed in the cloud, or an on-premises NFS server accessed over a virtual network. Alternatively, take advantage of the [Avere vFXT](../avere-vfxt/avere-vfxt-overview.md) distributed in-memory cache solution, which provides seamless connectivity to on-premises storage, reading data on-demand into its cache, and delivers high performance and scale to cloud-based compute nodes.
117+
118+
```csharp
119+
new PoolAddParameter
120+
{
121+
Id = poolId,
122+
MountConfiguration = new[]
123+
{
124+
new MountConfiguration
125+
{
126+
NfsMountConfiguration = new NFSMountConfiguration
127+
{
128+
Source = "source",
129+
RelativeMountPath = "RelativeMountPath",
130+
MountOptions = "options ver=1.0"
131+
},
132+
}
133+
}
134+
}
135+
```
136+
137+
### Common Internet File System
138+
139+
Common Internet File Systems (CIFS) can also be mounted to pool nodes allowing traditional file systems to be easily accessed by Azure Batch nodes. CIFS is a file-sharing protocol that provides an open and cross-platform mechanism for requesting network server files and services. CIFS is based on the enhanced version of Microsoft's Server Message Block (SMB) protocol for internet and intranet file sharing and is used to mount external file systems on Windows nodes. To learn more about SMB, see [File Server and SMB](https://docs.microsoft.com/windows-server/storage/file-server/file-server-smb-overview).
140+
141+
```csharp
142+
new PoolAddParameter
143+
{
144+
Id = poolId,
145+
MountConfiguration = new[]
146+
{
147+
new MountConfiguration
148+
{
149+
CifsMountConfiguration = new CIFSMountConfiguration
150+
{
151+
Username = "StorageAccountName",
152+
RelativeMountPath = "cifsmountpoint",
153+
Source = "source",
154+
Password = "StorageAccountKey",
155+
MountOptions = "-o vers=3.0,dir_mode=0777,file_mode=0777,serverino"
156+
},
157+
}
158+
}
159+
}
160+
```
161+
162+
## Diagnose mount errors
163+
164+
If a mount configuration fails, the compute node in the pool will fail and the node state becomes unusable. To diagnose a mount configuration failure, inspect the [`ComputeNodeError`](https://docs.microsoft.com/rest/api/batchservice/computenode/get#computenodeerror) property for details on the error.
165+
166+
To get the log files for debugging, use [OutputFiles](batch-task-output-files.md) to upload the `*.log` files. The `*.log` files contain information about the file system mount at the `AZ_BATCH_NODE_MOUNTS_DIR` location. Mount log files have the format: `<type>-<mountDirOrDrive>.log` for each mount. For example, a `cifs` mount at a mount directory named `test` will have a mount log file named: `cifs-test.log`.
167+
168+
## Supported SKUs
169+
170+
| Publisher | Offer | SKU | Azure Files Share | Blobfuse | NFS mount | CIFS mount |
171+
|---|---|---|---|---|---|---|
172+
| batch | rendering-centos73 | rendering | :heavy_check_mark: <br>Note: Compatible with CentOS 7.7</br>| :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
173+
| Canonical | UbuntuServer | 16.04-LTS, 18.04-LTS | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
174+
| Credativ | Debian | 8, 9 | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: |
175+
| microsoft-ads | linux-data-science-vm | linuxdsvm | :heavy_check_mark: <br>Note: Compatible with CentOS 7.4. </br> | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
176+
| microsoft-azure-batch | centos-container | 7.6 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
177+
| microsoft-azure-batch | centos-container-rdma | 7.4 | :heavy_check_mark: <br>Note: Supports A_8 or 9 storage</br> | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
178+
| microsoft-azure-batch | ubuntu-server-container | 16.04-LTS | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
179+
| microsoft-dsvm | linux-data-science-vm-ubuntu | linuxdsvmubuntu | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
180+
| OpenLogic | CentOS | 7.6 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
181+
| OpenLogic | CentOS-HPC | 7.4, 7.3, 7.1 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
182+
| Oracle | Oracle-Linux | 7.6 | :x: | :x: | :x: | :x: |
183+
| Windows | WindowsServer | 2012, 2016, 2019 | :heavy_check_mark: | :x: | :x: | :x: |
184+
185+
## Next steps
186+
187+
- Learn more details about mounting an Azure Files share with [Windows](../storage/files/storage-how-to-use-files-windows.md) or [Linux](../storage/files/storage-how-to-use-files-linux.md).
188+
- Learn about using and mounting [blobfuse](https://github.com/Azure/azure-storage-fuse) virtual file systems.
189+
- See [Network File System overview](https://docs.microsoft.com/windows-server/storage/nfs/nfs-overview) to learn about NFS and its applications.
190+
- See [Microsoft SMB protocol and CIFS protocol overview](https://docs.microsoft.com/windows/desktop/fileio/microsoft-smb-protocol-and-cifs-protocol-overview) to learn more about CIFS.

0 commit comments

Comments
 (0)