Skip to content

Commit 4ab13c0

Browse files
v-ccolinv-ccolin
authored
Merge pull request #267524 from wenxiangMS/main
Add Auto OS Upgrade doc
2 parents 63a7867 + 18d7ff6 commit 4ab13c0

File tree

2 files changed

+225
-0
lines changed

2 files changed

+225
-0
lines changed

‎articles/batch/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,8 @@
198198
href: simplified-node-communication-pool-no-public-ip.md
199199
- name: Create a pool with ephemeral OS disk nodes
200200
href: create-pool-ephemeral-os-disk.md
201+
- name: Create an Azure Batch pool with Auto OS Upgrade
202+
href: batch-upgrade-policy.md
201203
- name: Use extensions with pools
202204
href: create-pool-extensions.md
203205
- name: Configure managed identities

‎articles/batch/batch-upgrade-policy.md

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
title: Provision a pool with Auto OS Upgrade
3+
description: Learn how to create a Batch pool with Auto OS Upgrade so that customers can have control over their OS upgrade strategy to ensure safe, workload-aware OS upgrade deployments.
4+
ms.topic: how-to
5+
ms.date: 02/29/2024
6+
ms.custom:
7+
---
8+
9+
# Create an Azure Batch pool with Automatic Operating System (OS) Upgrade
10+
11+
> [!IMPORTANT]
12+
> - Support for pools with Auto OS Upgrade in Azure Batch is currently in public preview, and is currently controlled by an account-level feature flag. If you want to use this feature, please start a [support request](../azure-portal/supportability/how-to-create-azure-support-request.md) and provide your batch account to request its activation.
13+
> - This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
14+
> - For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
15+
16+
When you create an Azure Batch pool, you can provision the pool with nodes that have Auto OS Upgrade enabled. This article explains how to set up a Batch pool with Auto OS Upgrade.
17+
18+
## Why use Auto OS Upgrade?
19+
20+
Auto OS Upgrade is used to implement an automatic operating system upgrade strategy and control within Azure Batch Pools. Here are some reasons for using Auto OS Upgrade:
21+
22+
- **Security.** Auto OS Upgrade ensures timely patching of vulnerabilities and security issues within the operating system image, to enhance the security of compute resources. It helps prevent potential security vulnerabilities from posing a threat to applications and data.
23+
- **Minimized Availability Disruption.** Auto OS Upgrade is used to minimize the availability disruption of compute nodes during OS upgrades. It is achieved through task-scheduling-aware upgrade deferral and support for rolling upgrades, ensuring that workloads experience minimal disruption.
24+
- **Flexibility.** Auto OS Upgrade allows you to configure your automatic operating system upgrade strategy, including percentage-based upgrade coordination and rollback support. It means you can customize your upgrade strategy to meet your specific performance and availability requirements.
25+
- **Control.** Auto OS Upgrade provides you with control over your operating system upgrade strategy to ensure secure, workload-aware upgrade deployments. You can tailor your policy configurations to meet the specific needs of your organization.
26+
27+
In summary, the use of Auto OS Upgrade helps improve security, minimize availability disruptions, and provide both greater control and flexibility for your workloads.
28+
29+
## How does Auto OS Upgrade work?
30+
31+
When upgrading images, VMs in Azure Batch Pool will follow roughly the same work flow as VirtualMachineScaleSets. To learn more about the detailed steps involved in the Auto OS Upgrade process for VirtualMachineScaleSets, you can refer to [VirtualMachineScaleSet page](../virtual-machine-scale-sets/virtual-machine-scale-sets-automatic-upgrade.md#how-does-automatic-os-image-upgrade-work).
32+
33+
However, if *automaticOSUpgradePolicy.osRollingUpgradeDeferral* is set to 'true' and an upgrade becomes available when a batch node is actively running tasks, the upgrade will be delayed until all tasks have been completed on the node.
34+
35+
> [!Note]
36+
> If a pool has enabled *osRollingUpgradeDeferral*, its nodes will be displayed as *upgradingos* state during the upgrade process. Please note that the *upgradingos* state will only be shown when you are using the the API version of 2024-02-01 or later. If you're using an old API version to call *GetTVM/ListTVM*, the node will be in a *rebooting* state when upgrading.
37+
38+
## Supported OS images
39+
Only certain OS platform images are currently supported for automatic upgrade. For detailed images list, you can get from [VirtualMachineScaleSet page](../virtual-machine-scale-sets/virtual-machine-scale-sets-automatic-upgrade.md#supported-os-images).
40+
41+
## Requirements
42+
43+
* The version property of the image must be set to **latest**.
44+
* For Batch Management API, use API version 2024-02-01 or higher. For Batch Service API, use API version 2024-02-01.19.0 or higher.
45+
* Ensure that external resources specified in the pool 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.
46+
* If you are using the property *virtualMachineConfiguration.windowsConfiguration.enableAutomaticUpdates*, this property must set to 'false' in the pool definition. The enableAutomaticUpdates property enables in-VM patching where "Windows Update" applies operating system patches without replacing the OS disk. With automatic OS image upgrades enabled, an extra patching process through Windows Update isn't required.
47+
48+
### Additional requirements for custom images
49+
50+
* When a new version of the image is published and replicated to the region of that pool, the VMs will be upgraded to the latest version of the Azure Compute Gallery image. If the new image isn't replicated to the region where the pool is deployed, the VM instances won't be upgraded to the latest version. Regional image replication allows you to control the rollout of the new image for your VMs.
51+
* The new image version shouldn't be excluded from the latest version for that gallery image. Image versions excluded from the gallery image's latest version won't be rolled out through automatic OS image upgrade.
52+
53+
## Configure Auto OS Upgrade
54+
55+
If you intend to implement Auto OS Upgrades within a pool, it's essential to configure the **UpgradePolicy** field during the pool creation process. To configure automatic OS image upgrades, make sure that the *automaticOSUpgradePolicy.enableAutomaticOSUpgrade* property is set to 'true' in the pool definition.
56+
57+
> [!Note]
58+
> **Upgrade Policy mode** and **Automatic OS Upgrade Policy** are separate settings and control different aspects of the provisioned scale set by Azure Batch. The Upgrade Policy mode will determine what happens to existing instances in scale set. However, Automatic OS Upgrade Policy enableAutomaticOSUpgrade is specific to the OS image and tracks changes the image publisher has made and determines what happens when there is an update to the image.
59+
60+
> [!IMPORTANT]
61+
> If you are using [user subscription](batch-account-create-portal.md#additional-configuration-for-user-subscription-mode), it's essential to note that a subscription feature **Microsoft.Compute/RollingUpgradeDeferral** is required for your subscription to be registered. You cannot use *osRollingUpgradeDeferral* unless this feature is registered. To enable this feature, please [manually register](../azure-resource-manager/management/preview-features.md) it on your subscription.
62+
63+
### REST API
64+
The following example describes how to create a pool with Auto OS Upgrade via REST API:
65+
66+
```http
67+
PUT https://management.azure.com/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupName>/providers/Microsoft.Batch/batchAccounts/<batchaccountname>/pools/<poolname>?api-version=2024-02-01
68+
```
69+
70+
Request Body
71+
72+
```json
73+
{
74+
"name": "test1",
75+
"type": "Microsoft.Batch/batchAccounts/pools",
76+
"parameters": {
77+
"properties": {
78+
"vmSize": "Standard_d4s_v3",
79+
"deploymentConfiguration": {
80+
"virtualMachineConfiguration": {
81+
"imageReference": {
82+
"publisher": "MicrosoftWindowsServer",
83+
"offer": "WindowsServer",
84+
"sku": "2019-datacenter-smalldisk",
85+
"version": "latest"
86+
},
87+
"nodePlacementConfiguration": {
88+
"policy": "Zonal"
89+
},
90+
"nodeAgentSKUId": "batch.node.windows amd64",
91+
"windowsConfiguration": {
92+
"enableAutomaticUpdates": false
93+
}
94+
}
95+
},
96+
"scaleSettings": {
97+
"fixedScale": {
98+
"targetDedicatedNodes": 2,
99+
"targetLowPriorityNodes": 0
100+
}
101+
},
102+
"upgradePolicy": {
103+
"mode": "Automatic",
104+
"automaticOSUpgradePolicy": {
105+
"disableAutomaticRollback": true,
106+
"enableAutomaticOSUpgrade": true,
107+
"useRollingUpgradePolicy": true,
108+
"osRollingUpgradeDeferral": true
109+
},
110+
"rollingUpgradePolicy": {
111+
"enableCrossZoneUpgrade": true,
112+
"maxBatchInstancePercent": 20,
113+
"maxUnhealthyInstancePercent": 20,
114+
"maxUnhealthyUpgradedInstancePercent": 20,
115+
"pauseTimeBetweenBatches": "PT0S",
116+
"prioritizeUnhealthyInstances": false,
117+
"rollbackFailedInstancesOnPolicyBreach": false
118+
}
119+
}
120+
}
121+
}
122+
}
123+
```
124+
125+
### SDK (C#)
126+
The following code snippet shows an example of how to use the [Batch .NET](https://www.nuget.org/packages/Microsoft.Azure.Batch/) client library to create a pool of Auto OS Upgrade via C# codes. For more details about Batch .NET, view the [reference documentation](/dotnet/api/microsoft.azure.batch).
127+
128+
```csharp
129+
public async Task CreateUpgradePolicyPool()
130+
{
131+
// Authenticate
132+
var clientId = Environment.GetEnvironmentVariable("CLIENT_ID");
133+
var clientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET");
134+
var tenantId = Environment.GetEnvironmentVariable("TENANT_ID");
135+
var subscriptionId = Environment.GetEnvironmentVariable("SUBSCRIPTION_ID");
136+
ClientSecretCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
137+
ArmClient client = new ArmClient(credential, subscriptionId);
138+
139+
// Get an existing Batch account
140+
string resourceGroupName = "testrg";
141+
string accountName = "testaccount";
142+
ResourceIdentifier batchAccountResourceId = BatchAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
143+
BatchAccountResource batchAccount = client.GetBatchAccountResource(batchAccountResourceId);
144+
145+
// get the collection of this BatchAccountPoolResource
146+
BatchAccountPoolCollection collection = batchAccount.GetBatchAccountPools();
147+
148+
// Define the pool
149+
string poolName = "testpool";
150+
BatchAccountPoolData data = new BatchAccountPoolData()
151+
{
152+
VmSize = "Standard_d4s_v3",
153+
DeploymentConfiguration = new BatchDeploymentConfiguration()
154+
{
155+
VmConfiguration = new BatchVmConfiguration(new BatchImageReference()
156+
{
157+
Publisher = "MicrosoftWindowsServer",
158+
Offer = "WindowsServer",
159+
Sku = "2019-datacenter-smalldisk",
160+
Version = "latest",
161+
},
162+
nodeAgentSkuId: "batch.node.windows amd64")
163+
{
164+
NodePlacementPolicy = BatchNodePlacementPolicyType.Zonal,
165+
IsAutomaticUpdateEnabled = false
166+
},
167+
},
168+
ScaleSettings = new BatchAccountPoolScaleSettings()
169+
{
170+
FixedScale = new BatchAccountFixedScaleSettings()
171+
{
172+
TargetDedicatedNodes = 2,
173+
TargetLowPriorityNodes = 0,
174+
},
175+
},
176+
UpgradePolicy = new UpgradePolicy()
177+
{
178+
Mode = UpgradeMode.Automatic,
179+
AutomaticOSUpgradePolicy = new AutomaticOSUpgradePolicy()
180+
{
181+
DisableAutomaticRollback = true,
182+
EnableAutomaticOSUpgrade = true,
183+
UseRollingUpgradePolicy = true,
184+
OSRollingUpgradeDeferral = true
185+
},
186+
RollingUpgradePolicy = new RollingUpgradePolicy()
187+
{
188+
EnableCrossZoneUpgrade = true,
189+
MaxBatchInstancePercent = 20,
190+
MaxUnhealthyInstancePercent = 20,
191+
MaxUnhealthyUpgradedInstancePercent = 20,
192+
PauseTimeBetweenBatches = "PT0S",
193+
PrioritizeUnhealthyInstances = false,
194+
RollbackFailedInstancesOnPolicyBreach = false,
195+
}
196+
}
197+
};
198+
199+
ArmOperation<BatchAccountPoolResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, poolName, data);
200+
BatchAccountPoolResource result = lro.Value;
201+
202+
// the variable result is a resource, you could call other operations on this instance as well
203+
// but just for demo, we get its data from this resource instance
204+
BatchAccountPoolData resourceData = result.Data;
205+
// for demo we just print out the id
206+
Console.WriteLine($"Succeeded on id: {resourceData.Id}");
207+
}
208+
```
209+
210+
## FAQs
211+
212+
- How can I enable Auto OS Upgrade?
213+
214+
Start a [support request](../azure-portal/supportability/how-to-create-azure-support-request.md) and provide your batch account to request its activation.
215+
216+
- Will my tasks be disrupted if I enabled Auto OS Upgrade?
217+
218+
Tasks won't be disrupted when *automaticOSUpgradePolicy.osRollingUpgradeDeferral* is set to 'true'. In that case, the upgrade will be postponed until node becomes idle. Otherwise, node will upgrade when it receives a new OS version, regardless of whether it is currently running a task or not. So we strongly advise enabling *automaticOSUpgradePolicy.osRollingUpgradeDeferral*.
219+
220+
## Next steps
221+
222+
- Learn how to use a [managed image](batch-custom-images.md) to create a pool.
223+
- Learn how to use the [Azure Compute Gallery](batch-sig-images.md) to create a pool.

0 commit comments

Comments
 (0)