Merge pull request #108128 from mayanknayar/master

Adding support for custom images through SIG

Author: GitHubber17

articles/virtual-machine-scale-sets/virtual-machine-scale-sets-automatic-upgrade.md

@@ -1,12 +1,12 @@
 ---
 title: Automatic OS image upgrades with Azure virtual machine scale sets
 description: Learn how to automatically upgrade the OS image on VM instances in a scale set
-author: shandilvarun
+author: mayanknayar
 tags: azure-resource-manager
 ms.service: virtual-machine-scale-sets
 ms.topic: conceptual
-ms.date: 07/16/2019
-ms.author: vashan
+ms.date: 03/18/2020
+ms.author: manayar
 
 ---
 # Azure virtual machine scale set automatic OS image upgrades
@@ -16,9 +16,9 @@ Enabling automatic OS image upgrades on your scale set helps ease update managem
 Automatic OS upgrade has the following characteristics:
 
 - Once configured, the latest OS image published by image publishers is automatically applied to the scale set without user intervention.
-- Upgrades batches of instances in a rolling manner each time a new platform image is published by the publisher.
+- Upgrades batches of instances in a rolling manner each time a new image is published by the publisher.
 - Integrates with application health probes and [Application Health extension](virtual-machine-scale-sets-health-extension.md).
-- Works for all VM sizes, and for both Windows and Linux platform images.
+- Works for all VM sizes, and for both Windows and Linux images.
 - You can opt out of automatic upgrades at any time (OS Upgrades can be initiated manually as well).
 - The OS Disk of a VM is replaced with the new OS Disk created with latest image version. Configured extensions and custom data scripts are run, while persisted data disks are retained.
 - [Extension sequencing](virtual-machine-scale-sets-extension-sequencing.md) is supported.
@@ -39,9 +39,9 @@ The upgrade process works as follows:
 The scale set OS upgrade orchestrator checks for the overall scale set health before upgrading every batch. While upgrading a batch, there could be other concurrent planned or unplanned maintenance activities that could impact the health of your scale set instances. In such cases if more than 20% of the scale set's instances become unhealthy, then the scale set upgrade stops at the end of current batch.
 
 ## Supported OS images
-Only certain OS platform images are currently supported. Custom images aren't currently supported.
+Only certain OS platform images are currently supported. Custom image support is available [in preview](virtual-machine-scale-sets-automatic-upgrade.md#automatic-os-image-upgrade-for-custom-images-preview) for custom images through [Shared Image Gallery](shared-image-galleries.md).
 
-The following SKUs are currently supported (and more are added periodically):
+The following platform SKUs are currently supported (and more are added periodically):
 
 | Publisher               | OS Offer      |  Sku               |
 |-------------------------|---------------|--------------------|
@@ -61,7 +61,7 @@ The following SKUs are currently supported (and more are added periodically):
 
 ## Requirements for configuring automatic OS image upgrade
 
-- The *version* property of the platform image must be set to *latest*.
+- The *version* property of the image must be set to *latest*.
 - Use application health probes or [Application Health extension](virtual-machine-scale-sets-health-extension.md) for non-Service Fabric scale sets.
 - Use Compute API version 2018-10-01 or higher.
 - Ensure that external resources specified in the scale set model are available and updated. Examples include SAS URI for bootstrapping payload in VM extension properties, payload in storage account, reference to secrets in the model, and more.
@@ -76,6 +76,86 @@ If you are using Service Fabric, ensure the following conditions are met:
 
 Ensure that durability settings are not mismatched on the Service Fabric cluster and Service Fabric extension, as a mismatch will result in upgrade errors. Durability levels can be modified per the guidelines outlined on [this page](../service-fabric/service-fabric-cluster-capacity.md#changing-durability-levels).
 
+
+## Automatic OS image upgrade for custom images (preview)
+
+> [!IMPORTANT]
+> Automatic OS image upgrade for custom images is currently in Public Preview. An opt-in procedure is needed to use the public preview functionality described below.
+> This preview version is provided without a service level agreement, and is not recommended 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/).
+
+Automatic OS image upgrade is available in preview for custom images deployed through [Shared Image Gallery](shared-image-galleries.md). Other custom images are not supported for automatic OS image upgrades.
+
+Enabling the preview functionality requires a one-time opt-in for the feature *AutomaticOSUpgradeWithGalleryImage* per subscription, as detailed below.
+
+### REST API
+The following example describes how to enable the preview for your subscription:
+
+```
+POST on `/subscriptions/{subscriptionId}/providers/Microsoft.Features/providers/Microsoft.Compute/features/AutomaticOSUpgradeWithGalleryImage/register?api-version=2015-12-01`
+```
+
+Feature registration can take up to 15 minutes. To check the registration status:
+
+```
+GET on `/subscriptions/{subscriptionId}/providers/Microsoft.Features/providers/Microsoft.Compute/features/AutomaticOSUpgradeWithGalleryImage?api-version=2015-12-01`
+```
+
+Once the feature has been registered for your subscription, complete the opt-in process by propagating the change into the Compute resource provider.
+
+```
+POST on `/subscriptions/{subscriptionId}/providers/Microsoft.Compute/register?api-version=2019-10-01`
+```
+
+### Azure PowerShell
+Use the [Register-AzProviderFeature](/powershell/module/az.resources/register-azproviderfeature) cmdlet to enable the preview for your subscription.
+
+```azurepowershell-interactive
+Register-AzProviderFeature -FeatureName AutomaticOSUpgradeWithGalleryImage -ProviderNamespace Microsoft.Compute
+```
+
+Feature registration can take up to 15 minutes. To check the registration status:
+
+```azurepowershell-interactive
+Get-AzProviderFeature -FeatureName AutomaticOSUpgradeWithGalleryImage -ProviderNamespace Microsoft.Compute
+```
+
+Once the feature has been registered for your subscription, complete the opt-in process by propagating the change into the Compute resource provider.
+
+```azurepowershell-interactive
+Register-AzResourceProvider -ProviderNamespace Microsoft.Compute
+```
+
+### Azure CLI 2.0
+Use [az feature register](/cli/azure/feature#az-feature-register) to enable the preview for your subscription.
+
+```azurecli-interactive
+az feature register --namespace Microsoft.Compute --name AutomaticOSUpgradeWithGalleryImage
+```
+
+Feature registration can take up to 15 minutes. To check the registration status:
+
+```azurecli-interactive
+az feature show --namespace Microsoft.Compute --name AutomaticOSUpgradeWithGalleryImage
+```
+
+Once the feature has been registered for your subscription, complete the opt-in process by propagating the change into the Compute resource provider.
+
+```azurecli-interactive
+az provider register --namespace Microsoft.Compute
+```
+
+### Additional requirements for custom images
+- The opt-in process described above needs to be completed only once per subscription. Post opt-in completion, automatic OS upgrades can be enabled for any scale set in that subscription.
+- The Shared Image Gallery can be in any subscription and does not require to be opted-in separately. Only the scale set subscription requires the feature opt-in.
+- The configuration process for automatic OS image upgrade is the same for all scale sets as detailed in the [configuration section](virtual-machine-scale-sets-automatic-upgrade.md#configure-automatic-os-image-upgrade) of this page.
+- Scale sets instances configured for automatic OS image upgrades will be upgraded to the latest version of the Shared Image Gallery image when a new version of the image is published and [replicated](shared-image-galleries.md#replication) to the region of that scale set. If the new image is not replicated to the region where the scale is deployed, the scale set instances will not be upgraded to the latest version. Regional image replication allows you to control the rollout of the new image for your scale sets.
+- The new image version should not be excluded from the latest version for that gallery image. Image versions excluded from the gallery image's latest version are not rolled out to the scale set through automatic OS image upgrade.
+
+> [!NOTE]
+>It can take up to 2 hours for a scale set to get the first image rollout after the scale set is configured for automatic OS upgrades. This is a one-time delay per scale set. Subsequent image rollouts are applied to the scale set without this delay.
+
+
 ## Configure automatic OS image upgrade
 To configure automatic OS image upgrade, ensure that the *automaticOSUpgradePolicy.enableAutomaticOSUpgrade* property is set to *true* in the scale set model definition.
 
@@ -138,13 +218,13 @@ The load-balancer probe can be referenced in the *networkProfile* of the scale s
 > [!NOTE]
 > When using Automatic OS Upgrades with Service Fabric, the new OS image is rolled out Update Domain by Update Domain to maintain high availability of the services running in Service Fabric. To utilize Automatic OS Upgrades in Service Fabric your cluster must be configured to use the Silver Durability Tier or higher. For more information on the durability characteristics of Service Fabric clusters, please see [this documentation](https://docs.microsoft.com/azure/service-fabric/service-fabric-cluster-capacity#the-durability-characteristics-of-the-cluster).
 
-### Keep credentials up-to-date
+### Keep credentials up to date
 If your scale set uses any credentials to access external resources, such as a VM extension configured to use a SAS token for storage account, then ensure that the credentials are updated. If any credentials, including certificates and tokens, have expired, the upgrade will fail and the first batch of VMs will be left in a failed state.
 
 The recommended steps to recover VMs and re-enable automatic OS upgrade if there's a resource authentication failure are:
 
 * Regenerate the token (or any other credentials) passed into your extension(s).
-* Ensure that any credential used from inside the VM to talk to external entities is up-to-date.
+* Ensure that any credential used from inside the VM to talk to external entities is up to date.
 * Update extension(s) in the scale set model with any new tokens.
 * Deploy the updated scale set, which will update all VM instances including the failed ones.
 
@@ -244,7 +324,7 @@ For specific cases where you do not want to wait for the orchestrator to apply t
 > Manual trigger of OS image upgrades does not provide automatic rollback capabilities. If an instance does not recover its health after an upgrade operation, its previous OS disk can't be restored.
 
 ### REST API
-Use the [Start OS Upgrade](/rest/api/compute/virtualmachinescalesetrollingupgrades/startosupgrade) API call to start a rolling upgrade to move all virtual machine scale set instances to the latest available platform image OS version. Instances that are already running the latest available OS version are not affected. The following example details how you can start a rolling OS upgrade on a scale set named *myScaleSet* in the resource group named *myResourceGroup*:
+Use the [Start OS Upgrade](/rest/api/compute/virtualmachinescalesetrollingupgrades/startosupgrade) API call to start a rolling upgrade to move all virtual machine scale set instances to the latest available image OS version. Instances that are already running the latest available OS version are not affected. The following example details how you can start a rolling OS upgrade on a scale set named *myScaleSet* in the resource group named *myResourceGroup*:
 
 ```
 POST on `/subscriptions/subscription_id/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myScaleSet/osRollingUpgrade?api-version=2018-10-01`