Tutorial: Process images by using FFmpeg on a mounted Azure Files share

The mounts.bicep module configures an Azure Files SMB mount on the function app. The mountPath value determines the local path where files appear at runtime. You pass the storage account access key as a parameter, and the platform resolves it at runtime through a Key Vault reference:

@description('Function app name')
param functionAppName string

@description('Storage account name')
param storageAccountName string

@description('Storage account access key or app setting reference for Azure Files SMB mount')
param accessKey string

@description('Array of mount configurations')
param mounts array

// Function app reference
resource functionApp 'Microsoft.Web/sites@2023-12-01' existing = {
  name: functionAppName
}

// Azure Files OS mount configuration
// Deploys azureStorageAccounts site config with all mounts in one shot
resource mountConfig 'Microsoft.Web/sites/config@2023-12-01' = {
  parent: functionApp
  name: 'azurestorageaccounts'
  properties: reduce(mounts, {}, (cur, mount) => union(cur, {
    '${mount.name}': {
      type: 'AzureFiles'
      shareName: mount.shareName
      mountPath: mount.mountPath
      accountName: storageAccountName
      accessKey: accessKey
    }
  }))
}

output mountPaths array = [for mount in mounts: mount.mountPath]

Because Azure Files SMB mounts don't yet support managed identity authentication, you need a storage account key. As a best practice, store this key in Azure Key Vault and use a Key Vault reference in an app setting. The mount configuration references that app setting by using @AppSettingRef(), so the key never appears in your Bicep templates. The keyvault.bicep module creates the vault, stores the key, and grants RBAC roles:

@description('Key Vault name')
param name string

@description('Location')
param location string

@description('Tags')
param tags object = {}

@description('Storage account name')
param storageAccountName string

@description('Principal ID of the function app identity (receives Key Vault Secrets User role)')
param functionAppPrincipalId string

@description('Principal ID of the deploying user (receives Key Vault Secrets Officer role)')
param deployerPrincipalId string = ''

// Storage account reference
resource storage 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: storageAccountName
}

// Key Vault with RBAC authorization
resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: name
  location: location
  tags: tags
  properties: {
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: tenant().tenantId
    enableRbacAuthorization: true
    enabledForTemplateDeployment: true
    enableSoftDelete: true
    softDeleteRetentionInDays: 7
  }
}

// Store storage account key as a secret (Azure Files mounts require shared key)
resource storageKeySecret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  parent: keyVault
  name: 'storageAccountKey'
  properties: {
    value: storage.listKeys().keys[0].value
    contentType: 'Storage account access key for Azure Files SMB mount'
  }
}

// Built-in Key Vault RBAC role IDs
var roles = {
  KeyVaultSecretsOfficer: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b86a8fe4-44ce-4948-aee5-eccb2c155cd7')
  KeyVaultSecretsUser: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
}

// Grant the function app identity read access to secrets
resource functionAppSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(keyVault.id, functionAppPrincipalId, roles.KeyVaultSecretsUser)
  scope: keyVault
  properties: {
    roleDefinitionId: roles.KeyVaultSecretsUser
    principalId: functionAppPrincipalId
    principalType: 'ServicePrincipal'
  }
}

// Grant the deployer manage access to secrets
resource deployerSecretsOfficer 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (!empty(deployerPrincipalId)) {
  name: guid(keyVault.id, deployerPrincipalId, roles.KeyVaultSecretsOfficer)
  scope: keyVault
  properties: {
    roleDefinitionId: roles.KeyVaultSecretsOfficer
    principalId: deployerPrincipalId
    principalType: 'User'
  }
}

output name string = keyVault.name
output uri string = keyVault.properties.vaultUri
output storageKeySecretUri string = storageKeySecret.properties.secretUri

The main.bicep file invokes the mount and Key Vault modules:

// Key Vault for secure storage of Azure Files access key
module keyVault './app/keyvault.bicep' = {
  name: 'keyVault'
  scope: rg
  params: {
    name: !empty(keyVaultName) ? keyVaultName : '${abbrs.keyVaultVaults}${resourceToken}'
    location: location
    tags: tags
    storageAccountName: storage.outputs.name
    functionAppPrincipalId: processorIdentity.outputs.principalId
    deployerPrincipalId: principalId
  }
}

// Azure Files mount configuration (access key resolved via Key Vault reference)
module azureFilesMount './app/mounts.bicep' = {
  name: 'azureFilesMount'
  scope: rg
  params: {
    functionAppName: functionApp.outputs.name
    storageAccountName: storage.outputs.name
    accessKey: '@AppSettingRef(MOUNT_SECRET_REFERENCE)'
    mounts: [
      {
        name: 'tools'
        shareName: 'tools'
        mountPath: '/mounts/tools/'
      }
    ]
  }
  dependsOn: [
    functionAppRoleAssignments
  ]
}

After azd up deploys the infrastructure and code, a post-deployment script downloads the FFmpeg static binary and uploads it to the Azure Files share. It also creates the Event Grid subscription and runs a health check:

# ---------------------------------------------------------------------------
# 2. Download and upload ffmpeg binary to Azure Files
# ---------------------------------------------------------------------------
echo "⬇️  Downloading ffmpeg static build..."
FFMPEG_URL="https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz"
FFMPEG_ARCHIVE="ffmpeg-static.tar.xz"

curl -L -o "$FFMPEG_ARCHIVE" "$FFMPEG_URL"

echo "📦 Extracting ffmpeg binary..."
# GNU tar uses --wildcards; BSD tar (macOS) supports globs natively
if tar --version 2>/dev/null | grep -q 'GNU'; then
    tar --wildcards -xf "$FFMPEG_ARCHIVE" --strip-components=1 "*/ffmpeg"
else
    tar -xf "$FFMPEG_ARCHIVE" --strip-components=1 "*/ffmpeg"
fi

echo "⬆️  Uploading ffmpeg to Azure Files share..."
ACCOUNT_KEY=$(az storage account keys list \
  --resource-group "$RESOURCE_GROUP" \
  --account-name "$STORAGE_ACCOUNT" \
  --query "[0].value" -o tsv)

export AZURE_STORAGE_CONNECTION_TIMEOUT=300
UPLOAD_OK=false
for attempt in 1 2 3 4 5; do
    az storage file upload \
      --account-name "$STORAGE_ACCOUNT" \
      --share-name "$FILE_SHARE" \
      --source ./ffmpeg \
      --account-key "$ACCOUNT_KEY" \
      --timeout 300 && { UPLOAD_OK=true; break; }
    echo "   Upload attempt $attempt failed, retrying in 15 seconds..."

The function reads the mount path from an environment variable (FFMPEG_PATH) set in the Bicep template. It calls process_with_ffmpeg, which runs the binary as a subprocess against the input image bytes:

@app.blob_trigger(
    arg_name="input_blob",
    path="images-input/{name}",
    connection="AzureWebJobsStorage",
    source="EventGrid",
    data_type=func.DataType.BINARY,
)
@app.blob_output(
    arg_name="$return",
    path="images-output/{name}",
    connection="AzureWebJobsStorage",
    data_type=func.DataType.BINARY,
)
def process_image_blob(input_blob: func.InputStream) -> bytes:
    """Process an uploaded image by resizing it with ffmpeg."""
    blob_name = input_blob.name
    logger.info("Processing blob: %s (%d bytes)", blob_name, input_blob.length)

    image_bytes = input_blob.read()
    if not image_bytes:
        logger.warning("Empty blob: %s", blob_name)
        return None

    ffmpeg_path = os.environ.get("FFMPEG_PATH", "/mounts/tools/ffmpeg")
    output_width = int(os.environ.get("OUTPUT_WIDTH", "800"))
    output_format = os.environ.get("OUTPUT_FORMAT", "png")

    result_bytes = process_with_ffmpeg(
        image_bytes,
        ffmpeg_path=ffmpeg_path,
        output_width=output_width,
        output_format=output_format,
    )

    logger.info("Processed %s: %d → %d bytes", blob_name, len(image_bytes), len(result_bytes))
    return result_bytes