Merge pull request #205406 from ericd-mst-github/erd-vm-applications-how-to

Erd vm applications how to

Author: 19BMG00

articles/virtual-machines/vm-applications-how-to.md

@@ -1,5 +1,5 @@
 ---
-title: Create and deploy VM application packages (preview)
+title: Create and deploy VM application packages
 description: Learn how to create and deploy VM Applications using an Azure Compute Gallery.
 ms.service: virtual-machines
 ms.subservice: gallery
@@ -11,15 +11,13 @@ ms.custom:
 
 ---
 
-# Create and deploy VM Applications (preview)
+# Create and deploy VM Applications
 
 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.
 
 
 > [!IMPORTANT]
-> **VM applications in Azure Compute Gallery** are currently in public preview.
-> This preview version is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. 
-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
+> Deploying **VM applications in Azure Compute Gallery** do not currently support using Azure policies.
 
 
 ## Prerequisites
@@ -144,8 +142,36 @@ Set a VM application to an existing VM using [az vm application set](/cli/azure/
 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 \
+  --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:
+
+```azurecli-interactive
+az vm applicaction set \
+	--resource-group myResourceGroup \
+	--name myVM \
+	--app-version-ids <appversionID1> <appversionID2> \
+	--treat-deployment-as-failure true
+```
+To verify application VM deployment status:
+
+```azurecli-interactive
+az vm get-instance-view -g myResourceGroup -n myVM --query "instanceView.extensions[?name == 'VMAppExtension']"
+```
+For verifying application VMSS deployment status:
+
+```azurecli-interactive
+$ids = az vmss list-instances -g myResourceGroup -n $vmssName --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']" 
+}
+```
+> [!NOTE]
+> The VMSS deployment status contains PowerShell syntax. Refer to the 2nd [vm-extension-delete](/cli/azure/vm/extension#az-vm-extension-delete-examples) example as there is precedence for it.
+
 
 ### [PowerShell](#tab/powershell)
 
@@ -179,6 +205,7 @@ New-AzGalleryApplicationVersion `
    -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" `
@@ -194,20 +221,23 @@ $applicationName = "myApp"
 $vmName = "myVM"
 $vm = Get-AzVM -ResourceGroupName $rgname -Name $vmName
 $appversion = Get-AzGalleryApplicationVersion `
-   -GalleryApplicationName $applicationname `
-   -GalleryName $galleryname `
+   -GalleryApplicationName $applicationName `
+   -GalleryName $galleryName `
    -Name $version `
-   -ResourceGroupName $rgname
+   -ResourceGroupName $rgName
 $packageid = $appversion.Id
 $app = New-AzVmGalleryApplication -PackageReferenceId $packageid
-Add-AzVmGalleryApplication -VM $vm -GalleryApplication $app
-Update-AzVM -ResourceGroupName $rgname -VM $vm
+Add-AzVmGalleryApplication -VM $vm -GalleryApplication $app -TreatFailureAsDeploymentFailure true
+Update-AzVM -ResourceGroupName $rgName -VM $vm
 ```
 
 Verify the application succeeded:
 
 ```powershell-interactive
-Get-AzVM -ResourceGroupName $rgname -VMName $vmname -Status
+$rgName = "myResourceGroup"
+$vmName = "myVM"
+$result = Get-AzVM -ResourceGroupName $rgName -VMName $vmName -Status
+$result.Extensions | Where-Object {$_.Name -eq "VMAppExtension"} | ConvertTo-Json
 ```
 
 ### [REST](#tab/rest2)
@@ -299,7 +329,8 @@ PUT
         {
           "order": 1,
           "packageReferenceId": "/subscriptions/{subscriptionId}/resourceGroups/<resource group>/providers/Microsoft.Compute/galleries/{gallery name}/applications/{application name}/versions/{version}",
-          "configurationReference": "{path to configuration storage blob}"
+          "configurationReference": "{path to configuration storage blob}",
+          "treatFailureAsDeploymentFailure": false
         }
       ]
     }
@@ -326,7 +357,8 @@ virtualMachineScaleSets/\<**VMSSName**\>?api-version=2019-03-01
           {
             "order": 1,
             "packageReferenceId": "/subscriptions/{subscriptionId}/resourceGroups/<resource group>/providers/Microsoft.Compute/galleries/{gallery name}/applications/{application name}/versions/{version}",
-            "configurationReference": "{path to configuration storage blob}"
+            "configurationReference": "{path to configuration storage blob}",
+            "treatFailureAsDeploymentFailure": false
           }
         ]
       }
@@ -344,6 +376,7 @@ virtualMachineScaleSets/\<**VMSSName**\>?api-version=2019-03-01
 | order | Optional. The order in which the applications should be deployed. See below. | Validate integer |
 | packageReferenceId | A reference the gallery application version | Valid application version reference |
 | configurationReference | Optional. The full url of a storage blob containing the configuration for this deployment. This will override any value provided for defaultConfiguration earlier. | Valid storage blob reference |
+| treatFailureAsDeploymentFailure | Optional. Provisioning status for VM App. When set to false, provisioning status will always show 'succeeded' regardless of app deployment failure. | True or False
 
 The order field may be used to specify dependencies between applications. The rules for order are the following:
 

articles/virtual-machines/vm-applications.md

@@ -1,5 +1,5 @@
 ---
-title: Overview of VM Applications in the Azure Compute Gallery (preview)
+title: Overview of VM Applications in the Azure Compute Gallery
 description: Learn more about VM application packages in an Azure Compute Gallery.
 author: ericd-mst-github
 ms.service: virtual-machines
@@ -13,14 +13,12 @@ ms.custom:
 
 ---
 
-# VM Applications overview (preview)
+# 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.
 
 > [!IMPORTANT]
-> **VM applications in Azure Compute Gallery** are currently in public preview.
-> This preview version is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. 
-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
+> Deploying **VM applications in Azure Compute Gallery** do not currently support using Azure policies.
 
 
 While you can create an image of a VM with apps pre-installed, 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.
@@ -116,11 +114,11 @@ The install/update/remove commands should be written assuming the application pa
 
 ## File naming
 
-During the preview, when the application file gets downloaded to the VM, the file name is the same as the name you use when you create the VM application. For example, if I name my VM application `myApp`, the file that will be downloaded to the VM will also be named `myApp`, regardless of what the file name is used in the storage account. If your VM application also has a configuration file, that file is the name of the application with `_config` appended. If `myApp` has a configuration file, it will be named `myApp_config`.
+When the application file gets downloaded to the VM, the file name is the same as the name you use when you create the VM application. For example, if I name my VM application `myApp`, the file that will be downloaded to the VM will also be named `myApp`, regardless of what the file name is used in the storage account. If your VM application also has a configuration file, that file is the name of the application with `_config` appended. If `myApp` has a configuration file, it will be named `myApp_config`.
 
 For example, if I name my VM application `myApp` when I create it in the Gallery, but it's stored as `myApplication.exe` in the storage account, when it gets downloaded to the VM the file name will be `myApp`. My install string should start by renaming the file to be whatever it needs to be to run on the VM (like myApp.exe).
 
-The install, update, and remove commands must be written with file naming in mind. 
+The install, update, and remove commands must be written with file naming in mind. The `configFileName` is assigned to the config file for the VM and `packageFileName` is the name assigned downloaded package on the VM. For more information regarding these additional VM settings, refer to [UserArtifactSettings](https://docs.microsoft.com/rest/api/compute/gallery-application-versions/create-or-update?tabs=HTTP#userartifactsettings) in our API docs.
 
 ## Command interpreter  
 
@@ -249,11 +247,13 @@ 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 will only report the extension status as failure when there's a problem with the extension or the underlying infrastructure. This 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](/powershell/module/az.compute/add-azvmgalleryapplication#-treatfailureasdeploymentfailure) or [CLI](/cli/azure/vm/application#-treat-deployment-as-failure).
 
-## Troubleshooting during preview
+## Troubleshooting VM Applications
 
-During the preview, the VM application extension always returns a success regardless of whether any VM app failed while being installed/updated/removed. The VM Application extension will only report the extension status as failure when there's a problem with the extension or the underlying infrastructure. To know whether a particular VM application was successfully added to the VM instance, check the message of the VM Application extension.
+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](extensions/features-linux.md#view-extension-status) and [Virtual machine extensions and features for Windows](extensions/features-windows.md#view-extension-status).
 
@@ -266,7 +266,13 @@ Get-AzVM -name <VM name> -ResourceGroupName <resource group name> -Status | conv
 To get status of scale set extensions, use [Get-AzVMSS](/powershell/module/az.compute/get-azvmss):
 
 ```azurepowershell-interactive
-Get-AzVmss -name <VMSS name> -ResourceGroupName <resource group name> -Status | convertto-json -Depth 10  
+$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