Service Fabric Azure Files Volume Driver (Preview)

The Azure Files volume plugin is a Docker volume plugin that provides Azure Files based volumes for Docker containers. This Docker volume plugin is packaged as a Service Fabric application that can be deployed to Service Fabric clusters. It's purpose is to provide Azure Files based volumes for other Service Fabric container applications that are deployed to the cluster.

Note

Version 6.255.389.9494 of the Azure Files volume plugin is a preview release that is available with this document. As a preview release, it is not supported for use in production environments.

Prerequisites

Deploy the Service Fabric Azure Files application

The Service Fabric application that provides the volumes for your containers can be downloaded from the following link. The application can be deployed to the cluster via PowerShell, CLI or FabricClient APIs.

  1. Using the command line, change directory to the root directory of the application package downloaded.

    cd .\AzureFilesVolume\
    
    cd ~/AzureFilesVolume
    
  2. Copy the application package to the image store Run the command below with the appropriate value for [ApplicationPackagePath] and [ImageStoreConnectionString]:

    Copy-ServiceFabricApplicationPackage -ApplicationPackagePath [ApplicationPackagePath] -ImageStoreConnectionString [ImageStoreConnectionString] -ApplicationPackagePathInImageStore AzureFilesVolumePlugin
    
    sfctl cluster select --endpoint https://testcluster.westus.cloudapp.azure.com:19080 --pem test.pem --no-verify
    sfctl application upload --path [ApplicationPackagePath] --show-progress
    
  3. Register the application type

    Register-ServiceFabricApplicationType -ApplicationPathInImageStore AzureFilesVolumePlugin
    
    sfctl application provision --application-type-build-path [ApplicationPackagePath]
    
  4. Create the application In the command to create the application below, note the ListenPort application parameter. This value specified for this application parameter is the port on which the Azure Files volume plugin listens for requests from the Docker daemon. It is important to ensure that the port provided to the application does not conflict with any other port that the cluster or your applications use.

    New-ServiceFabricApplication -ApplicationName fabric:/AzureFilesVolumePluginApp -ApplicationTypeName AzureFilesVolumePluginType -ApplicationTypeVersion 6.255.389.9494 -ApplicationParameter @{ListenPort='19100'}
    
    sfctl application create --app-name fabric:/AzureFilesVolumePluginApp --app-type AzureFilesVolumePluginType --app-version 6.255.389.9494 --parameter '{"ListenPort":"19100"}'
    

Note

Windows Server 2016 Datacenter does not support mapping SMB mounts to containers (That is only supported on Windows Server version 1709). This constraint prevents network volume mapping and Azure Files volume drivers on versions older than 1709.

Deploy the application on a local development cluster

The default service instance count for the Azure Files volume plugin application is -1, which means that there is an instance of the service deployed to each node in the cluster. However, when deploying the Azure Files volume plugin application on a local development cluster, the service instance count should be specified as 1. This can be done via the InstanceCount application parameter. Therefore, the command for deploying the Azure Files volume plugin application on a local development cluster is:

New-ServiceFabricApplication -ApplicationName fabric:/AzureFilesVolumePluginApp -ApplicationTypeName AzureFilesVolumePluginType -ApplicationTypeVersion 6.255.389.9494 -ApplicationParameter @{ListenPort='19100';InstanceCount='1'}
sfctl application create --app-name fabric:/AzureFilesVolumePluginApp --app-type AzureFilesVolumePluginType --app-version 6.255.389.9494 --parameter '{"ListenPort": "19100","InstanceCount": "1"}'

Configure your applications to use the volume

The following snippet shows how an Azure Files based volume can be specified in the application manifest of your application. The specific element of interest is the Volume tag:

?xml version="1.0" encoding="UTF-8"?>
<ApplicationManifest ApplicationTypeName="WinNodeJsApp" ApplicationTypeVersion="1.0" xmlns="http://schemas.microsoft.com/2011/01/fabric" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Description>Calculator Application</Description>
    <Parameters>
      <Parameter Name="ServiceInstanceCount" DefaultValue="3"></Parameter>
      <Parameter Name="MyCpuShares" DefaultValue="3"></Parameter>
      <Parameter Name="MyStorageVar" DefaultValue="c:\tmp"></Parameter>
    </Parameters>
    <ServiceManifestImport>
        <ServiceManifestRef ServiceManifestName="NodeServicePackage" ServiceManifestVersion="1.0"/>
     <Policies>
       <ContainerHostPolicies CodePackageRef="NodeService.Code" Isolation="hyperv">
            <PortBinding ContainerPort="8905" EndpointRef="Endpoint1"/>
            <RepositoryCredentials PasswordEncrypted="false" Password="****" AccountName="test"/>
            <Volume Source="azfiles" Destination="c:\VolumeTest\Data" Driver="sfazurefile">
                <DriverOption Name="shareName" Value="" />
                <DriverOption Name="storageAccountName" Value="" />
                <DriverOption Name="storageAccountKey" Value="" />
            </Volume>
       </ContainerHostPolicies>
   </Policies>
    </ServiceManifestImport>
    <ServiceTemplates>
        <StatelessService ServiceTypeName="StatelessNodeService" InstanceCount="5">
            <SingletonPartition></SingletonPartition>
        </StatelessService>
    </ServiceTemplates>
</ApplicationManifest>

The driver name for the Azure Files volume plugin is sfazurefile. This value is set for the Driver attribute of the Volume element in the application manifest.

In the Volume element in the snippet above, the Azure Files volume plugin requires the following tags:

  • Source - This is the name of the volume. The user can pick any name for their volume.
  • Destination - This tag is the location that the volume is mapped to within the running container. Thus, your destination can't be a location that already exists within your container

As shown in the DriverOption elements in the snippet above, the Azure Files volume plugin supports the following driver options:

  • shareName - Name of the Azure Files file share that provides the volume for the container
  • storageAccountName - Name of the Azure storage account that contains the Azure Files file share
  • storageAccountKey - Access key for the Azure storage account that contains the Azure Files file share

All of the above driver options are required.

Using your own volume or logging driver

Service Fabric also allows the usage of your own custom volume or logging drivers. If the Docker volume/logging driver is not installed on the cluster, you can install it manually by using the RDP/SSH protocols. You can perform the install with these protocols through a virtual machine scale set start-up script or an SetupEntryPoint script.

An example of the script to install the Docker volume driver for Azure is as follows:

docker plugin install --alias azure --grant-all-permissions docker4x/cloudstor:17.09.0-ce-azure1  \
    CLOUD_PLATFORM=AZURE \
    AZURE_STORAGE_ACCOUNT="[MY-STORAGE-ACCOUNT-NAME]" \
    AZURE_STORAGE_ACCOUNT_KEY="[MY-STORAGE-ACCOUNT-KEY]" \
    DEBUG=1

In your applications, to use the volume or logging driver you installed, you would have to specify the appropriate values in the Volume and LogConfig elements under ContainerHostPolicies in your application manifest.

<ContainerHostPolicies CodePackageRef="NodeService.Code" Isolation="hyperv">
    <PortBinding ContainerPort="8905" EndpointRef="Endpoint1"/>
    <RepositoryCredentials PasswordEncrypted="false" Password="****" AccountName="test"/>
    <LogConfig Driver="[YOUR_LOG_DRIVER]" >
        <DriverOption Name="test" Value="vale"/>
    </LogConfig>
    <Volume Source="c:\workspace" Destination="c:\testmountlocation1" IsReadOnly="false"></Volume>
    <Volume Source="[MyStorageVar]" Destination="c:\testmountlocation2" IsReadOnly="true"> </Volume>
    <Volume Source="myvolume1" Destination="c:\testmountlocation2" Driver="[YOUR_VOLUME_DRIVER]" IsReadOnly="true">
        <DriverOption Name="[name]" Value="[value]"/>
    </Volume>
</ContainerHostPolicies>

When specifying a volume plug-in, Service Fabric automatically creates the volume by using the specified parameters. The Source tag for the Volume element is the name of the volume and the Driver tag specifies the volume driver plug-in. The Destination tag is the location that the Source is mapped to within the running container. Thus, your destination can't be a location that already exists within your container. Options can be specified by using the DriverOption tag as follows:

<Volume Source="myvolume1" Destination="c:\testmountlocation4" Driver="azure" IsReadOnly="true">
           <DriverOption Name="share" Value="models"/>
</Volume>

Application parameters are supported for volumes as shown in the preceding manifest snippet (look for MyStorageVar for an example use).

If a Docker log driver is specified, you have to deploy agents (or containers) to handle the logs in the cluster. The DriverOption tag can be used to specify options for the log driver.

Next steps