Zip Push Deployment for Web Apps, Functions and WebJobs

Nick Walker 10/16/2017 10:20:11 AM

---

With our most recent release of Kudu, we have introduced a new deployment option for web apps, Azure Functions and WebJobs: zip push deployment. Zipdeploy combines the simplicity of Kudu’s zip API with the flexibility and robustness of Kudu’s deployment features, like deletion of unused files from old deployments, history tracking and Auto Swap support.

Why a new API?

Since App Service and Kudu were first introduced, the deployment needs of developers have evolved.

• Availability and adoption of mature continuous integration and delivery (CI/CD) tools and services like VSTS have grown significantly. Developers are increasingly looking to deploy tested, ready-to-run apps from these services instead of from source code.
• The ability of many app stacks to enable rapid iteration has improved. Many contemporary developer workflows require the ability to quickly deploy directly from a development environment.
• The introduction of Azure Functions has further driven the popularity of rapid-iteration workflows. The nature of Functions encourages developers to repeatedly prototype and deploy small packages of functionality.

Kudu features a variety of mechanisms for deploying code to App Service that make use of its underlying deployment platform, which provides for safe, tracked deployments. But despite its relative lack of features, feedback has indicated that many developers favor using Kudu’s zip API for deployments, especially in the above scenarios. For many workflows, the pure simplicity and cross-platform availability of the push-based zip API and of zip files themselves wins out over the features of other available deployment mechanisms:

• Git deployment restricts your site contents to files that are in the repository and requires a commit to deploy. Triggering deployments with pushes to hosted providers like GitHub requires some setup before getting started. Git deployment also engages Kudu's CI build system by default, which detects your app's runtime stack and generates scripts to do things like restore packages or compile code. This is undesirable when deploying an app that's already been built by your CI/CD service or deploying a working app from your local environment.
• Web Deploy (aka msdeploy) is extremely powerful but challenging to configure. It's not supported on App Service on Linux and can't be used from non-Windows clients.
• FTP requires tools that many developers don't have handy or aren't familiar with. Many of them require scripting to achieve the desired result.

Zips are simple and ubiquitous, but without a connection to Kudu's deployment features, the zip API is only fit for general-purpose file transfers and is not robust enough for deployments. Deploying via the zip API can leave old files lying around that can break your application or Function unless you completely erase the existing files first. It doesn't create any deployment history, and there is no first-class way of verifying that deployment operations performed via the zip API are 100% successful. Why not combine the ease of pushing a zip file up to your site with Kudu's comprehensive deployment features? Enter zipdeploy!

Usage

Create a zip file containing the files you want deployed to wwwroot and POST it as binary data to /api/zipdeploy on your site’s Kudu instance. Here’s how to do it with curl:

curl -X POST -u <publishing-user> --data-binary @<zipfile> https://{sitename}.scm.azurewebsites.net/api/zipdeploy

Be aware that this operation may delete files currently in your site depending on the contents of your deployment! See Features below for more information. Add ?isAsync=true to the URL to perform an async deployment. A response will be returned as soon as the file is uploaded, and the deployment will continue on the server. The response will include a Location header with a URL that can be queried for realtime deployment status. By default, Kudu assumes that zip deployments do not require any build-related actions like npm install or dotnet publish. This can be overridden by setting the SCM_DO_BUILD_DURING_DEPLOYMENT deployment setting to true to enable Kudu’s detection logic and build script generation process. As with all web app deployments, modifying the files of a running app is a potentially dangerous operation that exposes your app to clients in a partially-deployed state. Apps that need atomic, zero-downtime deployments, smoke testing and/or rollback support should always use a staging environment and a slot swap as part of deployment.

Features

• Flexibility: Push-based zip deployment eliminates the need to host your build output on the web or create a git commit. Zip deployments do not require any setup in Kudu or the Azure portal and can be run at any time with nothing but an HTTP client, regardless of whether your application is already synced with a source control provider.
• Deletion of files left over from the previous deployment: Deployments use the KuduSync utility to track and delete files and directories that were created by a previous deployment if they’re not included in the new deployment. Any other files and directories found in the site that aren't being overwritten by the deployment will be preserved, such as files deployed via FTP, created in the Functions portal or created by your app during runtime.
• Function trigger sync: If you are running Functions on a Consumption plan, modifying their triggers requires a synchronization process that doesn't occur with file-based deployment methods like FTP or the zip API. Zipdeploy will perform this synchronization for you.
• Efficient file copy: KuduSync will only overwrite an existing file if its last-modified timestamp doesn’t match what’s in the deployment. You can speed up your deployments by using a build process that preserves timestamps on files that do not change across builds.
• Logging, status tracking and history: Zipdeploy generates live status, deployment logs and recorded history in Kudu's deployment API. However, zip deployments cannot be redeployed.
• Async support: By adding ?isAsync=true to the URL, a response will be returned as soon as the zip has been uploaded to the site. Deployment will continue asynchronously on the server. The Location header of the response will contain the deployment URL that can be polled for deployment status. Webhooks can be used for fully asynchronous notification of completion.
• Customization: Deployment-related settings will be respected, including those in app settings as well as configuration placed in a .deployment file located in the root of the zip.
• Build script support: By default, zipdeploy assumes that the zip contains a ready-to-run app. Kudu's continuous integration build process can be enabled via the SCM_DO_BUILD_DURING_DEPLOYMENT deployment setting, or by providing a custom build command with the COMMAND setting.
• Safe deployment: Zipdeploy engages Kudu's deployment locks, preventing multiple simultaneous deployments from clobbering your site.
• Auto Swap and container restart support: A zip deployment will trigger an Auto Swap if your site is configured for it. On App Service on Linux, zip deployment will trigger a restart of the app container.

Feedback

Please give zipdeploy a try and let us know what you think, especially if you're currently using the zip API for deployments. We’d love to hear your feedback – we’ll be watching the Issues tab on Kudu’s GitHub page, as well as the MSDN forums, Stack Overflow and Uservoice.