Skip to content

Commit d17f753

Browse files
author
Jill Grant
authored
Merge pull request #280027 from dksimpson/tsk261306-dks-9
Refresh article: How to target Azure Functions runtime versions [Task 261306]
2 parents 9e8a347 + 22de45e commit d17f753

File tree

3 files changed

+64
-56
lines changed

3 files changed

+64
-56
lines changed

‎articles/azure-functions/set-runtime-version.md

Lines changed: 58 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,60 @@
11
---
22
title: How to target Azure Functions runtime versions
3-
description: Azure Functions supports multiple versions of the runtime. Learn how to specify the runtime version of a function app hosted in Azure.
4-
ms.topic: conceptual
3+
description: Learn how to specify the runtime version of a function app hosted in Azure.
4+
ms.service: azure-functions
5+
ms.topic: how-to
6+
ms.date: 07/03/2024
57
ms.custom: ignite-2023, linux-related-content
6-
ms.date: 03/11/2024
78
zone_pivot_groups: app-service-platform-windows-linux
9+
10+
#Customer intent: As a function developer, I want to learn how to view and edit the runtime version of my function app so that I can pin it to a specific minor version, if necessary.
811
---
912

1013
# How to target Azure Functions runtime versions
1114

12-
A function app runs on a specific version of the Azure Functions runtime. By default, function apps are created in latest 4.x version of the Functions runtime. Your function apps are only supported when running on a [supported major version](functions-versions.md). This article explains how to configure a function app in Azure to target, or _pin_ to, a specific version when required.
13-
14-
::: zone pivot="platform-windows"
15+
A function app runs on a specific version of the Azure Functions runtime. By default, function apps are created in the latest 4.x version of the Functions runtime. Your function apps are supported only when they run on a [supported major version](functions-versions.md). This article explains how to configure a function app in Azure to target, or _pin_ to, a specific version when required.
16+
17+
::: zone pivot="platform-windows"
1518
The way that you target a specific version depends on whether you're running Windows or Linux. This version of the article supports Windows. Choose your operating system at the top of the article.
1619
::: zone-end
17-
::: zone pivot="platform-linux"
20+
::: zone pivot="platform-linux"
1821
The way that you target a specific version depends on whether you're running Windows or Linux. This version of the article supports Linux. Choose your operating system at the top of the article.
1922
::: zone-end
2023
>[!IMPORTANT]
21-
>When possible, you should always run your functions on the latest supported version of the Azure Functions runtime. You should only pin your app to a specific version when instructed to do so because of an issue in the latest version. You should always move up to the latest runtime version as soon as your functions can run correctly.
24+
>When possible, always run your functions on the latest supported version of the Azure Functions runtime. You should only pin your app to a specific version if you're instructed to do so due to an issue with the latest version. Always move up to the latest runtime version as soon as your functions can run correctly.
2225
23-
During local development, your installed version of Azure Functions Core Tools must match major runtime version used by the function app in Azure. For more information, see [Core Tools versions](functions-run-local.md#v2).
26+
During local development, your installed version of Azure Functions Core Tools must match the major runtime version used by the function app in Azure. For more information, see [Core Tools versions](functions-run-local.md#v2).
2427

2528
## Update your runtime version
2629

2730
When possible, you should always run your function apps on the latest supported version of the Azure Functions runtime. If your function app is currently running on an older version of the runtime, you should migrate your app to version 4.x
2831

2932
[!INCLUDE [functions-migrate-apps](../../includes/functions-migrate-apps.md)]
3033

31-
To determine your current runtime version, see [View the current runtime version](#view-the-current-runtime-version).
34+
To determine your current runtime version, see [View the current runtime version](#view-the-current-runtime-version).
3235

3336
## View the current runtime version
3437

3538
You can view the current runtime version of your function app in one of these ways:
3639

37-
### [Portal](#tab/portal)
40+
### [Azure portal](#tab/azure-portal)
3841

3942
[!INCLUDE [Set the runtime version in the portal](../../includes/functions-view-update-version-portal.md)]
4043

41-
### [Azure CLI](#tab/azurecli)
44+
### [Azure CLI](#tab/azure-cli)
4245

43-
You can view the `FUNCTIONS_EXTENSION_VERSION` from the Azure CLI.
46+
You can view the `FUNCTIONS_EXTENSION_VERSION` app setting from the Azure CLI.
4447

45-
Using the Azure CLI, view the current runtime version with the [`az functionapp config appsettings list`](/cli/azure/functionapp/config/appsettings) command.
48+
Using the Azure CLI, view the current runtime version with the [`az functionapp config appsettings list`](/cli/azure/functionapp/config/appsettings) command:
4649

4750
```azurecli-interactive
4851
az functionapp config appsettings list --name <function_app> \
4952
--resource-group <my_resource_group>
5053
```
5154

52-
In this code, replace `<function_app>` with the name of your function app. Also replace `<my_resource_group>` with the name of the resource group for your function app.
55+
In this code, replace `<function_app>` with the name of your function app. Also replace `<my_resource_group>` with the name of the resource group for your function app.
5356

54-
You see the `FUNCTIONS_EXTENSION_VERSION` in the following output, which has been truncated for clarity:
57+
You see the `FUNCTIONS_EXTENSION_VERSION` in the following partial output:
5558

5659
```output
5760
[
@@ -72,43 +75,46 @@ You see the `FUNCTIONS_EXTENSION_VERSION` in the following output, which has bee
7275

7376
Choose **Open Cloud Shell** in the previous code example to run the command in [Azure Cloud Shell](../cloud-shell/overview.md). You can also run the [Azure CLI locally](/cli/azure/install-azure-cli) to execute this command. When running locally, you must first run [`az login`](/cli/azure/reference-index#az-login) to sign in.
7477

75-
### [PowerShell](#tab/powershell)
78+
### [Azure PowerShell](#tab/azure-powershell)
7679

77-
To check the Azure Functions runtime, use the following cmdlet:
80+
To check the Azure Functions runtime, use the following cmdlet:
7881

79-
```powershell
82+
```azurepowershell-interactive
8083
Get-AzFunctionAppSetting -Name "<FUNCTION_APP>" -ResourceGroupName "<RESOURCE_GROUP>"
8184
```
85+
8286
Replace `<FUNCTION_APP>` with the name of your function app and `<RESOURCE_GROUP>`. The current value of the `FUNCTIONS_EXTENSION_VERSION` setting is returned in the hash table.
8387

8488
---
8589

86-
## <a name="manual-version-updates-on-linux"></a>Pinning to a specific version
90+
## <a name="manual-version-updates-on-linux"></a>Pin to a specific version
8791

88-
Azure Functions lets you use the `FUNCTIONS_EXTENSION_VERSION` application setting to target the runtime version used by a given function app. When you specify only the major version (`~4`), the function app is automatically updated to new minor versions of the runtime when they become available. Minor version updates are done automatically because new minor versions shouldn't introduce breaking changes.
92+
Azure Functions lets you use the `FUNCTIONS_EXTENSION_VERSION` app setting to target the runtime version used by a given function app. If you specify only the major version (`~4`), the function app is automatically updated to new minor versions of the runtime as they become available. Minor version updates are done automatically because new minor versions aren't likely to introduce changes that would break your functions.
8993
::: zone pivot="platform-linux"
90-
Linux apps use the [`linuxFxVersion` site setting](./functions-app-settings.md#linuxfxversion) along with `FUNCTIONS_EXTENSION_VERSION` to determine the correct Linux base image in which to run your functions. When you create a new funtion app on Linux, the runtime automatically chooses the correct base image for you based on the runtime version of your language stack.
94+
Linux apps use the [`linuxFxVersion` site setting](./functions-app-settings.md#linuxfxversion) along with `FUNCTIONS_EXTENSION_VERSION` to determine the correct Linux base image in which to run your functions. When you create a new function app on Linux, the runtime automatically chooses the correct base image for you based on the runtime version of your language stack.
9195
::: zone-end
9296
Pinning to a specific runtime version causes your function app to restart.
93-
::: zone pivot="platform-windows"
94-
When you specify a specific minor version (such as `4.0.12345`) in `FUNCTIONS_EXTENSION_VERSION`, the function app is pinned to that specific version of the runtime until you explicitly choose to move back to automatic updates. You should only pin to a specific minor version long enough to resolve any issues with your function app that prevent you from targeting the major version. Older minor versions are regularly removed from the production environment. When you're pinned to a minor version that gets removed, your function app is instead run on the closest existing version instead of the version set in `FUNCTIONS_EXTENSION_VERSION`. Minor version removals are announced in [App Service announcements](https://github.com/Azure/app-service-announcements/issues).
97+
::: zone pivot="platform-windows"
98+
When you specify a specific minor version (such as `4.0.12345`) in `FUNCTIONS_EXTENSION_VERSION`, the function app is pinned to that specific version of the runtime until you explicitly choose to move back to automatic version updates. You should only pin to a specific minor version long enough to resolve any issues with your function app that prevent you from targeting the major version. Older minor versions are regularly removed from the production environment. When your function app is pinned to a minor version that is later removed, your function app is instead run on the closest existing version instead of the version set in `FUNCTIONS_EXTENSION_VERSION`. Minor version removals are announced in [App Service announcements](https://github.com/Azure/app-service-announcements/issues).
9599

96100
> [!NOTE]
97-
> When you try to publish from Visual Studio to an app that is pinned to a specific minor version of the runtime, a dialog prompts you to update to the latest version or cancel the publish. To avoid this check when you must use a specific minor version, add the `<DisableFunctionExtensionVersionUpdate>true</DisableFunctionExtensionVersionUpdate>` property in your `.csproj` file.
101+
> When you try to publish from Visual Studio to an app that is pinned to a specific minor version of the runtime, a dialog prompts you to update to the latest version or cancel the publish. To avoid this check when you must use a specific minor version, add the `<DisableFunctionExtensionVersionUpdate>true</DisableFunctionExtensionVersionUpdate>` property in your `.csproj` file.
98102
99-
Use one of these methods to temporarily pin your app to a specific version of the runtime:
103+
Use one of these methods to temporarily pin your app to a specific version of the runtime:
100104

101-
### [Portal](#tab/portal)
105+
### [Azure portal](#tab/azure-portal)
102106

103107
[!INCLUDE [Set the runtime version in the portal](../../includes/functions-view-update-version-portal.md)]
104108

105-
3. To pin your app to a specific minor version, select **Application settings** > **FUNCTIONS_EXTENSION_VERSION**, change **Value** to your required minor version, and select **OK**.
109+
3. To pin your app to a specific minor version, in the left pane, expand **Settings**, and then select **Environment variables**.
110+
111+
4. From the **App settings** tab, select **FUNCTIONS_EXTENSION_VERSION**, change **Value** to your required minor version, and then select **Apply**.
106112

107-
4. Select **Save** > **Continue** to apply changes and restart the app.
113+
5. Select **Apply**, and then select **Confirm** to apply the changes and restart the app.
108114

109-
### [Azure CLI](#tab/azurecli)
115+
### [Azure CLI](#tab/azure-cli)
110116

111-
You can update the `FUNCTIONS_EXTENSION_VERSION` setting in the function app with the [az functionapp config appsettings set](/cli/azure/functionapp/config/appsettings) command.
117+
You can update the `FUNCTIONS_EXTENSION_VERSION` app setting in the function app with the [az functionapp config appsettings set](/cli/azure/functionapp/config/appsettings) command.
112118

113119
```azurecli-interactive
114120
az functionapp config appsettings set --name <FUNCTION_APP> \
@@ -118,56 +124,56 @@ az functionapp config appsettings set --name <FUNCTION_APP> \
118124

119125
Replace `<FUNCTION_APP>` with the name of your function app and `<RESOURCE_GROUP>` with the name of the resource group for your function app. Also, replace `<VERSION>` with the specific minor version you temporarily need to target.
120126

121-
Choose **Try it** in the previous code example to run the command in [Azure Cloud Shell](../cloud-shell/overview.md). You can also run the [Azure CLI locally](/cli/azure/install-azure-cli) to execute this command. When running locally, you must first run [`az login`](/cli/azure/reference-index#az-login) to sign in.
127+
Choose **Open Cloud Shell** in the previous code example to run the command in [Azure Cloud Shell](../cloud-shell/overview.md). You can also run the [Azure CLI locally](/cli/azure/install-azure-cli) to execute this command. When running locally, you must first run [`az login`](/cli/azure/reference-index#az-login) to sign in.
122128

123-
### [PowerShell](#tab/powershell)
129+
### [Azure PowerShell](#tab/azure-powershell)
124130

125131
Use this script to pin the Functions runtime:
126132

127-
```powershell
133+
```azurepowershell-interactive
128134
Update-AzFunctionAppSetting -Name "<FUNCTION_APP>" -ResourceGroupName "<RESOURCE_GROUP>" -AppSetting @{"FUNCTIONS_EXTENSION_VERSION" = "<VERSION>"} -Force
129135
```
130136

131-
Replace `<FUNCTION_APP>` with the name of your function app and `<RESOURCE_GROUP>` with the name of the resource group for your function app. Also, replace `<VERSION>` with the specific minor version you temporarily need to target. You can verify the updated value of the `FUNCTIONS_EXTENSION_VERSION` setting in the returned hash table.
137+
Replace `<FUNCTION_APP>` with the name of your function app and `<RESOURCE_GROUP>` with the name of the resource group for your function app. Also, replace `<VERSION>` with the specific minor version you temporarily need to target. You can verify the updated value of the `FUNCTIONS_EXTENSION_VERSION` setting in the returned hash table.
132138

133139
---
134140

135-
The function app restarts after the change is made to the application setting.
141+
The function app restarts after the change is made to the application setting.
136142
::: zone-end
137-
::: zone pivot="platform-linux"
138-
To pin your function app to a specific runtime version on Linux, you set a version-specific base image URL in the [`linuxFxVersion` site setting][`linuxFxVersion`] in the format `DOCKER|<PINNED_VERSION_IMAGE_URI>`.
143+
::: zone pivot="platform-linux"
144+
To pin your function app to a specific runtime version on Linux, you set a version-specific base image URL in the [`linuxFxVersion` site setting][`linuxFxVersion`] in the format `DOCKER|<PINNED_VERSION_IMAGE_URI>`.
139145

140146
> [!IMPORTANT]
141-
> Pinned function apps on Linux don't receive regular security and host functionality updates. Unless recommended by a support professional, use the [`FUNCTIONS_EXTENSION_VERSION`](functions-app-settings.md#functions_extension_version) setting and a standard [`linuxFxVersion`] value for your language and version, such as `Python|3.9`. For valid values, see the [`linuxFxVersion` reference article][`linuxFxVersion`].
147+
> Pinned function apps on Linux don't receive regular security and host functionality updates. Unless recommended by a support professional, use the [`FUNCTIONS_EXTENSION_VERSION`](functions-app-settings.md#functions_extension_version) setting and a standard [`linuxFxVersion`] value for your language and version, such as `Python|3.9`. For valid values, see the [`linuxFxVersion` reference article][`linuxFxVersion`].
142148
>
143-
> Pinning to a specific runtime isn't currently supported for Linux function apps running in a Consumption plan.
149+
> Pinning to a specific runtime isn't currently supported for Linux function apps running in a Consumption plan.
144150
145-
The following is an example of the [`linuxFxVersion`] value required to pin a Node.js 16 function app to a specific runtime version of 4.14.0.3:
151+
The following example shows the [`linuxFxVersion`] value required to pin a Node.js 16 function app to a specific runtime version of 4.14.0.3:
146152

147-
`DOCKER|mcr.microsoft.com/azure-functions/node:4.14.0.3-node16`
153+
`DOCKER|mcr.microsoft.com/azure-functions/node:4.14.0.3-node16`
148154

149-
When needed, a support professional can provide you with a valid base image URI for your application.
155+
When needed, a support professional can provide you with a valid base image URI for your application.
150156

151-
Use the following Azure CLI commands to view and set the [`linuxFxVersion`]. You can't currently set [`linuxFxVersion`] in the portal or by using Azure PowerShell.
157+
Use the following Azure CLI commands to view and set the [`linuxFxVersion`]. You can't currently set [`linuxFxVersion`] in the portal or by using Azure PowerShell:
152158

153-
+ To view the current runtime version, use with the [az functionapp config show](/cli/azure/functionapp/config) command.
159+
+ To view the current runtime version, use the [az functionapp config show](/cli/azure/functionapp/config) command:
154160

155161
```azurecli-interactive
156162
az functionapp config show --name <function_app> \
157163
--resource-group <my_resource_group> --query 'linuxFxVersion' -o tsv
158164
```
159-
160-
In this code, replace `<function_app>` with the name of your function app. Also replace `<my_resource_group>` with the name of the resource group for your function app. The current value of [`linuxFxVersion`] is returned.
161-
162-
+ To update the [`linuxFxVersion`] setting in the function app, use the [az functionapp config set](/cli/azure/functionapp/config) command.
165+
166+
In this code, replace `<function_app>` with the name of your function app. Also, replace `<my_resource_group>` with the name of the resource group for your function app. The current value of [`linuxFxVersion`] is returned.
167+
168+
+ To update the [`linuxFxVersion`] setting in the function app, use the [az functionapp config set](/cli/azure/functionapp/config) command:
163169
164170
```azurecli-interactive
165171
az functionapp config set --name <FUNCTION_APP> \
166172
--resource-group <RESOURCE_GROUP> \
167173
--linux-fx-version <LINUX_FX_VERSION>
168174
```
169-
170-
Replace `<FUNCTION_APP>` with the name of your function app. Also replace `<RESOURCE_GROUP>` with the name of the resource group for your function app. Finally, replace `<LINUX_FX_VERSION>` with the value of a specific image provided to you by a support professional.
175+
176+
Replace `<FUNCTION_APP>` with the name of your function app. Also, replace `<RESOURCE_GROUP>` with the name of the resource group for your function app. Finally, replace `<LINUX_FX_VERSION>` with the value of a specific image provided to you by a support professional.
171177
172178
You can run these commands from the [Azure Cloud Shell](../cloud-shell/overview.md) by choosing **Open Cloud Shell** in the preceding code examples. You can also use the [Azure CLI locally](/cli/azure/install-azure-cli) to execute this command after executing [`az login`](/cli/azure/reference-index#az-login) to sign in.
173179
@@ -177,6 +183,6 @@ The function app restarts after the change is made to the site config.
177183
## Next steps
178184
179185
> [!div class="nextstepaction"]
180-
> [See Release notes for runtime versions](https://github.com/Azure/azure-webjobs-sdk-script/releases)
186+
> [Release notes for runtime versions](https://github.com/Azure/azure-webjobs-sdk-script/releases)
181187
182188
[`linuxFxVersion`]: functions-app-settings.md#linuxfxversion

0 commit comments

Comments
 (0)