Additional details for SIG AutoOSUpgrade

Additional details for SIG AutoOSUpgrade

Author: mayanknayar

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

@@ -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,7 +39,7 @@ 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 image support is available [in preview](virtual-machine-scale-sets-automatic-upgrade.md#automatic-os-image-upgrade-for-custom-images-preview) for custom images deployed through [Shared Image Gallery](shared-image-galleries.md).
+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 platform SKUs are currently supported (and more are added periodically):
 
@@ -61,7 +61,7 @@ The following platform SKUs are currently supported (and more are added periodic
 
 ## 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.
@@ -146,9 +146,11 @@ 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 created with Shared Image Gallery images in that subscription.
+- 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.
@@ -216,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.
 
@@ -322,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`