Improving AKS TypeSpec definitions - resolve FIXME comments

specification/containerservice/resource-manager/Microsoft.ContainerService/aks/AgentPool.tsp

@@ -48,21 +48,21 @@ interface AgentPools {
        */
       @header
       ifNoneMatch?: string;
-    },
-    LroHeaders = ArmLroLocationHeader<FinalResult = AgentPool> &
-      Azure.Core.Foundations.RetryAfterHeader
+    }
   >;
 
   /**
    * Deletes an agent pool in the specified managed cluster.
    */
   delete is ArmResourceDeleteWithoutOkAsync<
     AgentPool,
+    LroHeaders = ArmAsyncOperationHeaderWithLocation &
+      Azure.Core.Foundations.RetryAfterHeader,
     Parameters = {
       /**
        * ignore-pod-disruption-budget=true to delete those pods on a node without considering Pod Disruption Budget
        */
-      #suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+      #suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
       @query("ignore-pod-disruption-budget")
       `ignore-pod-disruption-budget`?: boolean;
 
@@ -82,7 +82,7 @@ interface AgentPools {
   /**
    * Aborts the currently running operation on the agent pool. The Agent Pool will be moved to a Canceling state and eventually to a Canceled state when cancellation finishes. If the operation completes before cancellation can take place, a 409 error code is returned.
    */
-  #suppress "@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes" "Keeping both 202 and 204 responses for passing the lintdiff validator. See https://github.com/Azure/azure-openapi-validator/issues/809"
   @action("abort")
   @summary("Aborts last operation running on agent pool.")
   abortLatestOperation is ArmResourceActionAsync<
@@ -112,21 +112,21 @@ interface AgentPools {
   deleteMachines is ArmResourceActionAsyncBase<
     AgentPool,
     AgentPoolDeleteMachinesParameter,
-    ArmAcceptedLroResponse,
+    ArmAcceptedLroResponse<LroHeaders = ArmAsyncOperationHeaderWithLocation &
+      Azure.Core.Foundations.RetryAfterHeader>,
     BaseParameters = Azure.ResourceManager.Foundations.DefaultBaseParameters<AgentPool>
   >;
 
   /**
    * Upgrading the node image version of an agent pool applies the newest OS and runtime updates to the nodes. AKS provides one new image per week with the latest updates. For more details on node image versions, see: https://docs.microsoft.com/azure/aks/node-image-upgrade
    */
-  #suppress "@azure-tools/typespec-azure-resource-manager/lro-location-header" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
   @summary("Upgrades the node image version of an agent pool to the latest.")
   upgradeNodeImageVersion is ArmResourceActionAsyncBase<
     AgentPool,
     void,
     {
       ...AcceptedResponse;
-      ...ArmAsyncOperationHeader<FinalResult = void>;
+      ...ArmCombinedLroHeaders<FinalResult = void>;
       ...Azure.Core.Foundations.RetryAfterHeader;
 
       @body

specification/containerservice/resource-manager/Microsoft.ContainerService/aks/AgentPoolUpgradeProfile.tsp

@@ -54,7 +54,7 @@ interface AgentPoolUpgradeProfiles {
 /**
  * The list of available upgrade versions.
  */
-#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state" "AKS uses custom provisioning states beyond standard ARM states. Using string type for forward compatibility."
 model AgentPoolUpgradeProfileProperties {
   /**
    * The Kubernetes version (major.minor.patch).
@@ -130,6 +130,5 @@ model AgentPoolRecentlyUsedVersion {
   /**
    * The timestamp when this version was last used.
    */
-  // FIXME: (utcDateTime) Please double check that this is the correct type for your scenario.
   timestamp?: utcDateTime;
 }

specification/containerservice/resource-manager/Microsoft.ContainerService/aks/GuardrailsAvailableVersion.tsp

@@ -87,7 +87,7 @@ union GuardrailsSupport {
 /**
  * Whether the version is default or not and support info.
  */
-#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state" "AKS uses custom provisioning states beyond standard ARM states. Using string type for forward compatibility."
 @added(Versions.v2025_10_02_preview)
 model GuardrailsAvailableVersionsProperties {
   /** Whether this is the default version. */

specification/containerservice/resource-manager/Microsoft.ContainerService/aks/JWTAuthenticator.tsp

@@ -18,7 +18,7 @@ namespace Microsoft.ContainerService;
 /**
  * Configuration for JWT authenticator in the managed cluster.
  */
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @parentResource(ManagedCluster)
 @added(Versions.v2025_10_02_preview)
 model JWTAuthenticator
@@ -41,7 +41,7 @@ model JWTAuthenticator
   "The JWT authenticator to create or update."
 );
 
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @armResourceOperations
 @added(Versions.v2025_10_02_preview)
 interface JWTAuthenticators {
@@ -53,7 +53,11 @@ interface JWTAuthenticators {
   /**
    * Creates or updates JWT authenticator in the managed cluster and updates the managed cluster to apply the settings.
    */
-  createOrUpdate is ArmResourceCreateOrReplaceAsync<JWTAuthenticator>;
+  createOrUpdate is ArmResourceCreateOrReplaceAsync<
+    JWTAuthenticator,
+    LroHeaders = ArmLroLocationHeader<FinalResult = JWTAuthenticator> &
+      Azure.Core.Foundations.RetryAfterHeader
+  >;
 
   /**
    * Deletes a JWT authenticator and updates the managed cluster to apply the settings.
@@ -115,7 +119,7 @@ union JWTAuthenticatorProvisioningState {
 /**
  * The properties of JWTAuthenticator. For details on how to configure the properties of a JWT authenticator, please refer to the Kubernetes documentation: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#using-authentication-configuration. Please note that not all fields available in the Kubernetes documentation are supported by AKS. For troubleshooting, please see https://aka.ms/aks-external-issuers-docs.
  */
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @added(Versions.v2025_10_02_preview)
 model JWTAuthenticatorProperties {
   /**
@@ -150,7 +154,7 @@ model JWTAuthenticatorProperties {
 /**
  * The OIDC issuer details for JWTAuthenticator.
  */
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @added(Versions.v2025_10_02_preview)
 model JWTAuthenticatorIssuer {
   /**
@@ -168,7 +172,7 @@ model JWTAuthenticatorIssuer {
 /**
  * The validation rule for JWTAuthenticator.
  */
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @added(Versions.v2025_10_02_preview)
 model JWTAuthenticatorValidationRule {
   /**
@@ -185,7 +189,7 @@ model JWTAuthenticatorValidationRule {
 /**
  * The claim mappings for JWTAuthenticator.
  */
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @added(Versions.v2025_10_02_preview)
 model JWTAuthenticatorClaimMappings {
   /**
@@ -213,7 +217,7 @@ model JWTAuthenticatorClaimMappings {
 /**
  * The claim mapping expression for JWTAuthenticator.
  */
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @added(Versions.v2025_10_02_preview)
 model JWTAuthenticatorClaimMappingExpression {
   /**
@@ -225,13 +229,13 @@ model JWTAuthenticatorClaimMappingExpression {
 /**
  * The extra claim mapping expression for JWTAuthenticator.
  */
-#suppress "@azure-tools/typespec-azure-core/casing-style" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-core/casing-style" "Property name maintained for backward compatibility with existing API versions"
 @added(Versions.v2025_10_02_preview)
 model JWTAuthenticatorExtraClaimMappingExpression {
   /**
    * The key of the extra attribute.
    */
-  #suppress "@azure-tools/typespec-azure-resource-manager/secret-prop" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+  #suppress "@azure-tools/typespec-azure-resource-manager/secret-prop" "The 'key' property refers to the key of an extra claim mapping attribute, not a secret or credential."
   key: string;
 
   /**

specification/containerservice/resource-manager/Microsoft.ContainerService/aks/LoadBalancer.tsp

@@ -56,7 +56,7 @@ interface LoadBalancers {
    */
   delete is ArmResourceDeleteWithoutOkAsync<
     LoadBalancer,
-    LroHeaders = ArmCombinedLroHeaders<FinalResult = void> &
+    LroHeaders = ArmAsyncOperationHeaderWithLocation &
       Azure.Core.Foundations.RetryAfterHeader
   >;
 
@@ -129,7 +129,7 @@ model LoadBalancerProperties {
   /**
    * The current provisioning state.
    */
-  #suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+  #suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state" "AKS uses custom provisioning states beyond standard ARM states. Using string type for forward compatibility."
   @visibility(Lifecycle.Read)
   provisioningState?: string;
 }
@@ -159,7 +159,7 @@ model LabelSelectorRequirement {
   /**
    * key is the label key that the selector applies to.
    */
-  #suppress "@azure-tools/typespec-azure-resource-manager/secret-prop" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+  #suppress "@azure-tools/typespec-azure-resource-manager/secret-prop" "The 'key' property refers to a Kubernetes label selector key, not a secret or credential."
   key?: string;
 
   /**

specification/containerservice/resource-manager/Microsoft.ContainerService/aks/LocationRoutes.tsp

@@ -14,7 +14,7 @@ namespace Microsoft.ContainerService;
 // Location-scoped operation groups
 // =============================================================================
 
-#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "Adding @armResourceOperations would inject an undesired resource-derived tag on these location-scoped operations."
 interface ManagedClustersOperationGroup {
   /**
    * Contains extra metadata on the version, including supported patch versions, capabilities, available upgrades, and details on preview status of the version
@@ -31,7 +31,7 @@ interface ManagedClustersOperationGroup {
   >;
 }
 
-#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details"
+#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "Adding @armResourceOperations would inject an undesired resource-derived tag on these location-scoped operations."
 interface TrustedAccessRolesOperationGroup {
   /**
    * List supported trusted access roles.
@@ -48,7 +48,7 @@ interface TrustedAccessRolesOperationGroup {
   >;
 }
 
-#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "For backward compatibility"
+#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "Adding @armResourceOperations would inject an undesired resource-derived tag on these location-scoped operations."
 @added(Versions.v2025_10_02_preview)
 interface ContainerServiceOperationGroup {
   /**