Zip deployment for Azure Functions

This article describes how to deploy your function app project files to Azure from a .zip (compressed) file. You learn how to do a push deployment, both by using Azure CLI and by using the REST APIs. Azure Functions Core Tools also uses these deployment APIs when publishing a local project to Azure.

Zip deployment is also an easy way to run your functions from a package file in Azure. It is the default deployment technology in the Consumption, Elastic Premium, and Dedicated (App Service) hosting plans. The Flex Consumption plan does not support zip deployment.

Azure Functions has the full range of continuous deployment and integration options that are provided by Azure App Service.

To speed up development, you might find it easier to deploy your function app project files directly from a .zip file. The .zip deployment API takes the contents of a .zip file and extracts the contents into the wwwroot folder of your function app. This .zip file deployment uses the same Kudu service that powers continuous integration-based deployments, including:

• Deletion of files that were left over from earlier deployments.
• Deployment customization, including running deployment scripts.
• Deployment logs.
• Syncing function triggers in a Consumption plan function app.

For more information, see the .zip deployment reference.

Deployment .zip file requirements

The zip archive you deploy must contain all of the files needed to run your function app. You can manually create a zip archive from the contents of a Functions project folder using built-in .zip compression functionality or third-party tools.

The archive must include the host.json file at the root of the extracted folder. The selected language stack for the function app creates additional requirements:

• .NET (isolated worker model)
• .NET (in-process model)
• Java
• JavaScript
• TypeScript
• PowerShell
• Python

A zip deployment process extracts the zip archive's files and folders in the wwwroot directory. If you include the parent directory when creating the archive, the system will not find the files it expects to see in wwwroot.

Deploy by using Azure CLI

You can use Azure CLI to trigger a push deployment. Push deploy a .zip file to your function app by using the az functionapp deployment source config-zip command. To use this command, you must use Azure CLI version 2.0.21 or later. To see what Azure CLI version you are using, use the az --version command.

In the following command, replace the <zip_file_path> placeholder with the path to the location of your .zip file. Also, replace <app_name> with the unique name of your function app and replace <resource_group> with the name of your resource group.

az functionapp deployment source config-zip -g <resource_group> -n \
<app_name> --src <zip_file_path>

This command deploys project files from the downloaded .zip file to your function app in Azure. It then restarts the app. To view the list of deployments for this function app, you must use the REST APIs.

When you're using Azure CLI on your local computer, <zip_file_path> is the path to the .zip file on your computer.

Deploy ZIP file with REST APIs

You can use the deployment service REST APIs to deploy the .zip file to your app in Azure. To deploy, send a POST request to https://<app_name>.scm.chinacloudsites.cn/api/zipdeploy. The POST request must contain the .zip file in the message body. The deployment credentials for your app are provided in the request by using HTTP BASIC authentication. For more information, see the .zip push deployment reference.

For the HTTP BASIC authentication, you need your App Service deployment credentials. To see how to set your deployment credentials, see Set and reset user-level credentials.

With cURL

The following example uses the cURL tool to deploy a .zip file. Replace the placeholders <deployment_user>, <zip_file_path>, and <app_name>. When prompted by cURL, type in the password.

curl -X POST -u <deployment_user> --data-binary @"<zip_file_path>" https://<app_name>.scm.chinacloudsites.cn/api/zipdeploy

This request triggers push deployment from the uploaded .zip file. You can review the current and past deployments by using the https://<app_name>.scm.chinacloudsites.cn/api/deployments endpoint, as shown in the following cURL example. Again, replace <app_name> with the name of your app and <deployment_user> with the username of your deployment credentials.

curl -u <deployment_user> https://<app_name>.scm.chinacloudsites.cn/api/deployments

Asynchronous zip deployment

While deploying synchronously you may receive errors related to connection timeouts. Add ?isAsync=true to the URL to deploy asynchronously. You will receive a response as soon as the zip file is uploaded with a Location header pointing to the pollable deployment status URL. When polling the URL provided in the Location header, you will receive a HTTP 202 (Accepted) response while the process is ongoing and a HTTP 200 (OK) response once the archive has been expanded and the deployment has completed successfully.

Azure AD authentication

An alternative to using HTTP BASIC authentication for the zip deployment is to use an Azure AD identity. Azure AD identity may be needed if HTTP BASIC authentication is disabled for the SCM site.

A valid Azure AD access token for the the user or service principal performing the deployment will be required. An access token can be retrieved using the Azure CLI's az account get-access-token command. The access token will be used in the Authentication header of the HTTP POST request.

curl -X POST \
    --data-binary @"<zip_file_path>" \
    -H "Authorization: Bearer <access_token>" \
    "https://<app_name>.scm.chinacloudsites.cn/api/zipdeploy"

With PowerShell

The following example uses Publish-AzWebapp upload the .zip file. Replace the placeholders <group-name>, <app-name>, and <zip-file-path>.

Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <zip-file-path>

This request triggers push deployment from the uploaded .zip file.

To review the current and past deployments, run the following commands. Again, replace the <deployment-user>, <deployment-password>, and <app-name> placeholders.

$username = "<deployment-user>"
$password = "<deployment-password>"
$apiUrl = "https://<app-name>.scm.chinacloudsites.cn/api/deployments"
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username, $password)))
$userAgent = "powershell/1.0"
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -UserAgent $userAgent -Method GET

Deploy by using ARM Template

You can use ZipDeploy ARM template extension to push your .zip file to your function app.

Example ZipDeploy ARM Template

This template includes both a production and staging slot and deploys to one or the other. Typically, you would use this template to deploy to the staging slot and then swap to get your new zip package running on the production slot.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServiceName": {
      "type": "string"
    },
    "deployToProduction": {
      "type": "bool",
      "defaultValue": false
    },
    "slot": {
      "type": "string",
      "defaultValue": "staging"
    },
    "packageUri": {
      "type": "secureString"
    }
  },
  "resources": [
    {
      "condition": "[parameters('deployToProduction')]",
      "type": "Microsoft.Web/sites/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/ZipDeploy', parameters('appServiceName'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    },
    {
      "condition": "[not(parameters('deployToProduction'))]",
      "type": "Microsoft.Web/sites/slots/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/{1}/ZipDeploy', parameters('appServiceName'), parameters('slot'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    }
  ]
}

For the initial deployment, you would deploy directly to the production slot. For more information, see Slot deployments.

Run functions from the deployment package

You can also choose to run your functions directly from the deployment package file. This method skips the deployment step of copying files from the package to the wwwroot directory of your function app. Instead, the package file is mounted by the Functions runtime, and the contents of the wwwroot directory become read-only.

Zip deployment integrates with this feature, which you can enable by setting the function app setting WEBSITE_RUN_FROM_PACKAGE to a value of 1. For more information, see Run your functions from a deployment package file.

Deployment customization

The deployment process assumes that the .zip file that you push contains a ready-to-run app. By default, no customizations are run. To enable the same build processes that you get with continuous integration, add the following to your application settings:

SCM_DO_BUILD_DURING_DEPLOYMENT=true

When you use .zip push deployment, this setting is false by default. The default is true for continuous integration deployments. When set to true, your deployment-related settings are used during deployment. You can configure these settings either as app settings or in a .deployment configuration file that's located in the root of your .zip file. For more information, see Repository and deployment-related settings in the deployment reference.

Download your function app files

If you created your functions by using the editor in the Azure portal, you can download your existing function app project as a .zip file in one of these ways:

• From the Azure portal:

  1. Sign in to the Azure portal, and then go to your function app.

  2. On the Overview tab, select Download app content. Select your download options, and then select Download.

     

     The downloaded .zip file is in the correct format to be republished to your function app by using .zip push deployment. The portal download can also add the files needed to open your function app directly in Visual Studio.

• Using REST APIs:

  Use the following deployment GET API to download the files from your <function_app> project:

  https://<function_app>.scm.chinacloudsites.cn/api/zip/site/wwwroot/
  

  Including /site/wwwroot/ makes sure your zip file includes only the function app project files and not the entire site. If you are not already signed in to Azure, you will be asked to do so.

You can also download a .zip file from a GitHub repository. When you download a GitHub repository as a .zip file, GitHub adds an extra folder level for the branch. This extra folder level means that you can't deploy the .zip file directly as you downloaded it from GitHub.

Next steps