Review request for Microsoft.ContainerService/aks to add version preview/2025-08-02-preview #37803

FumingZhang · 2025-09-28T23:38:35Z

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.

…eview/2025-07-02-preview to version preview/2025-08-02-preview

Signed-off-by: Mateusz Gozdek <[email protected]>

* Added changes for Istio CNI to 2028-08-02-preview API * run prettierc --------- Co-authored-by: German Robayo Paz <[email protected]>

Co-authored-by: indusridhar <[email protected]>

* Add MeshMembership subresource and examples * There are no async operations for PUT and DELETE so no need to mark them as long running operation * Linting * Sync deletion should return 200 and 204 --------- Co-authored-by: Zhewei Hu <[email protected]>

* Make MeshMembership PUT/DELETE long running operation * Add provisionState --------- Co-authored-by: Zhewei Hu <[email protected]>

…37382)

…37609)

Co-authored-by: Xintian Yang <[email protected]>

github-actions · 2025-09-28T23:38:49Z

Next Steps to Merge

Next steps that must be taken to merge this PR:

❌ Your PR has breaking changes in the generated SDK for Go (label: BreakingChange-Go-Sdk). Refer to step 3 in the PR workflow diagram.
❌ Your PR has breaking changes in the generated SDK for JavaScript (label: BreakingChange-JavaScript-Sdk). Refer to step 3 in the PR workflow diagram.
❌ Your PR has breaking changes in the generated SDK for Python (label: BreakingChange-Python-Sdk). Refer to step 3 in the PR workflow diagram.

Comment generated by summarize-checks workflow run.

github-actions · 2025-09-28T23:40:44Z

API Change Check

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

Language	API Review for Package
Swagger	Microsoft.ContainerService-aks
Go	sdk/resourcemanager/containerservice/armcontainerservice
Java	com.azure.resourcemanager:azure-resourcemanager-containerserviceaks-generated
JavaScript	@azure/arm-containerservice

FumingZhang · 2025-09-29T00:29:02Z

Regarding the breaking change, compared with previous stable API version

Item 1-2 of 1029 - ReadonlyPropertyChanged are caused by change baf5edb.

The reason for this change is that customers need a recovery mechanism in case upgrades failed or even if the upgrade succeeded but customer has workload issues on the newer version. Goal is to rollback kubernetes/node image version to allow them to go back to the previous version(s), so removing the previous read-only restriction on this field.
Items 3-7 of 1029 - ReadonlyPropertyChanged and 1036 - ConstraintChanged are caused by change c66c21c in previous preview API version 2025-04-02-preview

The reason for this change is that previously, AKS only supported Get/List Machines. In this new API proposal, AKS introduces Put Machine as a new operation. Since the machine data model and name parameter will now be shared between Get and Put, we are removing the read-only restriction from certain properties and expanding the name parameter accordingly. Check this Review request for Microsoft.ContainerService/aks to add version preview/2025-04-02-preview #35081 (comment).
1034 - AddedRequiredProperty is a false alert. The results are based on a comparison between the new preview and stable API versions. In the stable API, the IstioEgressGateway model definition does not even contain the name attribute, let alone setting it to read only.

ravimeda · 2025-10-03T11:46:49Z

        "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter"

Suggest using v6 #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:46 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T11:53:10Z

Thanks for the summary. This helps.

In reply to: 3344457468

ravimeda · 2025-10-03T11:55:37Z

},

I see enableCustomCATrust is removed. Is it expected? #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:5595 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:00:57Z

    "Flatcar",

Curious to know the positioning of the new one. Are the values sorted in some order? #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:8897 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:23:46Z

        "description": "Spot priority VMs will be used. There is no SLA for spot nodes. See [spot on AKS](https://docs.microsoft.com/azure/aks/spot-node-pool) for more information."

nit - Create an aka.ms link that you can update as needed. #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:8974 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:24:55Z

    "name": "AgentPoolSSHAccess",

What is the default value? #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:9808 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:26:25Z

        "description": "SSH to node with EntraId integration. More information can be found under https://aka.ms/aks/ssh/aad"

The article has no mention of Entra. Please add a link to appropriate doc. #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:9821 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:28:21Z

        "description": "SSH to node with EntraId integration. More information can be found under https://aka.ms/aks/ssh/aad"

If you have plans to update the current doc, then you can leave the link as-is.

In reply to: 3365492539

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:9821 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:32:15Z

        "CNIChaining"

Which of these is the default? #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:11539 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:33:12Z

            "description": "Istio will created a chained CNI plugin to redirect traffic (recommended)."

Suggest - 'create' #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:11551 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:34:20Z

            "value": "CNIChaining",

Two letter acronyms are in uppercase. For three or more only the first letter is upper cased e.g., CniChanning #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:11550 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:37:02Z

      "description": "Unique read-only string used to implement optimistic concurrency. The eTag value will change when the resource is updated. Specify an if-match or if-none-match header with the eTag value for a subsequent request to enable optimistic concurrency per the normal etag convention.",

ETag #Closed

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:12434 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda · 2025-10-03T12:38:09Z

      "description": "Unique read-only string used to implement optimistic concurrency. The eTag value will change when the resource is updated. Specify an if-match or if-none-match header with the eTag value for a subsequent request to enable optimistic concurrency per the normal etag convention.",

ETag #Resolved

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:12837 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

ravimeda

🕐

FumingZhang · 2025-10-07T00:23:18Z

        "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter"
Suggest using v6

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:46 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

Thanks for the suggestion, we are on a very tight schedule and will switch to v6 from the next monthly stable/preview API version.

      },
I see enableCustomCATrust is removed. Is it expected?

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:5595 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

Yes, that's expected. The change was made in #b1a21f6. The custom CA trust feature reached GA and has been available in the stable API version since 2025-01-01, as noted in commit #cea24e7 in PR #32934. In the stable API version, the field enableCustomCATrust is not present and has also been deprecated in the preview API version. Therefore, it's being removed starting from this preview API version.

    "Flatcar",
Curious to know the positioning of the new one. Are the values sorted in some order?

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:8897 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

emm, I guess they are not sorted, let me fix this.

        "description": "Spot priority VMs will be used. There is no SLA for spot nodes. See [spot on AKS](https://docs.microsoft.com/azure/aks/spot-node-pool) for more information."
nit - Create an aka.ms link that you can update as needed.

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:8974 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

Make sense. We'll apply this approach moving forward. For this specific description that's been around for four years, it may take some time to identify the appropriate owner first. We'll fix the issue in next preview API version.

FumingZhang · 2025-10-07T00:50:26Z

The sorting issue and the ETag case issue have been resolved in #db0e847.

matthchr · 2025-10-07T00:51:58Z

            "value": "CNIChaining",
Two letter acronyms are in uppercase. For three or more only the first letter is upper cased e.g., CniChanning

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:11550 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

@ravimeda is this documented someplace -- can you share it? It doesn't match current AKS patterns and also requires RP code-change as our enums are case-sensitive (to avoid having to normalize). I think we would prefer to stick with our current pattern

See for example:

Note that some enums aren't UpperCamelCase (legacy). We review for that now but didn't in the past so a few are lowerCamel or alllower, though the vast majority (80+%) are UpperCamel.

Given we have an existing pattern I would rather stay self-consistent than break our self-consistency to follow the external rule (assuming there is one).

matthchr · 2025-10-07T00:54:40Z

      "description": "Unique read-only string used to implement optimistic concurrency. The eTag value will change when the resource is updated. Specify an if-match or if-none-match header with the eTag value for a subsequent request to enable optimistic concurrency per the normal etag convention.",
ETag

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:12837 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

The actual field is eTag. Shouldn't we refer to it by the actual field name?

Certainly when saying "The eTag value will change...." we're literally saying "the field eTag will change". There is no "ETag" field.

german1608 · 2025-10-07T01:04:05Z

        "CNIChaining"
Which of these is the default?

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:11539 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

The default is dynamic, depends on the contents of the istio revisions list.

https://github.com/Azure/azure-rest-api-specs/blob/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2025-08-01/managedClusters.json#L7474

Currently, it is InitContainers, but once the asm-1-28 Istio revision is available (somewhere around December or January) if the revisions list contains any revision greater or equal than asm-1-28 the default will become CNIChaining

Co-authored-by: German Robayo Paz <[email protected]>

jiashun0011 · 2025-10-07T06:35:53Z

        "description": "SSH to node with EntraId integration. More information can be found under https://aka.ms/aks/ssh/aad"
If you have plans to update the current doc, then you can leave the link as-is.

In reply to: 3365492539

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:9821 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

yes, we will update the entra id ssh doc with this link, so just keep it.

jiashun0011 · 2025-10-07T06:45:16Z

    "name": "AgentPoolSSHAccess",
What is the default value?

Refers to: specification/containerservice/resource-manager/Microsoft.ContainerService/aks/preview/2025-08-02-preview/managedClusters.json:9808 in 356f5f9. [](commit_id = 356f5f9, deletion_comment = False)

The default value should be localuser and the setting of default behavior/value is in server side, we don't backfill client side default value in order to support partial PUT.

FumingZhang and others added 13 commits September 29, 2025 09:36

Adds base for updating Microsoft.ContainerService/aks from version pr…

24253b7

…eview/2025-07-02-preview to version preview/2025-08-02-preview

Updates readme

d359cb2

Updates API version in new specs and examples

0cfb3ef

[AKS] add Flatcar ossku to preview (#37168)

8540993

Signed-off-by: Mateusz Gozdek <[email protected]>

Adds changes for Istio CNI to 2025-08-02-preview API (#37163)

ae70136

* Added changes for Istio CNI to 2028-08-02-preview API * run prettierc --------- Co-authored-by: German Robayo Paz <[email protected]>

Adding changes in API to enable rollback (#37229)

baf5edb

Co-authored-by: indusridhar <[email protected]>

Make MeshMembership PUT and DELETE long running operations (#37378)

f482594

* Make MeshMembership PUT/DELETE long running operation * Add provisionState --------- Co-authored-by: Zhewei Hu <[email protected]>

Add node customization profile to MC agentpool swagger with example (#…

34dcdcb

…37382)

feat: remove enableCustomCATrust from preview swagger spec (#37479)

b1a21f6

feat: add swagger changes for EntraId support in AgentPoolSSHAccess (#…

599b2c5

…37609)

Add swagger change for hosted system pool. (#37723)

da14202

Co-authored-by: Xintian Yang <[email protected]>

chore: update description changes for AgentPoolSSHAccess (#37778)

356f5f9

FumingZhang requested review from palma21 and matthchr as code owners September 28, 2025 23:38

microsoft-github-policy-service bot added the Container Service label Sep 28, 2025

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

ravimeda requested changes Oct 3, 2025

View reviewed changes

ravimeda added ARMChangesRequested and removed WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required labels Oct 3, 2025

update (#37937)

db0e847

FumingZhang and others added 2 commits October 7, 2025 12:17

fix (#37938)

d02d6ba

doc: improve description of CNIChaining (#37939)

0dfdcb5

Co-authored-by: German Robayo Paz <[email protected]>

FumingZhang removed the ARMChangesRequested label Oct 7, 2025

github-actions bot added the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Oct 7, 2025

mentat9 added the ARMSignedOff <valid label in PR review process>add this label when ARM approve updates after review label Oct 7, 2025

github-actions bot removed the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Oct 7, 2025

Review request for Microsoft.ContainerService/aks to add version preview/2025-08-02-preview #37803

Are you sure you want to change the base?

Review request for Microsoft.ContainerService/aks to add version preview/2025-08-02-preview #37803

Uh oh!

Conversation

FumingZhang commented Sep 28, 2025

ARM (Control Plane) API Specification Update Pull Request

PR review workflow diagram

Purpose of this PR

Due diligence checklist

Additional information

Getting help

Uh oh!

github-actions bot commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Next Steps to Merge

Uh oh!

github-actions bot commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Change Check

Uh oh!

FumingZhang commented Sep 29, 2025

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda commented Oct 3, 2025 • edited by mentat9 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ravimeda left a comment

Choose a reason for hiding this comment

Uh oh!

FumingZhang commented Oct 7, 2025

Uh oh!

FumingZhang commented Oct 7, 2025

Uh oh!

matthchr commented Oct 7, 2025

Uh oh!

matthchr commented Oct 7, 2025

Uh oh!

german1608 commented Oct 7, 2025

Uh oh!

jiashun0011 commented Oct 7, 2025

Uh oh!

jiashun0011 commented Oct 7, 2025

Uh oh!

Uh oh!

github-actions bot commented Sep 28, 2025 •

edited

Loading

github-actions bot commented Sep 28, 2025 •

edited

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading

ravimeda commented Oct 3, 2025 •

edited

Loading

ravimeda commented Oct 3, 2025 •

edited by mentat9

Loading