Skip to content

Batch Mangement Plane 2025-06-01 #35105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Conversation

wiboris
Copy link
Member

@wiboris wiboris commented Jun 4, 2025

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.

spec_pr_review_workflow_diagram

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.

Sorry, something went wrong.

Copy link

openapi-pipeline-app bot commented Jun 4, 2025

Next Steps to Merge

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

Copy link

openapi-pipeline-app bot commented Jun 4, 2025

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

@github-actions github-actions bot added the brownfield Brownfield services will soon be required to convert to TypeSpec. See https://aka.ms/azsdk/typespec. label Jun 4, 2025
@AzureRestAPISpecReview AzureRestAPISpecReview added ARMReview new-api-version resource-manager WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required labels Jun 4, 2025
Copy link

github-actions bot commented Jun 4, 2025

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

@rkmanda rkmanda added the ARMChangesRequested <valid label in PR review process>add this label when require changes after ARM review label Jun 20, 2025
@openapi-pipeline-app openapi-pipeline-app bot removed the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Jun 20, 2025
@wenxiangMS
Copy link

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.

@dpwatrous dpwatrous removed the ARMChangesRequested <valid label in PR review process>add this label when require changes after ARM review label Jun 23, 2025
@openapi-pipeline-app openapi-pipeline-app bot added the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Jun 23, 2025
@ramoka178
Copy link
Contributor

    "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
Copy link
Contributor

    },

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
Copy link
Contributor

  "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
Copy link
Contributor

    },

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
Copy link
Contributor

  "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)

@ramoka178 ramoka178 added the ARMChangesRequested <valid label in PR review process>add this label when require changes after ARM review label Jun 26, 2025
@openapi-pipeline-app openapi-pipeline-app bot removed the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Jun 26, 2025
@wenxiangMS
Copy link

  "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
Copy link

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
Copy link

dxyinme commented Jun 30, 2025

    },

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
Copy link

    "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.

@wanghoppe wanghoppe requested a review from wenxiangMS July 1, 2025 04:43
@wanghoppe wanghoppe removed the ARMChangesRequested <valid label in PR review process>add this label when require changes after ARM review label Jul 1, 2025
@openapi-pipeline-app openapi-pipeline-app bot added the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Jul 1, 2025
@TimLovellSmith
Copy link
Member

TimLovellSmith commented Jul 2, 2025

    "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
Copy link
Member

TimLovellSmith commented Jul 2, 2025

    },

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
Copy link
Member

      "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
Copy link
Member

      "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 TimLovellSmith added ARMSignedOff <valid label in PR review process>add this label when ARM approve updates after review and removed WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required labels Jul 2, 2025
@TimLovellSmith
Copy link
Member

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

@TimLovellSmith
Copy link
Member

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
Copy link
Member

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
Copy link
Member

TimLovellSmith commented Jul 2, 2025

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
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
ARMReview ARMSignedOff <valid label in PR review process>add this label when ARM approve updates after review Batch brownfield Brownfield services will soon be required to convert to TypeSpec. See https://aka.ms/azsdk/typespec. new-api-version PipelineBotTrigger PublishToCustomers Acknowledgement the changes will be published to Azure customers. ReadyForApiTest <valid label in PR review process>add this label when swagger and service APIs are ready for test resource-manager
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet