Attach a Kubernetes cluster to Azure Machine Learning workspace

APPLIES TO: Azure CLI ml extension v2 (current) Python SDK azure-ai-ml v2 (current)

Once Azure Machine Learning extension is deployed on AKS or Arc Kubernetes cluster, you can attach the Kubernetes cluster to Azure Machine Learning workspace and create compute targets for ML professionals to use.

Prerequisites

Attaching a Kubernetes cluster to Azure Machine Learning workspace can flexibly support many different scenarios. For example, the shared scenarios with multiple attachments, model training scripts accessing Azure resources, and the authentication configuration of the workspace.

Multi-attach and workload isolation

One cluster to one workspace, creating multiple compute targets

  • For the same Kubernetes cluster, you can attach it to the same workspace multiple times and create multiple compute targets for different projects/teams/workloads.

One cluster to multiple workspaces

  • For the same Kubernetes cluster, you can also attach it to multiple workspaces, and the multiple workspaces can share the same Kubernetes cluster.

If you plan to have different compute targets for different projects/teams, you can specify the existed Kubernetes namespace in your cluster for the compute target to isolate workload among different teams/projects.

Important

The namespace you plan to specify when attaching the cluster to Azure Machine Learning workspace should be previously created in your cluster.

Securely access Azure resource from training script

If you need to access Azure resource securely from your training script, you can specify a managed identity for Kubernetes compute target during attach operation.

Attach to workspace with user-assigned managed identity

Azure Machine Learning workspace defaults to having a system-assigned managed identity to access Azure Machine Learning resources. The steps are completed if the system assigned default setting is on.

Otherwise, if a user-assigned managed identity is specified in Azure Machine Learning workspace creation, the following role assignments need to be granted to the managed identity manually before attaching the compute.

Azure resource name Roles to be assigned Description
Azure Relay Azure Relay Owner Only applicable for Arc-enabled Kubernetes cluster. Azure Relay isn't created for AKS cluster without Arc connected.
Kubernetes - Azure Arc or Azure Kubernetes Service Reader
Kubernetes Extension Contributor
Azure Kubernetes Service Cluster Admin
Applicable for both Arc-enabled Kubernetes cluster and AKS cluster.
Azure Kubernetes Service Contributor Required only for AKS clusters that use the Trusted Access feature. The workspace uses user-assigned managed identity. See AzureML access to AKS clusters with special configurations for details.

Tip

Azure Relay resource is created during the extension deployment under the same Resource Group as the Arc-enabled Kubernetes cluster.

Note

  • If the "Kubernetes Extension Contributor" role permission is not available, the cluster attachment fails with "extension not installed" error.
  • If the "Azure Kubernetes Service Cluster Admin" role permission is not available, the cluster attachment fails with "internal server" error.

How to attach a Kubernetes cluster to Azure Machine Learning workspace

We support two ways to attach a Kubernetes cluster to Azure Machine Learning workspace, using Azure CLI or studio UI.

The following CLI v2 commands show how to attach an AKS and Azure Arc-enabled Kubernetes cluster, and use it as a compute target with managed identity enabled.

AKS cluster

az ml compute attach --resource-group <resource-group-name> --workspace-name <workspace-name> --type Kubernetes --name k8s-compute --resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>" --identity-type SystemAssigned --namespace <Kubernetes namespace to run Azure Machine Learning workloads> --no-wait

Arc Kubernetes cluster

az ml compute attach --resource-group <resource-group-name> --workspace-name <workspace-name> --type Kubernetes --name amlarc-compute --resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Kubernetes/connectedClusters/<cluster-name>" --user-assigned-identities "subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>" --no-wait

Set the --type argument to Kubernetes. Use the identity_type argument to enable SystemAssigned or UserAssigned managed identities.

Important

--user-assigned-identities is only required for UserAssigned managed identities. Although you can provide a list of comma-separated user managed identities, only the first one is used when you attach your cluster.

Compute attach won't create the Kubernetes namespace automatically or validate whether the kubernetes namespace existed. You need to verify that the specified namespace exists in your cluster, otherwise, any Azure Machine Learning workloads submitted to this compute will fail.

Assign managed identity to the compute target

A common challenge for developers is the management of secrets and credentials used to secure communication between different components of a solution. Managed identities eliminate the need for developers to manage credentials.

To access Azure Container Registry (ACR) for a Docker image, and a Storage Account for training data, attach Kubernetes compute with a system-assigned or user-assigned managed identity enabled.

Assign managed identity

  • You can assign a managed identity to the compute in the compute attach step.

  • If the compute has already been attached, you can update the settings to use a managed identity in Azure Machine Learning studio.

    • Go to Azure Machine Learning studio. Select Compute, Attached compute, and select your attached compute.
    • Select the pencil icon to edit managed identity.

    Screenshot of updating identity of the Kubernetes compute from Azure portal.

    Screenshot of selecting identity of the Kubernetes compute from Azure portal.

Assign Azure roles to managed identity

Azure offers a couple of ways to assign roles to a managed identity.

If you're using the Azure portal to assign roles and have a system-assigned managed identity, Select User, Group Principal or Service Principal, you can search for the identity name by selecting Select members. The identity name needs to be formatted as: <workspace name>/computes/<compute target name>.

If you have user-assigned managed identity, select Managed identity to find the target identity.

You can use Managed Identity to pull images from Azure Container Registry. Grant the AcrPull role to the compute Managed Identity. For more information, see Azure Container Registry roles and permissions.

You can use a managed identity to access Azure Blob:

  • For read-only purpose, Storage Blob Data Reader role should be granted to the compute managed identity.
  • For read-write purpose, Storage Blob Data Contributor role should be granted to the compute managed identity.

Next steps