Skip to content

functions-migrate-v4.md

Latest commit

 

History

History
191 lines (116 loc) · 10.2 KB

functions-migrate-v4.md

File metadata and controls

191 lines (116 loc) · 10.2 KB
author ggailey777
ms.service azure-functions
ms.custom devx-track-azurecli, linux-related-content
ms.topic include
ms.date 11/03/2022
ms.author glenga

Update your function app in Azure

You need to update the runtime of the function app host in Azure to version 4.x before you publish your migrated project. The runtime version used by the Functions host is controlled by the FUNCTIONS_EXTENSION_VERSION application setting, but in some cases other settings must also be updated. Both code changes and changes to application settings require your function app to restart.

The easiest way is to update without slots and then republish your app project. You can also minimize the downtime in your app and simplify rollback by updating using slots.

Update without slots

The simplest way to update to v4.x is to set the FUNCTIONS_EXTENSION_VERSION application setting to ~4 on your function app in Azure. You must follow a different procedure on a site with slots.

Azure CLI

az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

Azure PowerShell

Update-AzFunctionAppSetting -AppSetting @{"FUNCTIONS_EXTENSION_VERSION" = "~4"} -Name <APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -Force

You must also set another setting, which differs between Windows and Linux.

Windows

When running on Windows, you also need to enable .NET 8.0, which is required by version 4.x of the runtime.

az functionapp config set --net-framework-version v8.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

.NET 6 is required for function apps in any language running on Windows.

Windows

When running on Windows, you also need to enable .NET 8.0, which is required by version 4.x of the runtime.

Set-AzWebApp -NetFrameworkVersion v8.0 -Name <APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME>

.NET 6 is required for function apps in any language running on Windows.

Linux

[!INCLUDE functions-migrate-v4-linuxfxversion]

Linux

When running .NET apps on Linux, you also need to update the linuxFxVersion site setting. Unfortunately, Azure PowerShell can't be used to set the linuxFxVersion at this time. Use the Azure CLI instead.

In this example, replace <APP_NAME> with the name of your function app and <RESOURCE_GROUP_NAME> with the name of the resource group.

You can now republish your app project that has been migrated to run on version 4.x.

Update using slots

Using deployment slots is a good way to update your function app to the v4.x runtime from a previous version. By using a staging slot, you can run your app on the new runtime version in the staging slot and switch to production after verification. Slots also provide a way to minimize downtime during the update. If you need to minimize downtime, follow the steps in Minimum downtime update.

After you've verified your app in the updated slot, you can swap the app and new version settings into production. This swap requires setting WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 in the production slot. How you add this setting affects the amount of downtime required for the update.

Standard update

If your slot-enabled function app can handle the downtime of a full restart, you can update the WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS setting directly in the production slot. Because changing this setting directly in the production slot causes a restart that impacts availability, consider doing this change at a time of reduced traffic. You can then swap in the updated version from the staging slot.

The Update-AzFunctionAppSetting PowerShell cmdlet doesn't currently support slots. You must use Azure CLI or the Azure portal.

  1. Use the following command to set WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 in the production slot:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0  -g <RESOURCE_GROUP_NAME>  -n <APP_NAME>

    In this example, replace <APP_NAME> with the name of your function app and <RESOURCE_GROUP_NAME> with the name of the resource group. This command causes the app running in the production slot to restart.

  2. Use the following command to also set WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS in the staging slot:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  3. Use the following command to change FUNCTIONS_EXTENSION_VERSION and update the staging slot to the new runtime version:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  4. Version 4.x of the Functions runtime requires .NET 6 in Windows. On Linux, .NET apps must also update to .NET 6. Use the following command so that the runtime can run on .NET 6:

    Windows

    When running on Windows, you also need to enable .NET 8.0, which is required by version 4.x of the runtime.

    az functionapp config set --net-framework-version v8.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 is required for function apps in any language running on Windows.

    Linux

    [!INCLUDE functions-migrate-v4-linuxfxversion]

    In this example, replace <APP_NAME> with the name of your function app and <RESOURCE_GROUP_NAME> with the name of the resource group.

  5. If your code project required any updates to run on version 4.x, deploy those updates to the staging slot now.

  6. Confirm that your function app runs correctly in the updated staging environment before swapping.

  7. Use the following command to swap the updated staging slot to production:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

Minimum downtime update

To minimize the downtime in your production app, you can swap the WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS setting from the staging slot into production. After that, you can swap in the updated version from a prewarmed staging slot.

  1. Use the following command to set WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 in the staging slot:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  2. Use the following commands to swap the slot with the new setting into production, and at the same time restore the version setting in the staging slot.

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production
az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~3 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    You may see errors from the staging slot during the time between the swap and the runtime version being restored on staging. This error can happen because having WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 only in staging during a swap removes the FUNCTIONS_EXTENSION_VERSION setting in staging. Without the version setting, your slot is in a bad state. Updating the version in the staging slot right after the swap should put the slot back into a good state, and you call roll back your changes if needed. However, any rollback of the swap also requires you to directly remove WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 from production before the swap back to prevent the same errors in production seen in staging. This change in the production setting would then cause a restart.

  3. Use the following command to again set WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 in the staging slot:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    At this point, both slots have WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 set.

  4. Use the following command to change FUNCTIONS_EXTENSION_VERSION and update the staging slot to the new runtime version:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  5. Version 4.x of the Functions runtime requires .NET 6 in Windows. On Linux, .NET apps must also update to .NET 6. Use the following command so that the runtime can run on .NET 6:

    Windows

    When running on Windows, you also need to enable .NET 8.0, which is required by version 4.x of the runtime.

    az functionapp config set --net-framework-version v8.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 is required for function apps in any language running on Windows.

    Linux

    [!INCLUDE functions-migrate-v4-linuxfxversion]

    In this example, replace <APP_NAME> with the name of your function app and <RESOURCE_GROUP_NAME> with the name of the resource group.

  6. If your code project required any updates to run on version 4.x, deploy those updates to the staging slot now.

  7. Confirm that your function app runs correctly in the updated staging environment before swapping.

  8. Use the following command to swap the updated and prewarmed staging slot to production:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production