Skip to content

Commit ce8775d

Browse files
alfparkalfpark
committed
Add article for updating Batch pool properties
1 parent 5b4b63d commit ce8775d

File tree

2 files changed

+197
-8
lines changed

2 files changed

+197
-8
lines changed

‎articles/batch/TOC.yml

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -166,16 +166,18 @@
166166
href: resource-files.md
167167
- name: Create and manage pools
168168
items:
169+
- name: Choose a VM size for compute nodes
170+
href: batch-pool-vm-sizes.md
171+
- name: Update pool properties
172+
href: batch-pool-update-properties.md
173+
- name: Create a pool in a virtual network
174+
displayName: vNet
175+
href: batch-virtual-network.md
169176
- name: Use simplified compute node communication
170177
href: simplified-compute-node-communication.md
171178
- name: Autoscale compute nodes
172179
displayName: scaling, dynamic, formula
173180
href: batch-automatic-scaling.md
174-
- name: Choose a VM size for compute nodes
175-
href: batch-pool-vm-sizes.md
176-
- name: Move from Cloud Service to Virtual Machine pools
177-
displayName: migrate
178-
href: batch-pool-cloud-service-to-virtual-machine-configuration.md
179181
- name: Configure access to compute nodes
180182
displayName: rdp, ssh, network, remote
181183
href: pool-endpoint-configuration.md
@@ -189,9 +191,6 @@
189191
href: create-pool-availability-zones.md
190192
- name: Create a pool with disk encryption enabled
191193
href: disk-encryption.md
192-
- name: Create a pool in a virtual network
193-
displayName: vNet
194-
href: batch-virtual-network.md
195194
- name: Create a pool with public IP addresses
196195
displayName: static
197196
href: create-pool-public-ip.md

‎articles/batch/batch-pool-update-properties.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
title: Update pool properties
3+
description: Learn how to update existing Batch pool properties.
4+
ms.topic: how-to
5+
ms.date: 09/26/2024
6+
ms.custom:
7+
---
8+
9+
# Update Batch pool properties
10+
11+
When you create an Azure Batch pool, you specify certain properties that define the configuration
12+
of the pool. Examples include specifying the VM size, VM image to use, virtual network configuration,
13+
and encryption settings. However, you may need to update pool properties as your workload evolves
14+
over time or if a VM image reaches end-of-life.
15+
16+
Some, but not all, of these pool properties can be patched or updated to accommodate these situations.
17+
This article provides information about updateable pool properties, expected behaviors for
18+
pool property updates, and examples.
19+
20+
> [!TIP]
21+
> Some pool properties can only be updated using the
22+
> [Batch Management Plane APIs or SDKs](batch-apis-tools.md#batch-management-apis) using Entra
23+
> authentication. You will need to install or use the appropriate [API or SDK](batch-apis-tools.md)
24+
> for these operations to be available.
25+
26+
## Updateable pool properties
27+
28+
Batch provides multiple methods to update properties on a pool. Selecting which API to use
29+
determines the set of pool properties that can be updated as well as the update behavior.
30+
31+
> [!NOTE]
32+
> If you want to update pool properties that aren't part of the following Update or Patch
33+
> APIs, then you must recreate the pool to reflect the desired state.
34+
35+
### Management Plane: Pool - Update
36+
37+
The recommended path to updating pool properties is utilizing the
38+
[Pool - Update API](/rest/api/batchmanagement/pool/update) as part of the
39+
[Batch Management Plane API or SDK](batch-apis-tools.md#batch-management-apis). This API provides
40+
the most comprehensive and flexible way to update pool properties. Using this API allows select
41+
update of Management plane only pool properties and the ability to update other properties that
42+
would otherwise be immutable via Data Plane APIs.
43+
44+
> [!IMPORTANT]
45+
> You must use API version 2024-07-01 or newer of the Batch Management Plane API for updating pool
46+
> properties as described in this section.
47+
48+
Since this operation is a `PATCH`, only pool properties specified in the request are updated.
49+
If properties aren't specified as part of the request, then the existing values remain unmodified.
50+
51+
Some properties can only be updated when the pool has no active nodes in it or where the total
52+
number of compute nodes in the pool is zero. The properties that *don't* require the pool
53+
to be size zero for the new value to take effect are:
54+
55+
- applicationPackages
56+
- certificates
57+
- metadata
58+
- scaleSettings
59+
- startTask
60+
61+
If there are active nodes when the pool is updated with these properties, reboot of active
62+
compute nodes may be required for changes to take effect. For more information, see the
63+
documentation for each individual pool property.
64+
65+
All other updateable pool properties require the pool to be of size zero nodes to be accepted
66+
as part of the request to update.
67+
68+
You may also use [Pool - Create API](/rest/api/batchmanagement/pool/create) to update these
69+
select properties, but since the operation is a `PUT`, the request fully replaces all
70+
existing properties. Therefore, any property that isn't specified in the request is removed
71+
or set with the associated default.
72+
73+
#### Example: Update VM Image Specification
74+
75+
The following example shows how to update a pool VM image configuration via the Management Plane C# SDK:
76+
77+
```csharp
78+
public async Task UpdatePoolVmImage()
79+
{
80+
// Authenticate
81+
var clientId = Environment.GetEnvironmentVariable("CLIENT_ID");
82+
var clientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET");
83+
var tenantId = Environment.GetEnvironmentVariable("TENANT_ID");
84+
var subscriptionId = Environment.GetEnvironmentVariable("SUBSCRIPTION_ID");
85+
ClientSecretCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
86+
ArmClient client = new ArmClient(credential, subscriptionId);
87+
88+
// Get an existing Batch account
89+
string resourceGroupName = "<resourcegroup>";
90+
string accountName = "<batchaccount>";
91+
ResourceIdentifier batchAccountResourceId = BatchAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
92+
BatchAccountResource batchAccount = client.GetBatchAccountResource(batchAccountResourceId);
93+
94+
// get the collection of this BatchAccountPoolResource
95+
BatchAccountPoolCollection collection = batchAccount.GetBatchAccountPools();
96+
97+
// Update the pool
98+
string poolName = "mypool";
99+
BatchAccountPoolData data = new BatchAccountPoolData()
100+
{
101+
DeploymentConfiguration = new BatchDeploymentConfiguration()
102+
{
103+
VmConfiguration = new BatchVmConfiguration(new BatchImageReference()
104+
{
105+
Publisher = "MicrosoftWindowsServer",
106+
Offer = "WindowsServer",
107+
Sku = "2022-datacenter-azure-edition-smalldisk",
108+
Version = "latest",
109+
},
110+
nodeAgentSkuId: "batch.node.windows amd64"),
111+
},
112+
};
113+
114+
ArmOperation<BatchAccountPoolResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, poolName, data);
115+
BatchAccountPoolResource result = lro.Value;
116+
117+
BatchAccountPoolData resourceData = result.Data;
118+
Console.WriteLine($"Succeeded on id: {resourceData.Id}");
119+
}
120+
```
121+
122+
#### Example: Update VM Size and Target Node Communication Mode
123+
124+
The following example shows how to update a pool VM image size and target node communication
125+
mode to be simplified via REST API:
126+
127+
```http
128+
PATCH https://management.azure.com/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupName>/providers/Microsoft.Batch/batchAccounts/<batchaccountname>/pools/<poolname>?api-version=2024-07-01
129+
```
130+
131+
Request Body
132+
133+
```json
134+
{
135+
"type": "Microsoft.Batch/batchAccounts/pools",
136+
"parameters": {
137+
"properties": {
138+
"vmSize": "standard_d32ads_v5",
139+
"targetNodeCommunicationMode": "simplified"
140+
}
141+
}
142+
}
143+
```
144+
145+
### Data Plane: Pool - Patch or Update Properties
146+
147+
The Data Plane offers the ability to either patch or update select pool properties. The
148+
available APIs are the [Pool - Patch API](/rest/api/batchservice/pool/patch) or the
149+
[Pool - Update Properties API](/rest/api/batchservice/pool/update-properties) as part of
150+
the [Batch Data Plane API or SDK](batch-apis-tools.md#batch-service-apis).
151+
152+
The [Patch API](/rest/api/batchservice/pool/patch) allows patching of select pool properties
153+
as specified in the documentation such as the `startTask`. Since this operation is a `PATCH`,
154+
only pool properties specified in the request are updated. If properties aren't specified as
155+
part of the request, then the existing values remain unmodified.
156+
157+
The [Update Properties API](/rest/api/batchservice/pool/update-properties) allows select
158+
update of the pool properties as specified in the documentation. This request fully
159+
replaces the existing properties, therefore any property that isn't specified in the
160+
request is removed.
161+
162+
Compute nodes must be rebooted for changes to take effect for the following properties:
163+
164+
- applicationPackageReferences
165+
- certificateReferences
166+
- startTask
167+
168+
The pool must be resized to zero active nodes for updates to the `targetNodeCommunicationMode`
169+
property.
170+
171+
## FAQs
172+
173+
- Do I need to perform any other operations after updating pool properties while the pool
174+
has active nodes?
175+
176+
Yes, for pool properties that can be updated with active nodes, there are select properties
177+
which require compute nodes to be rebooted. Alternatively, the pool can be scaled down to
178+
zero nodes to reflect the modified properties.
179+
180+
- Can I modify the Managed identity collection on the pool while the pool has active nodes?
181+
182+
Yes, but you shouldn't. While Batch doesn't prohibit mutation of the collection with active
183+
nodes, we recommend avoiding doing so as that leads to inconsistency in the identity collection
184+
if the pool scales out. We recommend to only update this property when the pool is sized zero.
185+
For more information, see the [Configure managed identities](managed-identity-pools.md) article.
186+
187+
## Next steps
188+
189+
- Learn more about available Batch [APIs and tools](batch-apis-tools.md).
190+
- Learn how to [check pools and nodes for errors](batch-pool-node-error-checking.md).

0 commit comments

Comments
 (0)