diff --git a/docs/docs/explanations/advanced-provider-configuration.md b/docs/docs/explanations/advanced-provider-configuration.md index db20165b..a7a239ce 100644 --- a/docs/docs/explanations/advanced-provider-configuration.md +++ b/docs/docs/explanations/advanced-provider-configuration.md @@ -19,7 +19,7 @@ Select the provider of your choice: import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - + @@ -199,9 +199,7 @@ cluster region by inspecting its respective SSM parameters. For more information -[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. +