VM Applications overview

VM Applications are a resource type in Azure Compute Gallery (formerly known as Shared Image Gallery) that simplifies management, sharing, and global distribution of applications for your virtual machines.

While you can create an image of a VM with apps preinstalled, you would need to update your image each time you have application changes. Separating your application installation from your VM images means there’s no need to publish a new image for every line of code change.

Application packages provide benefits over other deployment and packaging methods:

• VM Applications have support for Azure Policies

• Grouping and versioning of your packages

• VM applications can be globally replicated to be closer to your infrastructure, so you don't need to use AzCopy or other storage copy mechanisms to copy the bits across Azure regions.

• Sharing with other users through Azure Role Based Access Control (RBAC)

• Support for virtual machines, and both flexible and uniform scale sets

• If you have Network Security Group (NSG) rules applied on your VM or scale set, downloading the packages from an internet repository might not be possible. And with storage accounts, downloading packages onto locked-down VMs would require setting up private links.

• Support for Block Blobs: This feature allows the handling of large files efficiently by breaking them into smaller, manageable blocks. Ideal for uploading large amounts of data, streaming, and background uploading.

What are VM app packages?

The VM application packages use multiple resource types:

Limitations

• No more than 3 replicas per region: When you're creating a VM Application version, the maximum number of replicas per region is three.

• Storage with public access or SAS URI with read privilege: The storage account needs to has public level access or use an SAS URI with read privilege, as other restriction levels fail deployments.

• Retrying failed installations: Currently, the only way to retry a failed installation is to remove the application from the profile, then add it back.

• Only 25 applications per VM: No more than 25 applications may be deployed to a VM at any point.

• 2GB application size: The maximum file size of an application version is 2 GB.

• No guarantees on reboots in your script: If your script requires a reboot, the recommendation is to place that application last during deployment. While the code attempts to handle reboots, it may fail.

• Requires a VM Agent: The VM agent must exist on the VM and be able to receive goal states.

• Multiple versions of same application on the same VM: You can't have multiple versions of the same application on a VM.

• Move operations currently not supported: Moving VMs with VM Apps to other resource groups aren't supported at this time.

Cost

There's no extra charge for using VM Application Packages, but you're charged for the following resources:

• Storage costs of storing each package and any replicas.
• Network egress charges for replication of the first image version from the source region to the replicated regions. Subsequent replicas are handled within the region, so there are no extra charges.

For more information on network egress, see Bandwidth pricing.

VM applications

The VM application resource defines the following about your VM application:

• Azure Compute Gallery where the VM application is stored
• Name of the application
• Supported OS type like Linux or Windows
• A description of the VM application

VM application versions

VM application versions are the deployable resource. Versions are defined with the following properties:

• Version number
• Link to the application package file in a storage account
• Install string for installing the application
• Remove string to show how to properly remove the app
• Package file name to use when it's downloaded to the VM
• Configuration file name to be used to configure the app on the VM
• A link to the configuration file for the VM application, which you can include license files
• Update string for how to update the VM application to a newer version
• End-of-life date. End-of-life dates are informational; you're still able to deploy VM application versions past the end-of-life date.
• Exclude from latest. You can keep a version from being used as the latest version of the application.
• Target regions for replication
• Replica count per region

Download directory

The download location of the application package and the configuration files are:

• Linux: /var/lib/waagent/Microsoft.CPlat.Core.VMApplicationManagerLinux/<appname>/<app version>
• Windows: C:\Packages\Plugins\Microsoft.CPlat.Core.VMApplicationManagerWindows\1.0.9\Downloads\<appname>\<app version>

The install/update/remove commands should be written assuming the application package and the configuration file are in the current directory.

File naming

When the application file gets downloaded to the VM, it's renamed as "MyVmApp" (no extension). This is because the VM isn't aware of your package's original name or extension. It utilizes the only name it has, which is the application name itself - "MyVmApp".

Here are a few alternatives to navigate this issue:

You can modify your script to include a command for renaming the file before execution:

move .\\MyVmApp .\\MyApp.exe & MyApp.exe /S

You can also use the packageFileName (and the corresponding configFileName) property to instruct us what to rename your file. For example, setting it to "MyApp.exe" will make your install script only need to be:

MyAppe.exe /S

Command interpreter

The default command interpreters are:

• Linux: /bin/bash
• Windows: cmd.exe

It's possible to use a different interpreter like Chocolatey or PowerShell, as long as it's installed on the machine, by calling the executable and passing the command to it. For example, to have your command run in PowerShell on Windows instead of cmd, you can pass powershell.exe -Command '<powershell commmand>'

How updates are handled

When you update an application version on a VM or Virtual Machine Scale Sets, the update command you provided during deployment is used. If the updated version doesn't have an update command, then the current version is removed and the new version is installed.

Update commands should be written with the expectation that it could be updating from any older version of the VM application.

Tips for creating VM Applications on Linux

Third party applications for Linux can be packaged in a few ways. Let's explore how to handle creating the install commands for some of the most common.

.tar and .gz files

These files are compressed archives and can be extracted to a desired location. Check the installation instructions for the original package to in case they need to be extracted to a specific location. If .tar.gz file contains source code, see the instructions for the package for how to install from source.

Example to install command to install golang on a Linux machine:

sudo tar -C /usr/local -xzf go_linux

Example remove command:

sudo rm -rf /usr/local/go

Creating application packages using .deb, .rpm, and other platform specific packages for VMs with restricted internet access

You can download individual packages for platform specific package managers, but they usually don't contain all the dependencies. For these files, you must also include all dependencies in the application package, or have the system package manager download the dependencies through the repositories that are available to the VM. If you're working with a VM with restricted internet access, you must package all the dependencies yourself.

Figuring out the dependencies can be a bit tricky. There are third party tools that can show you the entire dependency tree.

# Download the Microsoft repository GPG keys
wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb"
# Register the Microsoft repository GPG keys
sudo dpkg -i packages-microsoft-prod.deb
sudo rm -rf packages-microsoft-prod.deb
sudo apt update
sudo apt show powershell | grep Depends

Depends: libc6, lib32gcc-s1, libgssapi-krb5-2, libstdc++6, zlib1g, libicu72|libicu71|libicu70|libicu69|libicu68|libicu67|libicu66|libicu65|libicu63|libicu60|libicu57|libicu55|libicu52, libssl3|libssl1.1|libssl1.0.2|libssl1.

mkdir /tmp/powershell
cd /tmp/powershell
sudo apt-get download libc6
sudo apt-get download lib32gcc-s1
sudo apt-get download libgssapi-krb5-2
sudo apt-get download libstdc++6
sudo apt-get download zlib1g
sudo apt-get download libssl1.1
sudo apt-get download libicu60
sudo apt-get download powershell
sudo tar -cvzf powershell.tar.gz *.deb

mkdir /tmp/powershell
cd /tmp/powershell
sudo apt-get download libc6
sudo apt-get download lib32gcc-s1
sudo apt-get download libgssapi-krb5-2
sudo apt-get download libstdc++6
sudo apt-get download zlib1g
sudo apt-get download libssl1.1
sudo apt-get download libicu66
sudo apt-get download powershell
sudo tar -cvzf powershell.tar.gz *.deb

mkdir /tmp/powershell
cd /tmp/powershell
sudo apt-get download libc6
sudo apt-get download lib32gcc-s1
sudo apt-get download libgssapi-krb5-2
sudo apt-get download libstdc++6
sudo apt-get download zlib1g
sudo apt-get download libssl3
sudo apt-get download libicu70
sudo apt-get download powershell
sudo tar -cvzf powershell.tar.gz *.deb

sudo tar -xvzf powershell.tar.gz && sudo dpkg -i *.deb

sudo apt remove powershell

dpkg -i <package_name> || apt --fix-broken install -y

sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo zypper addrepo --name 'Azure CLI' --check https://packages.microsoft.com/yumrepos/azure-cli azure-cli
sudo zypper info --requires azure-cli

Requires       : [98]
    /usr/bin/python3
    python(abi) = 3.6
    azure-cli-command-modules-nspkg >= 2.0
    azure-cli-nspkg >= 3.0.3
    python3-azure-loganalytics >= 0.1.0
    python3-azure-mgmt-apimanagement >= 0.2.0
    python3-azure-mgmt-authorization >= 0.61.0
    python3-azure-mgmt-batch >= 9.0.0
    python3-azure-mgmt-cognitiveservices >= 6.3.0
    python3-azure-mgmt-containerservice >= 9.4.0
    python3-azure-mgmt-cosmosdb >= 1.0.0
    python3-azure-mgmt-datalake-store >= 0.5.0
    python3-azure-mgmt-deploymentmanager >= 0.2.0
    python3-azure-mgmt-imagebuilder >= 0.4.0
    python3-azure-mgmt-iothubprovisioningservices >= 0.2.0
    python3-azure-mgmt-maps >= 0.1.0
    python3-azure-mgmt-media >= 2.1.0
<truncated>
...
<truncated>
    python3-vsts-cd-manager >= 1.0.2
    python3-websocket-client >= 0.56.0
    python3-xmltodict >= 0.12
    python3-azure-mgmt-keyvault >= 8.0.0
    python3-azure-mgmt-storage >= 16.0.0
    python3-azure-mgmt-billing >= 1.0.0
    python3-azure-mgmt-cdn >= 5.2.0
    python3-azure-mgmt-hdinsight >= 2.0.0
    python3-azure-mgmt-netapp >= 0.14.0
    python3-azure-mgmt-synapse >= 0.5.0
    azure-cli-core = 2.17.1
    python3-azure-batch >= 10.0
    python3-azure-mgmt-compute >= 18.0
    python3-azure-mgmt-containerregistry >= 3.0.0rc16
    python3-azure-mgmt-databoxedge >= 0.2.0
    python3-azure-mgmt-network >= 17.0.0
    python3-azure-mgmt-security >= 0.6.0

mkdir /tmp/azurecli
cd /tmp/azurecli
for i in $(sudo zypper info --requires azure-cli | sed -n -e '/Requires*/,$p' | grep -v "Requires" | awk -F '[>=]' '{print $1}') ; do sudo zypper --non-interactive --pkg-cache-dir /tmp/azurecli install -f --download-only $i; done
for i in $(sudo find /tmp/azurecli -name "*.rpm") ; do sudo cp $i /tmp/azurecli; done
sudo tar -cvzf azurecli.tar.gz *.rpm

sudo tar -xvzf azurecli.tar.gz && sudo zypper --no-refresh --no-remote --non-interactive install *.rpm

sudo zypper remove azure-cli

Tips for creating VM Applications on Windows

Most third party applications in Windows are available as .exe or .msi installers. Some are also available as extract and run zip files. Let us look at the best practices for each of them.

.exe installer

Installer executables typically launch a user interface (UI) and require someone to select through the UI. If the installer supports a silent mode parameter, it should be included in your installation string.

Cmd.exe also expects executable files to have the extension .exe, so you need to rename the file to have the .exe extension.

If I want to create a VM application package for myApp.exe, which ships as an executable, my VM Application is called 'myApp', so I write the command assuming the application package is in the current directory:

"move .\\myApp .\\myApp.exe & myApp.exe /S -config myApp_config"

If the installer executable file doesn't support an uninstall parameter, you can sometimes look up the registry on a test machine to know where the uninstaller is located.

In the registry, the uninstall string is stored in Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\<installed application name>\UninstallString so I would use the contents as my remove command:

'\"C:\\Program Files\\myApp\\uninstall\\helper.exe\" /S'

.msi installer

For command line execution of .msi installers, the commands to install or remove an application should use msiexec. Typically, msiexec runs as its own separate process and cmd doesn't wait for it to complete, which can lead to problems when installing more than one VM application. The start command can be used with msiexec to ensure that the installation completes before the command returns. For example:

start /wait %windir%\\system32\\msiexec.exe /i myapp /quiet /forcerestart /log myapp_install.log

Example remove command:

start /wait %windir%\\system32\\msiexec.exe /x $appname /quiet /forcerestart /log ${appname}_uninstall.log

Typically, the start command would be called within a batch script. If used with the /wait parameter, the calling script will be paused until the called process terminates. Once complete, the batch script would check for the errorlevel variable set by the start command and exit as follows:

start /wait %windir%\\system32\\msiexec.exe /i myapp /quiet /forcerestart /log myapp_install.log
if %errorlevel% neq 0 exit /b %errorlevel%
...

Zipped files

For .zip or other zipped files, rename and unzip the contents of the application package to the desired destination.

Example install command:

rename myapp myapp.zip && mkdir C:\myapp && powershell.exe -Command "Expand-Archive -path myapp.zip -destinationpath C:\myapp"

Example remove command:

rmdir /S /Q C:\\myapp

Treat failure as deployment failure

The VM application extension always returns a success regardless of whether any VM app failed while being installed/updated/removed. The VM Application extension only reports the extension status as failure when there's a problem with the extension or the underlying infrastructure. This behavior is triggered by the "treat failure as deployment failure" flag, which is set to $false by default and can be changed to $true. The failure flag can be configured in PowerShell or CLI.

Troubleshooting VM Applications

To know whether a particular VM application was successfully added to the VM instance, check the message of the VM Application extension.

To learn more about getting the status of VM extensions, see Virtual machine extensions and features for Linux and Virtual machine extensions and features for Windows.

To get status of VM extensions, use Get-AzVM:

Get-AzVM -name <VM name> -ResourceGroupName <resource group name> -Status | convertto-json -Depth 10

To get status of scale set extensions, use Get-AzVMSS:

$result = Get-AzVmssVM -ResourceGroupName $rgName -VMScaleSetName $vmssName -InstanceView
$resultSummary  = New-Object System.Collections.ArrayList
$result | ForEach-Object {
    $res = @{ instanceId = $_.InstanceId; vmappStatus = $_.InstanceView.Extensions | Where-Object {$_.Name -eq "VMAppExtension"}}
    $resultSummary.Add($res) | Out-Null
}
$resultSummary | convertto-json -depth 5

Error messages

Next steps

• Learn how to create and deploy VM application packages.