add azure provider parameters breakdown

Author: viniciusdc

docs/docs/explanations/advanced-provider-configuration.md

@@ -199,9 +199,7 @@ cluster region by inspecting its respective SSM parameters. For more information
 
 <TabItem value="azure" label="Azure">
 
-[Microsoft Azure](https://azure.microsoft.com/) has similar settings for Kubernetes version, region, and instance names - using Azure's available values of course.
-
-Azure also requires a field named `storage_account_postfix` which will have been generated by `nebari init`. This allows nebari to create a Storage Account bucket that should be globally unique.
+[Microsoft Azure](https://azure.microsoft.com/) offers robust support for deploying and managing Kubernetes clusters through Azure Kubernetes Service (AKS). Azure provides a variety of settings for Kubernetes versions, regions, instance types, and more, enabling you to tailor your cluster to meet specific requirements.
 
 ```yaml
 ### Provider configuration ###
@@ -224,6 +222,161 @@ azure:
   storage_account_postfix: t65ft6q5
 ```
 
+:::note
+
+Azure requires a field named `storage_account_postfix`, which is generated by `nebari init`. This ensures the creation of a globally unique Storage Account bucket essential for your deployments.
+:::
+
+### Provider Configuration
+
+The `azure` section in your `nebari-config.yaml` defines the core settings for deploying your Kubernetes cluster on Azure. Below are the available configurations:
+
+- **name** (Required): The name of your Azure Kubernetes cluster.
+- **environment** (Required): The environment context (e.g., development, staging, production).
+- **region** (Required): The Azure region where your resources will be deployed (e.g., `Central US`).
+- **kubernetes_version** (Required): Specifies the Kubernetes version to deploy (e.g., `1.19.11`).
+- **resource_group_name** (Required): The name of the Azure Resource Group that will contain the cluster resources.
+- **node_resource_group_name** (Required): The name of the Resource Group specifically for node-related resources.
+- **vnet_subnet_id** (Optional): The ID of the existing Virtual Network (VNet) subnet where the nodes will be deployed. If not provided, Nebari will create a new VNet.
+- **private_cluster_enabled** (Required): Boolean flag to enable or disable a private AKS cluster. When enabled, the API server is accessible only within the VNet.
+- **tags** (Optional): A dictionary of tags to apply to all Azure resources for easier management and organization.
+- **max_pods** (Optional): Maximum number of pods that can run on a single node.
+- **network_profile** (Optional): Configures network settings for the cluster, including network plugin, service CIDR, DNS service IP, and Docker bridge CIDR.
+- **workload_identity_enabled** (Optional): Enables Azure AD Workload Identity for better security and identity management within the cluster.
+- **azure_rbac** (Optional): Configures Azure Active Directory Role-Based Access Control (RBAC) integration.
+- **storage_account_postfix** (Required): A unique postfix generated by `nebari init` to create a globally unique Storage Account.
+
+### Node Groups
+
+Node groups define the sets of nodes within your Kubernetes cluster, specifying instance types and scaling parameters.
+
+```yaml
+node_groups:
+  general:
+    instance: Standard_D4_v3
+    min_nodes: 1
+    max_nodes: 1
+  user:
+    instance: Standard_D2_v2
+    min_nodes: 0
+    max_nodes: 5
+  worker:
+    instance: Standard_D2_v2
+    min_nodes: 0
+    max_nodes: 5
+```
+
+**Parameters:**
+
+- `instance` (Required): The Azure VM instance type for the node group (e.g., `Standard_D4_v3`).
+- `min_nodes` (Required): The minimum number of nodes in the group.
+- `max_nodes` (Required): The maximum number of nodes in the group.
+
+### Azure Active Directory Role-Based Access Control (RBAC) (Optional)
+
+Integrating Azure AD with Kubernetes RBAC enhances security by managing access through Azure AD identities.
+
+```yaml
+azure_rbac:
+  enabled: true
+  managed_identity: true
+  admin_group_object_ids:
+    - "00000000-0000-0000-0000-000000000000"
+```
+
+**Parameters:**
+
+- `enabled` (Required): Enables or disables Azure AD-based RBAC integration.
+- `managed_identity` (Required): If set to `true`, Azure manages the Service Principal used for integration.
+- `admin_group_object_ids` (Required): A list of Azure AD group Object IDs that will have administrative privileges within the Kubernetes cluster. This is only applicable when `managed_identity` is `true`.
+
+::warning
+This change is irreversible and may impact the cluster's security posture. Ensure that
+you have the necessary permissions and understand the implications before enabling Azure
+AD RBAC. For more information, see [Azure AD integration with AKS](https://learn.microsoft.com/en-us/azure/aks/enable-authentication-microsoft-entra-id).
+:::
+
+### Virtual Network and Subnet (Optional)
+
+Specify an existing Virtual Network subnet for deploying your nodes to ensure network policies and integrations align with your infrastructure.
+
+```yaml
+vnet_subnet_id: "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/my-vnet-group/providers/Microsoft.Network/virtualNetworks/my-vnet/subnets/my-subnet"
+```
+
+**Parameters:**
+
+- `vnet_subnet_id` (Optional): The full Azure Resource Manager (ARM) ID of the subnet where the nodes will be deployed. If not provided, Nebari will create a new VNet and subnet.
+
+### Private Cluster (Optional)
+
+Enable a private AKS cluster to restrict API server access within your Virtual Network, enhancing security.
+
+```yaml
+private_cluster_enabled: true
+```
+
+**Parameters:**
+
+- `private_cluster_enabled` (Required): Set to `true` to enable a private cluster where the Kubernetes API server is accessible only within the VNet.
+
+### Network Profile (Optional)
+
+Customize network settings to fit your organizational requirements.
+
+```yaml
+network_profile:
+  network_plugin: azure
+  service_cidr: "10.0.0.0/16"
+  dns_service_ip: "10.0.0.10"
+  docker_bridge_cidr: "172.17.0.1/16"
+```
+
+**Parameters:**
+
+- `network_plugin` (Optional): Specifies the network plugin to use (e.g., `azure`, `kubenet`).
+- `service_cidr` (Optional): The CIDR range for Kubernetes services.
+- `dns_service_ip` (Optional): The IP address for the DNS service.
+- `docker_bridge_cidr` (Optional): The CIDR range for the Docker bridge.
+
+### Workload Identity (Optional)
+
+Enable Azure AD Workload Identity for improved security and simplified identity management within your cluster.
+
+```yaml
+workload_identity_enabled: true
+```
+
+**Parameters:**
+
+- `workload_identity_enabled` (Optional): Set to `true` to enable Azure AD Workload Identity integration.
+
+### Tags (Optional)
+
+Apply metadata to your Azure resources for better organization and management.
+
+```yaml
+tags:
+  environment: production
+  department: engineering
+```
+
+**Parameters:**
+
+- `tags` (Optional): A dictionary of key-value pairs to tag Azure resources. Useful for categorization, billing, and access control.
+
+### Storage Account Postfix
+
+Azure requires a unique `storage_account_postfix` to create a globally unique Storage Account for your deployments.
+
+```yaml
+storage_account_postfix: t65ft6q5
+```
+
+**Parameters:**
+
+- `storage_account_postfix` (Required): A unique postfix generated by `nebari init`. This ensures that the Storage Account name adheres to Azure’s global uniqueness requirements.
+
 </TabItem>
 
 <TabItem value="existing" label="Existing Kubernetes clusters">