Merge pull request #299167 from hhunter-ms/durable_mssql_for_aca

Durable Functions + MSSQL for ACA quickstart

Author: JillGrant615

articles/azure-functions/durable/TOC.yml

@@ -62,6 +62,8 @@
     href: durable-functions-phone-verification.md
   - name: Publish to Event Grid
     href: durable-functions-event-publishing.md
+  - name: Hosting in Azure Container Apps 
+    href: durable-functions-mssql-container-apps-hosting.md
 - name: Samples
   items:
   - name: Code samples

articles/azure-functions/durable/durable-functions-azure-storage-provider.md

@@ -237,6 +237,7 @@ You can enable extended sessions by setting `durableTask/extendedSessionsEnabled
   }
 }
 ```
+---
 
 There are two potential downsides of this setting to be aware of:
 
@@ -288,8 +289,6 @@ If you are not seeing the throughput numbers you expect and your CPU and memory
 ### Flex Consumption Plan 
 The [Flex Consumption plan](../flex-consumption-plan.md) is an Azure Functions hosting plan that provides many of the benefits of the Consumption plan, including a serverless billing model, while also adding useful features, such as private networking, instance memory size selection, and full support for managed identity authentication.
 
-Azure Storage is currently the only supported [storage provider](durable-functions-storage-providers.md) for Durable Functions when hosted in the Flex Consumption plan.
-
 You should follow these performance recommendations when hosting Durable Functions in the Flex Consumption plan:
 
 * Set the [always ready instance count](../flex-consumption-how-to.md#set-always-ready-instance-counts) for the `durable` group to `1`. This ensures that there is always one instance ready to handle Durable Functions related requests, thus reducing the application's cold start. 

articles/azure-functions/durable/durable-functions-mssql-container-apps-hosting.md

@@ -0,0 +1,295 @@
+---
+title: "Host a Durable Functions app in Azure Container Apps"
+description: Learn how to host a Durable Functions app using the MSSQL backend in Azure Container Apps.
+ms.topic: how-to
+ms.date: 05/06/2025
+---
+
+# Host a Durable Functions app in Azure Container Apps (.NET isolated)
+
+This article shows how to host a Durable Functions app in Azure Container Apps. While Durable Functions supports several [storage providers](./durable-functions-storage-providers.md) or *backends*, autoscaling of the app is only available when using the Microsoft SQL (MSSQL) backend. If another backends is used, you need to [manually set up scaling](../functions-container-apps-hosting.md#event-driven-scaling) today.
+
+## Prerequisites 
+
++ [Visual Studio Code](https://code.visualstudio.com/download) installed.
+
++ [.NET 8.0 SDK](https://dotnet.microsoft.com/download).
+
++ [Docker](https://docs.docker.com/install/) and [Docker ID](https://hub.docker.com/signup)
+
++ [Azure CLI](/cli/azure/install-azure-cli) [version 2.47](/cli/azure/release-notes-azure-cli#april-21-2020) or later.
+
++ [Azure Functions Core Tools](../functions-run-local.md)
+
++ Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?ref=microsoft.com&utm_source=microsoft.com&utm_medium=docs&utm_campaign=visualstudio).
+
++ An HTTP test tool that keeps your data secure. For more information, see [HTTP test tools](../functions-develop-local.md#http-test-tools).
+
+## Create a local Durable Functions project
+
+In Visual Studio Code, [create a .NET isolated Durable Functions project](./quickstart-mssql.md) configured to use the MSSQL backend. Follow the article until the [Test locally](./quickstart-mssql.md#test-locally) section and make sure you can run the app locally before going to the next step. 
+
+### Add Docker related files
+
+1. In the project root directory, add a _Dockerfile_ with the following content:
+    ```
+    FROM mcr.microsoft.com/dotnet/sdk:8.0 AS installer-env
+
+    COPY . /src/dotnet-function-app
+    RUN cd /src/dotnet-function-app && \
+    mkdir -p /home/site/wwwroot && \
+    dotnet publish *.csproj --output /home/site/wwwroot
+
+    # To enable ssh & remote debugging on app service change the base image to the one below
+    # FROM mcr.microsoft.com/azure-functions/dotnet-isolated:4-dotnet-isolated8.0-appservice
+    FROM mcr.microsoft.com/azure-functions/dotnet-isolated:4-dotnet-isolated8.0
+    ENV AzureWebJobsScriptRoot=/home/site/wwwroot \
+        AzureFunctionsJobHost__Logging__Console__IsEnabled=true
+
+    COPY --from=installer-env ["/home/site/wwwroot", "/home/site/wwwroot"]
+    ```
+1. Add a _.dockerignore_ file with the following content:
+    ```
+    local.settings.json
+    ```
+
+## Build the container image 
+
+The Dockerfile in the project root describes the minimum required environment to run the function app in a container. The complete list of supported base images for Azure Functions is documented above as Host images in the pre-requisites section or can be found in the [Azure Functions Base by Microsoft | Docker Hub](https://hub.docker.com/_/microsoft-azure-functions-base)
+
+1. Start the Docker daemon. 
+
+1. Sign in to Docker with the [docker login](https://docs.docker.com/engine/reference/commandline/login/) command. This command prompts you for your username and password. A "Login Succeeded" message confirms that you're signed in.
+
+1. In the **LocalFunctionProj** project folder, run the following command to build the image, replacing <DOCKER_ID> with your Docker Hub account ID:
+    ```bash
+    dockerId=<DOCKER_ID>
+    imageName=IMAGE_NAME>
+    imageVersion=v1.0.0
+
+    docker build --platform linux --tag $dockerId/$imageName:$imageVersion .
+    ```
+
+    >[!NOTE]
+    > If you're running on an M-series Mac, use `--platform linux/amd64` instead.
+
+1. Push the image to Docker:
+    ```bash
+    docker push $dockerId/$imageName:$imageVersion
+    ```
+Depending on network speed, pushing the image the first time might take a few minutes (pushing subsequent changes is much faster). While you're waiting, proceed to the next section to create Azure resources in another terminal.
+
+## Create Azure resources
+
+The following instructions will guide you through creating these Azure resources:
+- Azure resource group: For convenient cleanup later, all resources are created in this group. 
+- Azure Container App environment: Environment where container app is hosted. 
+- Azure Container App: Image containing the Durable Functions app is deployed to this app. 
+- Azure Storage Account: Required by the function app to store app related data such as application code. 
+- A virtual network: Required by the Azure Container App environment. 
+
+### Initial set up
+
+1. Login to your Azure subscription:
+    ```azurecli
+    az login  
+
+    az account set -subscription | -s <subscription_name>
+    ```
+
+1. Run the required commands to set up the Azure Container Apps CLI extension:
+    ```azurecli
+    az upgrade
+
+    az extension add --name containerapp --upgrade
+
+    az provider register --namespace Microsoft.App
+
+    az provider register --namespace Microsoft.OperationalInsights
+    ```
+
+### Create container app and related resources
+
+A workload profile determines the amount of compute and memory resources available to the container apps deployed in an environment. Create a Consumption workload profile for scale-to-zero support and pay-per-use. Learn more about [workload profiles](../functions-container-apps-hosting.md#hosting-and-workload-profiles). 
+
+```azurecli
+location=<REGION>
+resourceGroup=<RESOURCE_GROUP_NAME>
+storage=<STORAGE_NAME>
+containerAppEnv=<CONTAINER_APP_ENVIRONMNET_NAME>
+functionApp=<APP_NAME>
+vnet=<VNET_NAME>
+
+# Create an Azure resource group
+az group create --name $resourceGroup --location $location
+
+# A VNET is required when creating a container app environment
+az network vnet create --resource-group $resourceGroup --name $vnet --location $location --address-prefix 10.0.0.0/16
+
+# The VNET must have a subnet for the environment deployment
+az network vnet subnet create \
+  --resource-group $resourceGroup \
+  --vnet-name $vnet \
+  --name infrastructure-subnet \
+  --address-prefixes 10.0.0.0/23
+
+# Get subnet ID
+subnetId=$(az network vnet subnet show --resource-group $resourceGroup --vnet-name $vnet --name infrastructure-subnet --query "id" -o tsv | tr -d '[:space:]')
+
+# Delegate the subnet to `Microsoft.App/environments`
+az network vnet subnet update --resource-group $resourceGroup --vnet-name $vnet --name infrastructure-subnet --delegations Microsoft.App/environments
+
+# Create the container app environment
+az containerapp env create \
+  --enable-workload-profiles \
+  --resource-group $resourceGroup \
+  --name $containerAppEnv \
+  --location $location \
+  --infrastructure-subnet-resource-id $subnetId
+
+# Create a container app based on the Durable Functions image
+az containerapp create --resource-group $resourceGroup \
+--name $functionApp \
+--environment $containerAppEnv \
+--image $dockerId/$imageName:$imageVersion \
+--ingress external \
+--allow-insecure \
+--target-port 80 \
+--transport auto \
+--kind functionapp \
+--query properties.outputs.fqdn
+```
+
+Note down the app link, which should look similar to:
+```
+https://<APP_NAME>.victoriouswave-3866c33e.<REGION>.azurecontainerapps.io/
+```
+
+### Create databases
+
+Create an Azure Storage account as required by the function app:
+
+```azurecli
+az storage account create --name $storage --location $location --resource-group $resourceGroup --sku Standard_LRS
+```
+
+Your Durable Functions also needs an Azure SQL Database as its storage backend. This is where state information is persisted as your orchestrations run. In the Azure portal, you can [create an Azure SQL database](/azure/azure-sql/database/single-database-create-quickstart). During creation:
+- Enable Azure services and resources to access this server (under _Networking_)
+- Set the value for _Database collation_ (under _Additional settings_) to `Latin1_General_100_BIN2_UTF8`.
+
+> [!NOTE] 
+> Enabling the **Allow Azure services and resources to access this server** setting isn't a recommended security practice for production scenarios. Real applications should implement more secure approaches, such as stronger firewall restrictions or virtual network configurations.
+
+
+### Configure identity-based authentication
+
+Managed identities make your app more secure by eliminating secrets from your app, such as credentials in the connection strings. You can choose between [system-assigned and user-assigned managed identity](/entra/identity/managed-identities-azure-resources/overview). This article demonstrates setting up user-assigned managed identity, which is the recommended option as it is not tied to the app lifecycle.
+
+1. Create identity and assign it to the container app:
+    ```azurecli
+    # Variables
+    subscription=<SUBSCRIPTION_ID>
+    identity=<IDENTITY_NAME>
+
+    # Create a managed identity resource
+    echo "Creating $identity"
+    az identity create -g $resourceGroup -n $identity --location "$location"
+
+    # Assign the identity to the container app
+    echo "Assigning $identity to app"
+    az containerapp identity assign --resource-group $resourceGroup --name $functionApp --user-assigned $identity
+    ```
+
+1. Assign the identity `Storage Blob Data Owner` role for access to the storage account. 
+    ```
+    # Set the scope of the access
+    scope="/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.Storage/storageAccounts/$storage"
+    
+    # Get the identity's ClientId 
+    clientId=$(az identity show --name $identity --resource-group $resourceGroup --query 'clientId' --output tsv)
+    
+    # Assign the role
+    echo "Assign Storage Blob Data Owner role to identity"
+    az role assignment create --assignee "$clientId" --role "Storage Blob Data Owner" --scope "$scope"
+    ```
+
+> [!NOTE]
+> Authenticating to the MSSQL database using managed identity isn't supported when hosting a Durable Functions app in Azure Container Apps. Use connection string for now.
+
+### Set up app settings
+
+1. Find the connection string by going to the SQL database resource on Azure portal, navigating to the **Settings** tab, then clicking on **Connection strings**:
+    :::image type="content" source="./media/quickstart-mssql/mssql-azure-db-connection-string.png" alt-text="Screenshot showing database connection string.":::
+
+    The connection string should have this format: 
+    ```bash
+    dbserver=<SQL_SERVER_NAME>
+    sqlDB=<SQL_DB_NAME>
+    username=<DB_USER_LOGIN>
+    password=<DB_USER_PASSWORD>
+
+    connStr="Server=tcp:$dbserver.database.windows.net,1433;Initial Catalog=$sqlDB;Persist Security Info=False;User ID=$username;Password=$password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
+    ```
+
+    If you forget the password from the previous database creation step, you can reset it on the SQL server resource:
+    :::image type="content" source="./media/quickstart-mssql/mssql-azure-reset-pass-2.png" alt-text="Screenshot showing reset password button.":::
+
+1. Store the SQL database's connection string as a [secret](../../container-apps/manage-secrets.md) called _sqldbconnection_ in the container app:
+    ```azurecli
+    az containerapp create \
+    --resource-group $resourceGroup \
+    --name $functionApp \
+    --environment $containerAppEnv \
+    --image $dockerId/$imageName:$imageVersion \
+    --secrets sqldbconnection=$connStr
+    ```
+
+1. Add these settings to the app:
+    - `AzureWebJobsStorage__accountName`: Azure Storage account name
+    - `AzureWebJobsStorage__clientId`: ClientId of the managed identity
+    - `AzureWebJobsStorage__credential`: Credential type, which is _managedidentity_
+    - `SQLDB_Connection`: Reference the SQL database connection string stored as a secret
+    - `FUNCTIONS_WORKER_RUNTIME`: Programming language of the app
+
+    ```azurecli
+    az containerapp update \
+    -n $functionApp \
+    -g $resourceGroup \
+    --set-env-vars SQLDB_Connection=secretref:sqldbconnection \
+    AzureWebJobsStorage__accountName=$storage \
+    AzureWebJobsStorage__clientId=$clientId \
+    AzureWebJobsStorage__credential=managedidentity \
+    FUNCTIONS_WORKER_RUNTIME=dotnet-isolated
+    ```
+
+## Test
+
+1. Use an HTTP test tool to send a POST request to the HTTP trigger endpoint, which should be similar to: 
+    ```
+    https://<APP NAME>.victoriouswave-3866c33e.<REGION>.azurecontainerapps.io/api/DurableFunctionsOrchestrationCSharp1_HttpStart
+    ```
+
+   The response is the HTTP function's initial result. It lets you know that the Durable Functions orchestration started successfully. It doesn't yet display the end result of the orchestration. The response includes a few useful URLs.
+
+1. Copy the URL value for `statusQueryGetUri`, paste it in your browser's address bar, and execute the request. Alternatively, you can also continue to use the HTTP test tool to issue the GET request.
+    The request queries the orchestration instance for the status. You should see that the instance finished and that it includes the outputs or results of the Durable Functions app like in this example:
+
+    ```json
+    {
+        "name":"HelloCities",
+        "instanceId":"7f99f9474a6641438e5c7169b7ecb3f2",
+        "runtimeStatus":"Completed",
+        "input":null,
+        "customStatus":null,
+        "output":"Hello, Tokyo! Hello, London! Hello, Seattle!",
+        "createdTime":"2023-01-31T18:48:49Z",
+        "lastUpdatedTime":"2023-01-31T18:48:56Z"
+    }
+    ```
+
+## Next steps
+
+Learn more about:
+- [Azure Container Apps hosting of Azure Functions](../functions-container-apps-hosting.md). 
+- [MSSQL storage provider](https://microsoft.github.io/durabletask-mssql/) architecture, configuration, and workload behavior. 
+- The Azure-managed storage backend, [Durable Task Scheduler](./durable-task-scheduler/durable-task-scheduler.md).

articles/azure-functions/durable/durable-functions-storage-providers.md

@@ -54,7 +54,7 @@ The source code for the DTFx components of the Azure Storage storage provider ca
 
 ## <a name="netherite"></a>Netherite 
 > [!NOTE]
-> Support for using the Netherite storage backend with Durable Functions will end 31 March 2028. It is recommended that you start evaluating the Durable Task Scheduler for workloads that you're currently using Netherite for. See [end-ofsupport announcement](https://azure.microsoft.com/updates/?id=489009). 
+> Support for using the Netherite storage backend with Durable Functions will end 31 March 2028. It is recommended that you start evaluating the Durable Task Scheduler for workloads that you're currently using Netherite for. See [end-of-support announcement](https://azure.microsoft.com/updates/?id=489009). 
 
 The Netherite storage backend was designed and developed by [Microsoft Research](https://www.microsoft.com/research). It uses [Azure Event Hubs](../../event-hubs/event-hubs-about.md) and the [FASTER](https://www.microsoft.com/research/project/faster/) database technology on top of [Azure Page Blobs](../../storage/blobs/storage-blob-pageblob-overview.md). The design of Netherite enables higher-throughput processing of orchestrations and entities compared to other providers. In some benchmark scenarios, throughput was shown to increase by more than an order of magnitude when compared to the default Azure Storage provider.
 
@@ -128,7 +128,6 @@ If no storage provider is explicitly configured in host.json, the Azure Storage
 See the [durable task scheduler getting started documentation](./durable-task-scheduler/quickstart-durable-task-scheduler.md).
 
 ### Configuring the MSSQL storage provider
-
 Enabling the MSSQL storage provider requires a configuration change in your `host.json`. For C# users, it also requires an additional installation step.
 
 #### `host.json` Configuration
@@ -149,25 +148,21 @@ The following example shows the minimum configuration required to enable the MSS
 }
 ```
 
-For more detailed setup instructions, see the [MSSQL provider's getting started documentation](https://microsoft.github.io/durabletask-mssql/#/quickstart).
+For more detailed setup instructions, see the [MSSQL provider's getting started documentation](./quickstart-mssql.md) and [documentation on github.io](https://microsoft.github.io/durabletask-mssql/#/quickstart).
 
 #### Install the Durable Task MSSQL extension (.NET only)
 
 > [!NOTE]
 > If your app uses [Extension Bundles](../functions-bindings-register.md#extension-bundles), you should ignore this section as Extension Bundles removes the need for manual Extension management.
 
-You'll need to install the latest version of the MSSQL storage provider Extension on NuGet. This usually means including a reference to it in your `.csproj` file and building the project.
-
-The Extension package to install depends on the .NET worker you are using:
-- For the _in-process_ .NET worker, install [`Microsoft.DurableTask.SqlServer.AzureFunctions`](https://www.nuget.org/packages/Microsoft.DurableTask.SqlServer.AzureFunctions).
-- For the _isolated_ .NET worker, install [`Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer`](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer).
+You'll need to install the latest version of the MSSQL storage provider Extension on NuGet: [`Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer`](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer). This usually means including a reference to it in your `.csproj` file and building the project.
 
 ## Comparing storage providers
 
 There are many significant tradeoffs between the various supported storage providers. The following table can be used to help you understand these tradeoffs and decide which storage provider is best for your needs.
 
 > [!NOTE]
-> Support for using the Netherite storage backend with Durable Functions will end 31 March 2028. It is recommended that you start evaluating the Durable Task Scheduler for workloads that you're currently using Netherite for. See [end-ofsupport announcement](https://azure.microsoft.com/updates/?id=489009). 
+> Support for using the Netherite storage backend with Durable Functions will end 31 March 2028. It is recommended that you start evaluating the Durable Task Scheduler for workloads that you're currently using Netherite for. See [end-of-support announcement](https://azure.microsoft.com/updates/?id=489009). 
 
 | Storage provider | Azure Storage | Netherite | MSSQL | DTS| 
 |- |-              |-          |-      |- |