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.

Azure CLI

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.

Studio

Attaching a Kubernetes cluster makes it available to your workspace for training or inferencing.

1. Navigate to Azure Machine Learning studio.

2. Under Manage, select Compute.

3. Select the Kubernetes clusters tab.

4. Select +New > Kubernetes

   

5. Enter a compute name and select your Kubernetes cluster from the dropdown.

   • (Optional) Enter Kubernetes namespace, which defaults to default. All machine learning workloads are sent to the specified Kubernetes namespace in the cluster. Compute attach doesn't create the Kubernetes namespace automatically or validate whether the kubernetes namespace exists. You need to verify that the specified namespace exists in your cluster, otherwise, any Azure Machine Learning workloads submitted to this compute would fail.

   • (Optional) Assign system-assigned or user-assigned managed identity. Managed identities eliminate the need for developers to manage credentials. For more information, see the Assign managed identity section of this article.

   

6. Select Attach

   In the Kubernetes clusters tab, the initial state of your cluster is Creating. When the cluster is successfully attached, the state changes to Succeeded. Otherwise, the state changes to Failed.

   

Azure SDK

The following python SDK v2 code shows how to attach an AKS and Azure Arc-enabled Kubernetes cluster, and use it as a compute target with managed identity enabled.

AKS cluster

from azure.ai.ml import load_compute

# for AKS cluster, the resource_id should be something like '/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerService/managedClusters/<CLUSTER_NAME>''
compute_params = [
    {"name": "<COMPUTE_NAME>"},
    {"type": "kubernetes"},
    {
        "resource_id": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerService/managedClusters/<CLUSTER_NAME>"
    },
]
k8s_compute = load_compute(source=None, params_override=compute_params)
ml_client.begin_create_or_update(k8s_compute).result()

Arc Kubernetes cluster

from azure.ai.ml import load_compute

# for arc connected cluster, the resource_id should be something like '/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerService/connectedClusters/<CLUSTER_NAME>''
compute_params = [
    {"name": "<COMPUTE_NAME>"},
    {"type": "kubernetes"},
    {
        "resource_id": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerService/connectedClusters/<CLUSTER_NAME>"
    },
]
k8s_compute = load_compute(source=None, params_override=compute_params)
ml_client.begin_create_or_update(k8s_compute).result()

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.

  

  

Assign Azure roles to managed identity

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

• Use Azure portal to assign roles
• Use Azure CLI to assign roles
• Use Azure PowerShell to assign roles

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

• Create and manage instance types
• Azure Machine Learning inference router and connectivity requirements
• Secure AKS inferencing environment