[AutoPR azure-mgmt-containerservice] Improve AKS Swagger documentation

sdk/containerservice/azure-mgmt-containerservice/_meta.json

@@ -1,7 +1,7 @@
 {
   "autorest": "V2",
   "use": "@microsoft.azure/autorest.python@~4.0.71",
-  "commit": "1f0bb3f63b1664ace42cfdf646d8b2382d7b7b22",
+  "commit": "42a50e3b7864eebf3acc51b5fe739e98afe79c82",
   "repository_url": "https://github.com/Azure/azure-rest-api-specs",
   "autorest_command": "autorest specification/containerservice/resource-manager/readme.md --keep-version-file --multiapi --no-async --python --python-mode=update --python-sdks-folder=/home/vsts/work/1/s/azure-sdk-for-python/sdk [email protected]/autorest.python@~4.0.71 --version=V2",
   "readme": "specification/containerservice/resource-manager/readme.md"

sdk/containerservice/azure-mgmt-containerservice/azure/mgmt/containerservice/v2021_05_01/models/_container_service_client_enums.py

@@ -198,20 +198,20 @@ class ContainerServiceVMSizeTypes(str, Enum):
 
 class OSDiskType(str, Enum):
 
-    managed = "Managed"
-    ephemeral = "Ephemeral"
+    managed = "Managed"  #: Azure replicates the operating system disk for a virtual machine to Azure storage to avoid data loss should the VM need to be relocated to another host. Since containers aren't designed to have local state persisted, this behavior offers limited value while providing some drawbacks, including slower node provisioning and higher read/write latency.
+    ephemeral = "Ephemeral"  #: Ephemeral OS disks are stored only on the host machine, just like a temporary disk. This provides lower read/write latency, along with faster node scaling and cluster upgrades.
 
 
 class KubeletDiskType(str, Enum):
 
-    os = "OS"
-    temporary = "Temporary"
+    os = "OS"  #: Kubelet will use the OS disk for its data.
+    temporary = "Temporary"  #: Kubelet will use the temporary disk for its data.
 
 
 class OSType(str, Enum):
 
-    linux = "Linux"
-    windows = "Windows"
+    linux = "Linux"  #: Use Linux.
+    windows = "Windows"  #: Use Windows.
 
 
 class OSSKU(str, Enum):
@@ -222,32 +222,32 @@ class OSSKU(str, Enum):
 
 class AgentPoolType(str, Enum):
 
-    virtual_machine_scale_sets = "VirtualMachineScaleSets"
-    availability_set = "AvailabilitySet"
+    virtual_machine_scale_sets = "VirtualMachineScaleSets"  #: Create an Agent Pool backed by a Virtual Machine Scale Set.
+    availability_set = "AvailabilitySet"  #: Use of this is strongly discouraged.
 
 
 class AgentPoolMode(str, Enum):
 
-    system = "System"
-    user = "User"
+    system = "System"  #: System agent pools are primarily for hosting critical system pods such as CoreDNS and metrics-server. System agent pools osType must be Linux. System agent pools VM SKU must have at least 2vCPUs and 4GB of memory.
+    user = "User"  #: User agent pools are primarily for hosting your application pods.
 
 
 class Code(str, Enum):
 
-    running = "Running"
-    stopped = "Stopped"
+    running = "Running"  #: The cluster is running.
+    stopped = "Stopped"  #: The cluster is stopped.
 
 
 class ScaleSetPriority(str, Enum):
 
-    spot = "Spot"
-    regular = "Regular"
+    spot = "Spot"  #: 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.
+    regular = "Regular"  #: Regular VMs will be used.
 
 
 class ScaleSetEvictionPolicy(str, Enum):
 
-    delete = "Delete"
-    deallocate = "Deallocate"
+    delete = "Delete"  #: Nodes in the underlying Scale Set of the node pool are deleted when they're evicted.
+    deallocate = "Deallocate"  #: Nodes in the underlying Scale Set of the node pool are set to the stopped-deallocated state upon eviction. Nodes in the stopped-deallocated state count against your compute quota and can cause issues with cluster scaling or upgrading.
 
 
 class GPUInstanceProfile(str, Enum):
@@ -261,38 +261,38 @@ class GPUInstanceProfile(str, Enum):
 
 class LicenseType(str, Enum):
 
-    none = "None"
-    windows_server = "Windows_Server"
+    none = "None"  #: No additional licensing is applied.
+    windows_server = "Windows_Server"  #: Enables Azure Hybrid User Benefits for Windows VMs.
 
 
 class NetworkPlugin(str, Enum):
 
-    azure = "azure"
-    kubenet = "kubenet"
+    azure = "azure"  #: Use the Azure CNI network plugin. See [Azure CNI (advanced) networking](https://docs.microsoft.com/azure/aks/concepts-network#azure-cni-advanced-networking) for more information.
+    kubenet = "kubenet"  #: Use the Kubenet network plugin. See [Kubenet (basic) networking](https://docs.microsoft.com/azure/aks/concepts-network#kubenet-basic-networking) for more information.
 
 
 class NetworkPolicy(str, Enum):
 
-    calico = "calico"
-    azure = "azure"
+    calico = "calico"  #: Use Calico network policies. See [differences between Azure and Calico policies](https://docs.microsoft.com/azure/aks/use-network-policies#differences-between-azure-and-calico-policies-and-their-capabilities) for more information.
+    azure = "azure"  #: Use Azure network policies. See [differences between Azure and Calico policies](https://docs.microsoft.com/azure/aks/use-network-policies#differences-between-azure-and-calico-policies-and-their-capabilities) for more information.
 
 
 class NetworkMode(str, Enum):
 
-    transparent = "transparent"
-    bridge = "bridge"
+    transparent = "transparent"  #: No bridge is created. Intra-VM Pod to Pod communication is through IP routes created by Azure CNI. See [Transparent Mode](https://docs.microsoft.com/azure/aks/faq#transparent-mode) for more information.
+    bridge = "bridge"  #: This is no longer supported
 
 
 class OutboundType(str, Enum):
 
-    load_balancer = "loadBalancer"
-    user_defined_routing = "userDefinedRouting"
+    load_balancer = "loadBalancer"  #: The load balancer is used for egress through an AKS assigned public IP. This supports Kubernetes services of type 'loadBalancer'. For more information see [outbound type loadbalancer](https://docs.microsoft.com/azure/aks/egress-outboundtype#outbound-type-of-loadbalancer).
+    user_defined_routing = "userDefinedRouting"  #: Egress paths must be defined by the user. This is an advanced scenario and requires proper network configuration. For more information see [outbound type userDefinedRouting](https://docs.microsoft.com/azure/aks/egress-outboundtype#outbound-type-of-userdefinedrouting).
 
 
 class LoadBalancerSku(str, Enum):
 
-    standard = "standard"
-    basic = "basic"
+    standard = "standard"  #: Use a a standard Load Balancer. This is the recommended Load Balancer SKU. For more information about on working with the load balancer in the managed cluster, see the [standard Load Balancer](https://docs.microsoft.com/azure/aks/load-balancer-standard) article.
+    basic = "basic"  #: Use a basic Load Balancer with limited functionality.
 
 
 class CreatedByType(str, Enum):
@@ -324,26 +324,26 @@ class ManagedClusterPodIdentityProvisioningState(str, Enum):
 
 class UpgradeChannel(str, Enum):
 
-    rapid = "rapid"
-    stable = "stable"
-    patch = "patch"
-    node_image = "node-image"
-    none = "none"
+    rapid = "rapid"  #: Automatically upgrade the cluster to the latest supported patch release on the latest supported minor version. In cases where the cluster is at a version of Kubernetes that is at an N-2 minor version where N is the latest supported minor version, the cluster first upgrades to the latest supported patch version on N-1 minor version. For example, if a cluster is running version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, your cluster first is upgraded to 1.18.6, then is upgraded to 1.19.1.
+    stable = "stable"  #: Automatically upgrade the cluster to the latest supported patch release on minor version N-1, where N is the latest supported minor version. For example, if a cluster is running version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, your cluster is upgraded to 1.18.6.
+    patch = "patch"  #: Automatically upgrade the cluster to the latest supported patch version when it becomes available while keeping the minor version the same. For example, if a cluster is running version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, your cluster is upgraded to 1.17.9.
+    node_image = "node-image"  #: Automatically upgrade the node image to the latest version available. Microsoft provides patches and new images for image nodes frequently (usually weekly), but your running nodes won't get the new images unless you do a node image upgrade. Turning on the node-image channel will automatically update your node images whenever a new version is available.
+    none = "none"  #: Disables auto-upgrades and keeps the cluster at its current version of Kubernetes.
 
 
 class Expander(str, Enum):
 
-    least_waste = "least-waste"
-    most_pods = "most-pods"
-    priority = "priority"
-    random = "random"
+    least_waste = "least-waste"  #: Selects the node group that will have the least idle CPU (if tied, unused memory) after scale-up. This is useful when you have different classes of nodes, for example, high CPU or high memory nodes, and only want to expand those when there are pending pods that need a lot of those resources.
+    most_pods = "most-pods"  #: Selects the node group that would be able to schedule the most pods when scaling up. This is useful when you are using nodeSelector to make sure certain pods land on certain nodes. Note that this won't cause the autoscaler to select bigger nodes vs. smaller, as it can add multiple smaller nodes at once.
+    priority = "priority"  #: Selects the node group that has the highest priority assigned by the user. It's configuration is described in more details [here](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/expander/priority/readme.md).
+    random = "random"  #: Used when you don't have a particular need for the node groups to scale differently.
 
 
 class ResourceIdentityType(str, Enum):
 
-    system_assigned = "SystemAssigned"
-    user_assigned = "UserAssigned"
-    none = "None"
+    system_assigned = "SystemAssigned"  #: Use an implicitly created system assigned managed identity to manage cluster resources. Master components in the control plane such as kube-controller-manager will use the system assigned managed identity to manipulate Azure resources.
+    user_assigned = "UserAssigned"  #: Use a user-specified identity to manage cluster resources. Master components in the control plane such as kube-controller-manager will use the specified user assigned managed identity to manipulate Azure resources.
+    none = "None"  #: Do not use a managed identity for the Managed Cluster, service principal will be used instead.
 
 
 class ManagedClusterSKUName(str, Enum):
@@ -353,8 +353,8 @@ class ManagedClusterSKUName(str, Enum):
 
 class ManagedClusterSKUTier(str, Enum):
 
-    paid = "Paid"
-    free = "Free"
+    paid = "Paid"  #: Guarantees 99.95% availability of the Kubernetes API server endpoint for clusters that use Availability Zones and 99.9% of availability for clusters that don't use Availability Zones.
+    free = "Free"  #: No guaranteed SLA, no additional charges. Free tier clusters have an SLO of 99.5%.
 
 
 class ExtendedLocationTypes(str, Enum):