Create and deploy VM Application

$inputFile = <the file you want to pad>

$fileInfo = Get-Item -Path $inputFile

$remainder = $fileInfo.Length % 512

if ($remainder -ne 0){

    $difference = 512 - $remainder

    $bytesToPad = [System.Byte[]]::CreateInstance([System.Byte], $difference)

    Add-Content -Path $inputFile -Value $bytesToPad -Encoding Byte
    }

inputFile="<the file you want to pad>"

# Get the file size
fileSize=$(stat -c %s "$inputFile")

# Calculate the remainder when divided by 512
remainder=$((fileSize % 512))

if [ "$remainder" -ne 0 ]; then
    # Calculate how many bytes to pad
    difference=$((512 - remainder))
    
    # Create padding (empty bytes)
    dd if=/dev/zero bs=1 count=$difference >> "$inputFile"
fi

1. Go to the Azure portal, then search for and select Azure Compute Gallery.
2. Select the gallery you want to use from the list.
3. On the page for your gallery, select Add from the top of the page and then select VM application definition from the drop-down. The Create a VM application definition page opens.
4. In the Basics tab, enter a name for your application and choose whether the application is for VMs running Linux or Windows.
5. Select the Publishing options tab if you want to specify any of the following optional settings for your VM Application definition:
   • A description of the VM Application definition.
   • End of life date
   • Link to an End User License Agreement (EULA)
   • URI of a privacy statement
   • URI for release notes
6. When you're done, select Review + create.
7. When validation completes, select Create to have the definition deployed.
8. Once the deployment is complete, select Go to resource.
9. On the page for the application, select Create a VM application version. The Create a VM Application Version page opens.
10. Enter a version number like 1.0.0.
11. Select the region where your application packages are uploaded.
12. Under Source application package, select Browse. Select the storage account, then the container where your package is located. Select the package from the list and then select Select when you're done. Alternatively, you can paste the SAS URI in this field if preferred.
13. Provide the 'Install script'. You can also provide the 'Uninstall script' and the 'Update script'. See the Overview for information on how to create the scripts.
14. If you have a default configuration file uploaded to a storage account, you can select it in Default configuration.
15. Select Exclude from latest if you don't want this version to appear as the latest version when you create a VM.
16. For End of life date, choose a date in the future to track when this version should be retired. It isn't deleted or removed automatically, it's only for your own tracking.
17. To replicate this version to other regions, select the Replication tab, add more regions, and make changes to the number of replicas per region. The original region where your version was created must be in the list and can't be removed.
18. When you're done making changes, select Review + create at the bottom of the page.
19. When validation shows as passed, select Create to deploy your VM application version.

Create the VM Application definition using New-AzGalleryApplication. In this example, we're creating a Linux app named myApp in the myGallery Azure Compute Gallery and in the myGallery resource group. Replace the values for variables as needed.

$galleryName = "myGallery"
$rgName = "myResourceGroup"
$applicationName = "myApp"
$description = "Backend Linux application for finance."
New-AzGalleryApplication `
  -ResourceGroupName $rgName `
  -GalleryName $galleryName `
  -Location "East US" `
  -Name $applicationName `
  -SupportedOSType Linux `
  -Description $description

Create a version of your VM Application using New-AzGalleryApplicationVersion. Allowed characters for version are numbers and periods. Numbers must be within the range of a 32-bit integer. Format: MajorVersion.MinorVersion.Patch.

In this example, we're creating version number 1.0.0. Replace the values of the variables as needed.

$galleryName = "myGallery"
$rgName = "myResourceGroup"
$applicationName = "myApp"
$version = "1.0.0"
New-AzGalleryApplicationVersion `
   -ResourceGroupName $rgName `
   -GalleryName $galleryName `
   -GalleryApplicationName $applicationName `
   -Name $version `
   -PackageFileLink "https://<storage account name>.blob.core.windows.net/<container name>/<filename>" `
   -DefaultConfigFileLink "https://<storage account name>.blob.core.windows.net/<container name>/<filename>" `
   -Location "East US" `
   -Install "mv myApp .\myApp\myApp" `
   -Remove "rm .\myApp\myApp" `

VM applications require Azure CLI version 2.30.0 or later.

Create the VM application definition using 'az sig gallery-application create'. In this example, we're creating a VM application definition named myApp for Linux-based VMs.

az sig gallery-application create \
    --application-name myApp \
    --gallery-name myGallery \
    --resource-group myResourceGroup \
    --os-type Linux \
    --location "East US"

Create a VM application version using 'az sig gallery-application version create'. Allowed characters for version are numbers and periods. Numbers must be within the range of a 32-bit integer. Format: MajorVersion.MinorVersion.Patch.

Replace the values of the parameters with your own.

az sig gallery-application version create \
   --version-name 1.0.0 \
   --application-name myApp \
   --gallery-name myGallery \
   --location "East US" \
   --resource-group myResourceGroup \
   --package-file-link "https://<storage account name>.blob.core.windows.net/<container name>/<filename>" \
   --install-command "mv myApp .\myApp\myApp" \
   --remove-command "rm .\myApp\myApp" \
   --update-command  "mv myApp .\myApp\myApp" \
   --default-configuration-file-link "https://<storage account name>.blob.core.windows.net/<container name>/<filename>"\

Create the VM Application definition using the 'create gallery application API'

PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/galleries/{galleryName}/applications/{applicationName}?api-version=2024-03-03

{
    "location": "West US",
    "name": "myApp",
    "properties": {
        "supportedOSType": "Windows | Linux",
        "endOfLifeDate": "2020-01-01",
	"description": "Description of the App",
	"eula": "Link to End-User License Agreement (EULA)",
	"privacyStatementUri": "Link to privacy statement for the application",
	"releaseNoteUri": "Link to release notes for the application"
    }
}

Create a VM application version using the 'create gallery application version API'.

PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/galleries/{galleryName}/applications/{applicationName}/versions/{versionName}?api-version=2024-03-03

{
  "location": "$location",
  "properties": {
    "publishingProfile": {
      "source": {
        "mediaLink": "$mediaLink",
        "defaultConfigurationLink": "$configLink"
      },
      "manageActions": {
        "install": "echo installed",
        "remove": "echo removed",
        "update": "echo update"
      },
      "targetRegions": [
        {
          "name": "West US",
          "regionalReplicaCount": 1
        },
	{
	  "name": "East US"
	}
      ]
      "endofLifeDate": "datetime",
      "replicaCount": 1,
      "excludeFromLatest": false,
      "storageAccountType": "PremiumV2_LRS | Premium_LRS | Standard_LRS | Standard_ZRS"
      "safetyProfile": {
	"allowDeletionOfReplicatedLocations": false
      }
      "settings": {
	"scriptBehaviorAfterReboot": "None | Rerun",
	"configFileName": "$appConfigFileName",
	"packageFileName": "$appPackageFileName"
      }
   }
}

Now you can create a VM and deploy the VM application to it using the portal. Just create the VM as usual, and under the Advanced tab, choose Select a VM application to install.

Select the VM application from the list and then select Save at the bottom of the page.

If you have more than one VM application to install, you can set the install order for each VM application back on the Advanced tab.

You can also deploy the VM application to currently running VMs. Select the Extensions + applications option under Settings in the left menu when viewing the VM details in the portal.

Choose VM applications and then select Add application to add your VM application.

Select the VM application from the list and then select Save at the bottom of the page.

Set a VM application to an existing VM using 'az vm application set' and replace the values of the parameters with your own.

az vm application set \
	--resource-group myResourceGroup \
	--name myVM \
  	--app-version-ids /subscriptions/{subID}/resourceGroups/MyResourceGroup/providers/Microsoft.Compute/galleries/myGallery/applications/myApp/versions/1.0.0 \
  	--treat-deployment-as-failure true

For setting multiple applications on a VM:

az vm application set \
	--resource-group myResourceGroup \
	--name myVM \
	--app-version-ids /subscriptions/{subId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/galleries/myGallery/applications/myApp/versions/1.0.0 /subscriptions/{subId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/galleries/myGallery/applications/myApp2/versions/1.0.1 \
	--treat-deployment-as-failure true true

To add an application to a Virtual Machine Scale Set, use 'az vmss application set':

az vmss application set \
	--resource-group myResourceGroup \
	--name myVmss \
	--app-version-ids /subscriptions/{subId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/galleries/myGallery/applications/myApp/versions/1.0.0 \
	--treat-deployment-as-failure true

To add multiple applications to a Virtual Machine Scale Set:

az vmss application set \
	--resource-group myResourceGroup \
	--name myVmss
	--app-version-ids /subscriptions/{subId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/galleries/myGallery/applications/myApp/versions/1.0.0 /subscriptions/{subId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/galleries/myGallery/applications/myApp2/versions/1.0.0 \
	--treat-deployment-as-failure true

To add the application to an existing VM, get the application version and use that to get the VM application version ID. Use the ID to add the application to the VM configuration.

$galleryName = "myGallery"
$rgName = "myResourceGroup"
$applicationName = "myApp"
$version = "1.0.0"
$vmName = "myVM"
$vm = Get-AzVM -ResourceGroupName $rgname -Name $vmName
$appVersion = Get-AzGalleryApplicationVersion `
   -GalleryApplicationName $applicationName `
   -GalleryName $galleryName `
   -Name $version `
   -ResourceGroupName $rgName
$packageId = $appVersion.Id
$app = New-AzVmGalleryApplication -PackageReferenceId $packageId
Add-AzVmGalleryApplication -VM $vm -GalleryApplication $app -TreatFailureAsDeploymentFailure true
Update-AzVM -ResourceGroupName $rgName -VM $vm

To add the application to a Virtual Machine Scale Set:

$vmss = Get-AzVmss -ResourceGroupName $rgname -Name $vmssName
$appVersion = Get-AzGalleryApplicationVersion `
   -GalleryApplicationName $applicationName `
   -GalleryName $galleryName `
   -Name $version `
   -ResourceGroupName $rgName
$packageId = $appVersion.Id
$app = New-AzVmssGalleryApplication -PackageReferenceId $packageId
Add-AzVmssGalleryApplication -VirtualMachineScaleSetVM $vmss.VirtualMachineProfile -GalleryApplication $app
Update-AzVmss -ResourceGroupName $rgName -VirtualMachineScaleSet $vmss -VMScaleSetName $vmssName

To add a VM application version to a VM, perform a PUT on the VM.

PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{VMName}?api-version=2024-03-03

{
  "properties": {
    "applicationProfile": {
      "galleryApplications": [
        {
          "order": 1,
          "packageReferenceId": "/subscriptions/{subscriptionId}/resourceGroups/<resource group>/providers/Microsoft.Compute/galleries/{gallery name}/applications/{application name}/versions/{version | latest}",
          "configurationReference": "{path to configuration storage blob}",
          "treatFailureAsDeploymentFailure": false
        }
      ]
    }
  },
  "name": "{vm name}",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resource group}/providers/Microsoft.Compute/virtualMachines/{vm name}",
  "location": "{vm location}"
}

To apply the VM application to a uniform scale set:

PUT
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{VMSSName}?api-version=2024-03-03

{
  "properties": {
    "virtualMachineProfile": {
      "applicationProfile": {
        "galleryApplications": [
          {
            "order": 1,
            "packageReferenceId": "/subscriptions/{subscriptionId}/resourceGroups/<resource group>/providers/Microsoft.Compute/galleries/{gallery name}/applications/{application name}/versions/{version | latest}",
            "configurationReference": "{path to configuration storage blob}",
            "treatFailureAsDeploymentFailure": false
          }
        ]
      }
    }
  },
  "name": "{vm name}",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resource group}/providers/Microsoft.Compute/virtualMachines/{vm name}",
  "location": "{vm location}"
}

The order field may be used to specify dependencies between applications. The rules for order are as follows:

The response includes the full VM model. The following are the relevant parts.

{
  "name": "{vm name}",
  "id": "{vm id}",
  "type": "Microsoft.Compute/virtualMachines",
  "location": "{vm location}",
  "properties": {
    "applicationProfile": {
      "galleryApplications": ""
    },
    "provisioningState": "Updating"
  },
  "resources": [
    {
      "name": "VMAppExtension",
      "id": "{extension id}",
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "location": "centraluseuap",
      "properties": "@{autoUpgradeMinorVersion=True; forceUpdateTag=7c4223fc-f4ea-4179-ada8-c8a85a1399f5; provisioningState=Creating; publisher=Microsoft.CPlat.Core; type=VMApplicationManagerLinux; typeHandlerVersion=1.0; settings=}"
    }
  ]
}

To show the VM application status, go to the Extensions + applications tab/settings and check the status of the VMAppExtension:

To show the VM application status for scale set, go to the Azure portal Virtual Machine Scale Sets page, then the Instances section, select one of the scales sets listed, then go to VMAppExtension:

To verify application deployment status on a VM, use 'az vm get-instance-view':

az vm get-instance-view -g myResourceGroup -n myVM --query "instanceView.extensions[?name == 'VMAppExtension']"

To verify application deployment status on Virtual Machine Scale Set, use 'az vmss get-instance-view':

az vmss get-instance-view --ids (az vmss list-instances -g myResourceGroup -n myVmss --query "[*].id" -o tsv) --query "[*].extensions[?name == 'VMAppExtension']"

$ids = az vmss list-instances -g myResourceGroup -n myVmss --query "[*].{id: id, instanceId: instanceId}" | ConvertFrom-Json
$ids | Foreach-Object {
    $iid = $_.instanceId
    Write-Output "instanceId: $iid" 
    az vmss get-instance-view --ids $_.id --query "extensions[?name == 'VMAppExtension']" 
}

Verify the application succeeded:

$rgName = "myResourceGroup"
$vmName = "myVM"
$result = Get-AzVM -ResourceGroupName $rgName -VMName $vmName -Status
$result.Extensions | Where-Object {$_.Name -eq "VMAppExtension"} | ConvertTo-Json

To verify on your Virtual Machine Scale Set:

$rgName = "myResourceGroup"
$vmssName = "myVMss"
$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

If the VM application isn't installed on the VM, the value is empty.

To get the result of VM instance view:

GET
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{VMName}/instanceView?api-version=2024-03-03

The result looks like this:

{
    ...
    "extensions"  [
    ...
        {
            "name":  "VMAppExtension",
            "type":  "Microsoft.CPlat.Core.VMApplicationManagerLinux",
            "typeHandlerVersion":  "1.0.9",
            "statuses":  [
                            {
                                "code":  "ProvisioningState/succeeded",
                                "level":  "Info",
                                "displayStatus":  "Provisioning succeeded",
                                "message":  "Enable succeeded: {\n \"CurrentState\": [\n  {\n   \"applicationName\": \"doNothingLinux\",\n   \"version\": \"1.0.0\",\n   \"result\": \"Install SUCCESS\"\n  },\n  {
        \n   \"applicationName\": \"badapplinux\",\n   \"version\": \"1.0.0\",\n   \"result\": \"Install FAILED Error executing command \u0027exit 1\u0027: command terminated with exit status=1\"\n  }\n ],\n \"ActionsPerformed\": []\n}
        "
                            }
                        ]
        }
    ...
    ]
}

The VM App status is in the status message of the result of the VM App extension in the instance view.

To get the status for the application on the Virtual Machine Scale Set:

GET
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/ virtualMachineScaleSets/{VMSSName}/virtualMachines/{instanceId}/instanceView?api-version=2019-03-01

The output is similar to the VM example earlier.

Delete the VM Application version:

Remove-AzGalleryApplicationVersion -ResourceGroupName $rgNmae -GalleryName $galleryName -GalleryApplicationName $galleryApplicationName -Name $name

Delete the VM Application after all its versions are deleted:

Remove-AzGalleryApplication -ResourceGroupName $rgNmae -GalleryName $galleryName -Name $name

Delete the VM Application version:

az sig gallery-application version delete --resource-group $rg-name --gallery-name $gallery-name --application-name $app-name --version-name $version-name

Delete the VM Application after all its versions are deleted:

az sig gallery-application delete --resource-group $rg-name --gallery-name $gallery-name --application-name $app-name

Delete the VM Application version:

DELETE
https://by8hpd4gja.proxynodejs.usequeue.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/galleries/{galleryName}/applications/{galleryApplicationName}/versions/{galleryApplicationVersionName}?api-version=2024-03-03

Delete the VM Application after all its versions are deleted:

DELETE
https://by8hpd4gja.proxynodejs.usequeue.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/galleries/{galleryName}/applications/{galleryApplicationName}?api-version=2024-03-03

Next steps

Learn more about Azure VM Applications.