Update Batch pool properties

When you create an Azure Batch pool, you specify certain properties that define the configuration of the pool. Examples include specifying the VM size, VM image to use, virtual network configuration, and encryption settings. However, you may need to update pool properties as your workload evolves over time or if a VM image reaches end-of-life.

Some, but not all, of these pool properties can be patched or updated to accommodate these situations. This article provides information about updateable pool properties, expected behaviors for pool property updates, and examples.

Batch provides multiple methods to update properties on a pool. Selecting which API to use determines the set of pool properties that can be updated as well as the update behavior.

The recommended path to updating pool properties is utilizing the Pool - Update API as part of the Batch Management Plane API or SDK. This API provides the most comprehensive and flexible way to update pool properties. Using this API allows select update of Management plane only pool properties and the ability to update other properties that would otherwise be immutable via Data Plane APIs.

Since this operation is a PATCH, only pool properties specified in the request are updated. If properties aren't specified as part of the request, then the existing values remain unmodified.

Some properties can only be updated when the pool has no active nodes in it or where the total number of compute nodes in the pool is zero. The properties that don't require the pool to be size zero for the new value to take effect are:

• applicationPackages
• certificates
• metadata
• scaleSettings
• startTask

If there are active nodes when the pool is updated with these properties, reboot of active compute nodes may be required for changes to take effect. For more information, see the documentation for each individual pool property.

All other updateable pool properties require the pool to be of size zero nodes to be accepted as part of the request to update.

You may also use Pool - Create API to update these select properties, but since the operation is a PUT, the request fully replaces all existing properties. Therefore, any property that isn't specified in the request is removed or set with the associated default.

The following example shows how to update a pool VM image configuration via the Management Plane C# SDK:

public async Task UpdatePoolVmImage()
{
     // Authenticate
     var clientId = Environment.GetEnvironmentVariable("CLIENT_ID");
     var clientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET");
     var tenantId = Environment.GetEnvironmentVariable("TENANT_ID");
     var subscriptionId = Environment.GetEnvironmentVariable("SUBSCRIPTION_ID");
     ClientSecretCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
     ArmClient client = new ArmClient(credential, subscriptionId);

     // Get an existing Batch account
     string resourceGroupName = "<resourcegroup>";
     string accountName = "<batchaccount>";
     ResourceIdentifier batchAccountResourceId = BatchAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
     BatchAccountResource batchAccount = client.GetBatchAccountResource(batchAccountResourceId);

     // get the collection of this BatchAccountPoolResource
     BatchAccountPoolCollection collection = batchAccount.GetBatchAccountPools();

     // Update the pool
     string poolName = "mypool";
     BatchAccountPoolData data = new BatchAccountPoolData()
     {
         DeploymentConfiguration = new BatchDeploymentConfiguration()
         {
             VmConfiguration = new BatchVmConfiguration(new BatchImageReference()
             {
                 Publisher = "MicrosoftWindowsServer",
                 Offer = "WindowsServer",
                 Sku = "2022-datacenter-azure-edition-smalldisk",
                 Version = "latest",
             },
             nodeAgentSkuId: "batch.node.windows amd64"),
         },
     };

     ArmOperation<BatchAccountPoolResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, poolName, data);
     BatchAccountPoolResource result = lro.Value;

     BatchAccountPoolData resourceData = result.Data;
     Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

The following example shows how to update a pool VM image size and target node communication mode to be simplified via REST API:

PATCH https://management.chinacloudapi.cn/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupName>/providers/Microsoft.Batch/batchAccounts/<batchaccountname>/pools/<poolname>?api-version=2024-07-01

Request Body

{
    "type": "Microsoft.Batch/batchAccounts/pools",
    "parameters": {
        "properties": {
            "vmSize": "standard_d32ads_v5",
            "targetNodeCommunicationMode": "simplified"
        }
    }
}

The Data Plane offers the ability to either patch or update select pool properties. The available APIs are the Pool - Patch API or the Pool - Update Properties API as part of the Batch Data Plane API or SDK.

The Patch API allows patching of select pool properties as specified in the documentation such as the startTask. Since this operation is a PATCH, only pool properties specified in the request are updated. If properties aren't specified as part of the request, then the existing values remain unmodified.

The Update Properties API allows select update of the pool properties as specified in the documentation. This request fully replaces the existing properties, therefore any property that isn't specified in the request is removed.

Compute nodes must be rebooted for changes to take effect for the following properties:

• applicationPackageReferences
• certificateReferences
• startTask

The pool must be resized to zero active nodes for updates to the targetNodeCommunicationMode property.

• Do I need to perform any other operations after updating pool properties while the pool has active nodes?

Yes, for pool properties that can be updated with active nodes, there are select properties which require compute nodes to be rebooted. Alternatively, the pool can be scaled down to zero nodes to reflect the modified properties.

• Can I modify the Managed identity collection on the pool while the pool has active nodes?

Yes, but you shouldn't. While Batch doesn't prohibit mutation of the collection with active nodes, we recommend avoiding doing so as that leads to inconsistency in the identity collection if the pool scales out. We recommend to only update this property when the pool is sized zero. For more information, see the Configure managed identities article.

• Learn more about available Batch APIs and tools.
• Learn how to check pools and nodes for errors.