Batch Mangement Plane 2025-06-01

[wiboris]

ARM (Control Plane) API Specification Update Pull Request

Tip

Overwhelmed by all this guidance? See the Getting help section at the bottom of this PR description.

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.

Purpose of this PR

What's the purpose of this PR? Check the specific option that applies. This is mandatory!

• New resource provider.
• New API version for an existing resource provider. (If API spec is not defined in TypeSpec, the PR should have been created in adherence to OpenAPI specs PR creation guidance).
• Update existing version for a new feature. (This is applicable only when you are revising a private preview API version.)
• Update existing version to fix OpenAPI spec quality issues in S360.
• Convert existing OpenAPI spec to TypeSpec spec (do not combine this with implementing changes for a new API version).
• Other, please clarify:
  • edit this with your clarification

Due diligence checklist

To merge this PR, you must go through the following checklist and confirm you understood
and followed the instructions by checking all the boxes:

• I confirm this PR is modifying Azure Resource Manager (ARM) related specifications, and not data plane related specifications.
• I have reviewed following Resource Provider guidelines, including
  ARM resource provider contract and
  REST guidelines (estimated time: 4 hours).
  I understand this is required before I can proceed to the diagram Step 2, "ARM API changes review", for this PR.
• A release plan has been created. If not, please create one as it will help guide you through the REST API and SDK creation process.

Additional information

Viewing API changes

For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.

Suppressing failures

If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the
suppressions guide to get approval.

Getting help

• First, please carefully read through this PR description, from top to bottom. Please fill out the Purpose of this PR and Due diligence checklist.
• If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
• To understand what you must do next to merge this PR, see the Next Steps to Merge comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
• For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure
  and https://aka.ms/ci-fix.
• For help with ARM review (PR workflow diagram Step 2), see https://aka.ms/azsdk/pr-arm-review.
• If the PR CI checks appear to be stuck in queued state, please add a comment with contents /azp run.
  This should result in a new comment denoting a PR validation pipeline has started and the checks should be updated after few minutes.
• If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.
• For guidance on SDK breaking change review, refer to https://aka.ms/ci-fix.

[openapi-pipeline-app]

Next Steps to Merge

✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.

[openapi-pipeline-app]

PR validation pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.Batch
Go	sdk/resourcemanager/batch/armbatch
Java	com.azure.resourcemanager:azure-resourcemanager-batch
JavaScript	@azure/arm-batch
Python	azure-mgmt-batch

[wenxiangMS]

Hi @rkmanda , thanks for your notification.

In the implementation of Batch, we will create DiskEncryptionSet resources from DiskRP to support the feature of CustomerManagedKey. The REST API of creating DiskEncryptionSet is: https://learn.microsoft.com/en-us/rest/api/compute/disk-encryption-sets/create-or-update?view=rest-compute-2025-02-01&tabs=HTTP. We receive the keyUrl and rotationToLatestKeyVersionEnabled properties from user. After some processing, we will use them with some other values to create DiskEncryptionSet. To keep align, we used almost the same API definition as creating DiskEncryptionSet in our API.

As for the structures between our current API and the recommended API definition, I believe they are very similar:

Recommended API Name	Batch API Name	Difference
infrastructureEncryption	None	As discussed above, it is not required
customerManagedKeyEncryption.keyEncryptionKeyUrl	customerManagedKey.keyUrl	Batch is using the same definition as DiskRP. Besides, another difference is: the keyEncryptionKeyUrl in the recommended API can be versioned or unversioned, but as the description from DiskEncryptionSet, the keyUrl must be versioned.
customerManagedKeyEncryption.keyEncryptionKeyIdentity.identityType	None	It is not needed for batch because Batch pool does not support system assigned identity. So the identity will be always user assigned identity, and we do not need customer to fill this field.
customerManagedKeyEncryption.keyEncryptionKeyIdentity.userAssignedIdentityResourceId	customerManagedKey.identityReference.resourceId	The resource id of the user assigned identity. The meaning and structure in two APIs are same.
customerManagedKeyEncryption.keyEncryptionKeyIdentity.federatedClientId	None	In the workflow of Batch with CustomerManagedKey, we will use the key and identity from user's tenant to create DiskEncryptionSet resource. So this is always a cross-tenant scenario, and we used HOBO V2 to accomplish it. In this scenario, DiskRP just receives the delegatedIdentityClientId, but does not receive federatedClientId anymore. So in our implementation, we will delegate the user assigned identity and create resource by the client id of delegated identitym. Also, due to HOBO V2, we should not receive the federated client id.
None	customerManagedKey.rotationToLatestKeyVersionEnabled	This property is defined in the API of DiskEncryptionSet, and we should allow user to control its value.

So their structures are very similar, Batch just removed some unnecessary properties. In addition, there are some differences in naming, some of which are to maintain consistency with DiskEncryptionSet.

[ramoka178]

    "ipTagType": {

can the type of tags be enums ?

---

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:5617 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

[ramoka178]

    },

please model as enum, with values Enabled,Disabled.

---

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:6770 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

[ramoka178]

  "type": "object",

Looks like this comment is still applicable. Please address.

---

In reply to: 2954203732

---

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:6543 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

[ramoka178]

    },

There are few new properties being introduced in this PR. The examples do not reflect the new properties being added.

Please update examples also , to have the new properties from this json/apiversion

---

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:4757 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

[ramoka178]

  "type": "object",

Author added comments in PR

---

In reply to: 3009476962

---

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:6543 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

[wenxiangMS]

  "type": "object",

Looks like this comment is still applicable. Please address.

In reply to: 2954203732

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:6543 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

Hi @ramoka178 , for this comment, please refer to my explanation at #35105 (comment).

We think our structures are same as the guidance, and we are following the naming from under layer (DiskRP, https://learn.microsoft.com/en-us/rest/api/compute/disk-encryption-sets/create-or-update?view=rest-compute-2025-02-01&tabs=HTTP).

[wenxiangMS]

Hi team,

We are working on the comments currently. But by the way, could you please check our reply 2995366145 on the comment 2954203732? So that we could confirm if we need to change our definitions and avoid reworking. Thanks!

[dxyinme]

    },

please model as enum, with values Enabled,Disabled.

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:6770 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

Hi @ramoka178 , the eanbled parameter is follow Azure VMSS API about proxyagentsettings https://learn.microsoft.com/en-us/rest/api/compute/virtual-machine-scale-sets/create-or-update?view=rest-compute-2025-02-01&tabs=HTTP#proxyagentsettings , and I think for this parameter there is no need to change boolean to enum because no more choice for it. and use enum may make customer misunderstand the mean of enabled

[ColtonPaul]

    "ipTagType": {

can the type of tags be enums ?

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:5617 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

In this case, I don't think it should be. Some Batch properties are passed through to Virtual Machine Scale Sets, and in these cases, we try to align to their API. ipTagType is one of these properties (https://learn.microsoft.com/en-us/rest/api/compute/virtual-machine-scale-sets/create-or-update?view=rest-compute-2025-02-01&tabs=HTTP#virtualmachinescalesetiptag), and it defines the type as 'string'.

Instead of having to track whenever VMSS adds a new type and needing to duplicate the type in Batch before it's usable to customers, we allow this field to be set to any string and delegate the validation to VMSS.

[TimLovellSmith]

    "ipTagType": {

can the type of tags be enums ?
Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:5617 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

In this case, I don't think it should be. Some Batch properties are passed through to Virtual Machine Scale Sets, and in these cases, we try to align to their API. ipTagType is one of these properties (https://learn.microsoft.com/en-us/rest/api/compute/virtual-machine-scale-sets/create-or-update?view=rest-compute-2025-02-01&tabs=HTTP#virtualmachinescalesetiptag), and it defines the type as 'string'.

Instead of having to track whenever VMSS adds a new type and needing to duplicate the type in Batch before it's usable to customers, we allow this field to be set to any string and delegate the validation to VMSS.

Just wondering, do you ever interact with this field? Can you actually be sure you'll really support every value that the VMSS RP supports, without adding logic for it in the future? Or is it better to explicitly enumerate the list of values you actually definitely support for this api version, so that customers don't try and send you values you don't definitely support?

[TimLovellSmith]

    },

please model as enum, with values Enabled,Disabled.
Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:6770 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

Hi @ramoka178 , the eanbled parameter is follow Azure VMSS API about proxyagentsettings https://learn.microsoft.com/en-us/rest/api/compute/virtual-machine-scale-sets/create-or-update?view=rest-compute-2025-02-01&tabs=HTTP#proxyagentsettings , and I think for this parameter there is no need to change boolean to enum because no more choice for it. and use enum may make customer misunderstand the mean of enabled

Assuming you can flow parameters to other RPs sounds fine in theory, but in practice it may stop working for you if other RPs ever make breaking changes in their APIs...
or e.g. they start supporting a more complex mechanism for this than just enabled/disabled.

Not to mention, worries like what is the potential security impact of allowing values to flow through, unchecked and unvalidated? In enum cases, its much more obvious that what can go wrong is limited, than with a string!

Bottom line for me: Maybe it is better not to expose the underlying implementation in every case. Maybe you should expose a simplified or more limited API capturing the pit of success. Are you really being strategic about this?

[TimLovellSmith]

      "default": "None",

You removed the documented Default value of 'None', but added "If not specified, the default is none.".

Is this intended as a bugfix, a breaking change, or what exactly?

---

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:4996 in af615ca. [](commit_id = af615ca, deletion_comment = True)

[TimLovellSmith]

      "title": "Audit / Enforce",

doesn't seem like the right title for the mode property. Do you want something like "Mode: audit vs enforce"?

---

Refers to: specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json:6736 in 13f5ea6. [](commit_id = 13f5ea6, deletion_comment = False)

[TimLovellSmith]

Nothing mandatory to fix at this point for me, but please review remaining feedback/questions.

[TimLovellSmith]

You should fix or suppress the remaining lintdiff warnings introduced in this PR:

⚠️ SchemaDescriptionOrTitle | Schema should have a description or title.Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L5614 |   -- | -- | -- ⚠️ XmsIdentifierValidation | Missing identifier id in array item propertyLocation: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L5654 |   ⚠️ EnumInsteadOfBoolean | Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L6549 |   ⚠️ EnumInsteadOfBoolean | Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L6767 ⚠️ [SchemaDescriptionOrTitle](https://github.com/Azure/azure-openapi-validator/blob/main/docs/schema-description-or-title.md) Schema should have a description or title. Location: [Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L5614](https://github.com/Azure/azure-rest-api-specs/blob/13f5ea68c1b4ba79edd91d41057eef097d319042/specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L5614) ⚠️ [XmsIdentifierValidation](https://github.com/Azure/azure-openapi-validator/blob/main/docs/xms-identifier-validation.md) Missing identifier id in array item property Location: [Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L5654](https://github.com/Azure/azure-rest-api-specs/blob/13f5ea68c1b4ba79edd91d41057eef097d319042/specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L5654) ⚠️ [EnumInsteadOfBoolean](https://github.com/Azure/azure-openapi-validator/blob/main/docs/enum-instead-of-boolean.md) Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum. Location: [Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L6549](https://github.com/Azure/azure-rest-api-specs/blob/13f5ea68c1b4ba79edd91d41057eef097d319042/specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L6549) ⚠️ [EnumInsteadOfBoolean](https://github.com/Azure/azure-openapi-validator/blob/main/docs/enum-instead-of-boolean.md) Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum. Location: [Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L6767](https://github.com/Azure/azure-rest-api-specs/blob/13f5ea68c1b4ba79edd91d41057eef097d319042/specification/batch/resource-manager/Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L6767)

[TimLovellSmith]

Since this is a new version, consider adding a provisioningState to your model to fix this historic linter warning

201 response schema in long running PUT operation is missing ProvisioningState property. A LRO PUT operations response schema must have ProvisioningState specified for the 200 and 201 status codes.
Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L38

[TimLovellSmith]

Since this is a new version, you should consider fixing this historic issue:

❌ PutRequestResponseSchemeArm | A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'BatchAccount_Create' Request Model: 'parameters[2].schema' Response Model: 'responses[200].schema'Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L38 -- | -- ❌ PutRequestResponseSchemeArm | A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'Certificate_Create' Request Model: 'parameters[3].schema' Response Model: 'responses[200].schema'Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L1262 -- | --

[TimLovellSmith]

Since this is a new api version, consider relaxing some of the 'required' constraints for PATCH requests:

❌ PatchBodyParametersSchema | Properties of a PATCH request body must not be required, property:storageAccountId.Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L146 -- | -- ❌ PatchBodyParametersSchema | Properties of a PATCH request body must not have default value, property:authenticationMode.Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L146 ❌ PatchBodyParametersSchema | Properties of a PATCH request body must not have default value, property:publicNetworkAccess.Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L146 ❌ PatchBodyParametersSchema | Properties of a PATCH request body must not be required, property:defaultAction.Location: Microsoft.Batch/stable/2025-06-01/BatchManagement.json#L146