Board Review: Split Azure Kubernetes Fleet Manager API definitions and SDKs from ContainerService (AKS)

[serbrech]

Thank you for submitting this review request. Thorough review of your client library ensures that your APIs are consistent with the guidelines and the consumers of your client library have a consistently good experience when using Azure.

The Architecture Board reviews Track 2 libraries only. If your library does not meet this requirement, please reach out to Architecture Board before creating the issue.

Please reference our review process guidelines to understand what is being asked for in the issue template.

To ensure consistency, all Tier-1 languages (C#, TypeScript, Java, Python) will generally be reviewed together. In expansive libraries, we will pair dynamic languages (Python, TypeScript) together, and strongly typed languages (C#, Java) together in separate meetings.

For Tier-2 languages (C, C++, Go, Android, iOS), the review will be on an as-needed basis.

Before submitting, ensure you adjust the title of the issue appropriately.

Note that the required material must be included before a meeting can be scheduled.

Contacts and Timeline

• Responsible service team: Azure Kubernetes Fleet Manager
• Main contacts: @serbrech (Fleet) @FumingZhang (AKS)
• Expected code complete date: Fleet service is already released in preview. API/SDK split could be effective within 2 weeks following approval
• Expected release date: N/A

About the Service

Note that the Fleets resources are in preview. No GA API have been released at this moment.

• Link to documentation introducing/describing the service: Azure Kubernetes Fleet Manager
• Link to the service REST APIs: Microsoft.ContainerService/preview/2022-09-02-preview/fleets.json
• Link to GitHub issue for previous review sessions, if applicable: N/A

We request to split the API definitions of Fleets resources from the existing ContainerService (AKS) APIs to :

• provide a clearer separation
• remove friction in the api versioning release
• remove friction in the release and maintenance of the related artifacts (sdks and CLI)

The proposal for the API definition is to stay under specification/containerservice/resource-manager/Microsoft.ContainerService but to add a fleet and an aks folder to group and isolate the api definitions and their respective versions:

screenshot from this PR : Azure/azure-rest-api-specs#21259 which was abandoned to first seek this approval.

About the client library

• Name of the client library: Currently, the Fleet control plane api and SDK are part of the AKS ContainerService Client. (ref API definition linked above.).

The resulting client libraries for all AKS APIs would not be impacted.
The resulting client libraries for Fleet APIs require a separate namespace.

New Namespace for fleet SDKs

language	namespaces	approved
go	(new for fleet) sdk/resourcemanager/containerservice/armcontainerservicefleet (existing aks) sdk/resourcemanager/containerservice/armcontainerservice	✅
python	(new for fleet) sdk/containerservice/azure-mgmt-containerservicefleet (existing aks) sdk/containerservice/azure-mgmt-containerservice	✅
.net	(new for fleet) Azure.ResourceManager.ContainerService.Fleet  (existing aks) Azure.ResourceManager.ContainerService	✅
typescript	(new for fleet) @azure/arm-containerservicefleet (existing aks) @azure/arm-containerservice	✅ (js)
nodejs	(new for fleet) azure-arm-containerservicefleet (existing aks) azure-arm-containerservice	✅
java	(new for fleet) com.microsoft.azure.management.containerservicefleet (existing aks) com.microsoft.azure.management.containerservice (new for fleet) com.azure.resourcemanager.containerservicefleet (existing aks) com.azure.resourcemanager.containerservice	✅

• Languages for this review: all

Artifacts required (per language)

Please read through “API Review” section here to understand how these artifacts are generated. It is critical that these artifacts are present and are in the right format. If not, the language architects cannot review them with the SDK Team’s API review tool.

.NET

• APIView Link: N/A (fleet is not in .net SDK yet)
• Link to Champion Scenarios/Quickstart samples: N/A

Java

• APIView Link: N/A (fleet is not in Java yet)
• Link to Champion Scenarios/Quickstart samples: N/A

Python

• APIView Link:
  • containerservice/v2022_09_02_preview/operations/_fleets_operations.py
  • containerservice/v2022_09_02_preview/operations/_fleet_members_operations.py
• Link to Champion Scenarios/Quickstart samples: N/A

TypeScript

• APIView Link: N/A
• Link to Champion Scenarios/Quickstart samples: N/A

For all other languages, send a request to the Architecture Board to discuss the best format on individual basis.

Thank you!

[ronniegeraghty]

@serbrech wanted to clarify here. Is this a request to approve proposals for MGMT Plane namespaces?

[serbrech]

Yes. I had an extensive email thread running with input from the different sdk owners that I can forward if needed.

[bterlson]

@azure/arm-containerservicefleet is fine for JS.

[m-nash]

dotnet is fine with Azure.ResourceManager.ContainerServiceFleet

[JeffreyRichter]

The proposal is good for Go.

[JonathanGiles]

Can I get more clarity on Java? I see you are proposing the following:

(new for fleet) com.microsoft.azure.management.containerservicefleet
(existing aks) com.microsoft.azure.management.containerservice

I note that all other languages are using the 'track two' naming pattern, but for Java I see the 'track one' com.microsoft.azure naming pattern being used. I'm not sure why the existing AKS library is in the 'track one' name space, whereas for all other languages it is 'track two'?

[serbrech]

@JonathanGiles oh, I based it on what I found in the sdk repo.
Could you help me on the naming pattern then? I'm not familiar at all with the Java sdk.
I'm not even sure if AKS has ever generated one for track2.

[annatisch]

azure-mgmt-containerservicefleet should be good for Python.

[JonathanGiles]

@JonathanGiles oh, I based it on what I found in the sdk repo. Could you help me on the naming pattern then? I'm not familiar at all with the Java sdk. I'm not even sure if AKS has ever generated one for track2.

@serbrech There is a 'track two' version of this library, from what I can tell, here: https://mvnrepository.com/artifact/com.azure.resourcemanager/azure-resourcemanager-containerservice

Therefore, I would propose for Java you use the following names, rather than what you proposed above:

(new for fleet) com.azure.resourcemanager.containerservicefleet
(existing aks) com.azure.resourcemanager.containerservice

I also want to note that in your original proposal for .NET, you had a sub-namespace for .fleet, and I note @m-nash commented that he was "fine with Azure.ResourceManager.ContainerServiceFleet", and there is a slight difference there with no sub-namespace in his approval. The same applies for Java here.

[serbrech]

@m-nash could you confirm whether we should use Azure.ResourceManager.ContainerServiceFleet or Azure.ResourceManager.ContainerService.Fleet in the .NET SDK?

I was advised to use a sub namespace by @KrzysztofCwalina

[serbrech]

Missing python still. I missed @annatisch comment :)
is typescript considered different than js, or is your approval valid for both @bterlson ?

I updated the table in the issue with a status column (checkmark) and updated the java namespace following feedback (@JonathanGiles)