Azure Site Extensions - davidni/kudu GitHub Wiki

This post introduces the Site Extension UI in the Preview Portal. Also, checkout this blog post for great information on getting started. The info below offers more technical details about how things work.

When you have an Azure Web Site, an IIS applicationhost.config gets generated by Azure for your site. In some scenarios, it can be interesting to tweak how this file is generated. Site Extensions provide a powerful way to do this using XDT Transforms.

There are two main types of Site Extensions:

1. Pre-Installed: they live under Program Files (x86) and are available to all sites. Kudu and Monaco are examples of this.
2. Private: installed by the user as part of the site files. Only apply to one site at a time.

Generally, site extensions can modify applicationhost.config in arbitrary ways by applying transforms to it. Some common usage:

1. Adding new applications to the 'scm' site: the Kudu service runs at the root of the scm site, but you can add sub-applications. e.g. /foo on the scm endpoint can be an unrelated app. The advantage of running under the scm endpoint is that it is protected by authentication, making it a great place to run admin tools of all kind.
2. Adding new applications (and vdirs) to the main site. Note that there is a simpler way to do this via the Azure Portal, so using Site Extensions this way is less common.
3. Arbitrary other changes: e.g. tweak the <fastCgi>, <httpCompression/> or <httpModules/> sections, etc...

All pre-installed Site Extensions are under %ProgramFiles(x86)%\SiteExtensions. e.g.

d:\Program Files (x86)
    SiteExtensions
        Kudu
            extension.xml
            1.24.12345
                applicationHost.xdt
                kudu bits...
            1.24.34567-preview
                applicationHost.xdt
                kudu bits...

extension.xml has the following format:

<extension>
    <version>latest|beta|1.2.3456|disabled</version>
</extension>

version can take the following values:

• latest: all sites get the latest non-prerelease version of the Extension. This is the default in case there is no extension.xml (which is why Kudu doesn't have this file)
• beta: all sites get the latest prerelease version of the Extension
• disabled: sites don't get the extension at all
• Specific version: e.g. 1.2.3456 (using semver syntax). Sites get this exact version of the Extension.

Each site can override the version by specifying <extension>_EXTENSION_VERSION in the AppSettings (e.g. from the Azure Portal). e.g. for Kudu you could set KUDU_EXTENSION_VERSION=beta to make the site get pre-release versions (if any are available).

Note that if newer Pre-Installed versions become available later, all sites will get them if it matches their version selection. However, a site restart is necessary for the site to get the newer version.

To become pre-installed site extension, partners must first contact the Windows Azure Kudu team (see Kudu contact). In order for us to add or update the Windows Azure pre-installed site extension, we will need a single zip package. The zip filename should be in <extension>.<semver>.zip format (for example, Kudu.1.25.21217.582.zip or Monaco.1.0.0-20130906.zip). The layout in the zip file should also be consistent with the zip file name. For instance, Kudu.1.25.21217.582.zip layout should be

        extension.xml
        /1.25.21217.582
            applicationHost.xdt
            kudu bits... 

Or Monaco.1.0.0-20130906.zip layout should be

        extension.xml
        /1.0.0-20130906
            applicationHost.xdt
            Monaco bits... 

After installation on Windows Azure, it will be lay out (unzip) exactly to %ProgramFiles(x86)%\SiteExtensions\<extension>

The site owner can overwrite the existing site extensions with their own implementations or introduce a totally new set of site extensions altogether.

Important note: Site Extensions only get applied after the site is restarted. However, if you modify existing extensions without changing the applicationHost.xdt, no manual restart is needed.

There are two flavors of Private site extensions: 'named' and 'top level'.

These work the same way as the 'pre-installed' extensions discussed above, except they're brought in by the site owner.

Here is a complete Site Extension sample.

All you need to do is upload the extension bits into a SiteExtensions folder. Below examples illustrate overriding the Kudu extension as well as introducing a new Foo extension. Note that unlike pre-installed extensions, these are not in versioned folders.

    /site
    /LogFiles
    /SiteExtensions
        /Kudu
            applicationHost.xdt
            kudu bits...
        /Foo
            applicationHost.xdt
            foo bits...

There can be only one such extension for a given site, and it consists of a single applicationHost.xdt file living in the site folder. It is typically used to make general tweaks to your site's ApplicationHost.config.

    /site
        applicationHost.xdt
        /wwwroot
    /LogFiles

Please check out XDT Transform Samples for a set of examples of what you can do with XDT files.

There are a set of environment variables passed to the XDT to assist in locating the appropriate elements and set the proper property.

• XDT_SITENAME is the current site name
• XDT_SCMSITENAME is the current scm site name
• XDT_EXTENSIONPATH is the version specific extension physical path
• HOME is the site root path

Site extensions can be shared with others using the Site Extensions gallery. See this post for more information.

An extension installed from the gallery can contain install/uninstall scripts. To use this, simply include an install.cmd and/or uninstall.cmd at the root of your extension. You can find an example here (taken from the Image Compressor extension).

Before trying to apply any transform, you may want to see what the applicationhost.config looks like. Likewise, after applying a transform, you'll want to look at applicationhost.config to make sure it looks ok.

Here is one way to do it (we should try to make this easier in the future):

• Go to the Kudu Console
• Click the 'planet' icon
• Click the Config folder
• Click the download button for applicationhost.config. Or you can click the Edit button to look at it directly in the browser (but don't attempt to modify it from here, as it's read only!)

If you look under /LogFiles/Transform you should see a log that gives info about what happened during the transforms. This can be very useful when errors happen.

If you run into problems and hose your site, all you have to do is set WEBSITE_PRIVATE_EXTENSIONS=0 in the site AppSettings, and none of your XDT will be applied.