Use customer-managed keys with Azure Machine Learning

In the customer-managed keys concepts article, you learned about the encryption capabilities that Azure Machine Learning provides. Now learn how to use customer-managed keys with Azure Machine Learning.

Azure Machine Learning relies on the following services that use customer-managed keys:

Service	What it's used for
Azure Cosmos DB	Stores metadata for Azure Machine Learning
Azure AI Search	Stores workspace metadata for Azure Machine Learning
Azure Storage	Stores workspace metadata for Azure Machine Learning
Azure Kubernetes Service	Hosts trained models as inference endpoints

You use the same key to help secure Azure Cosmos DB, Azure AI Search, and Azure Storage. You can use a different key for Azure Kubernetes Service.

When you use a customer-managed key with Azure Cosmos DB, Azure AI Search, and Azure Storage, the key is provided when you create your workspace. The key that you use with Azure Kubernetes Service is provided when you configure that resource.

Prerequisites

• An Azure subscription.

• The following Azure resource providers must be registered:

  Resource provider	Why it's needed
  Microsoft.MachineLearningServices	Creating the Azure Machine Learning workspace.
  Microsoft.Storage	Storage Account is used as the default storage for the workspace.
  Microsoft.KeyVault	Azure Key Vault is used by the workspace to store secrets.
  Microsoft.DocumentDB/databaseAccounts	Azure Cosmos DB instance that logs metadata for the workspace.
  Microsoft.Search/searchServices	Azure Search provides indexing capabilities for the workspace.

  For information on registering resource providers, see Resolve errors for resource provider registration.

Limitations

• After workspace creation, the customer-managed encryption key for resources that the workspace depends on can only be updated to another key in the original Azure Key Vault resource..
• Resources managed by Microsoft in your subscription can't transfer ownership to you.
• You can't delete Microsoft-managed resources used for customer-managed keys without also deleting your workspace.
• The key vault that contains your customer-managed key must be in the same Azure subscription as the Azure Machine Learning workspace.
• OS disk of machine learning compute can't be encrypted with customer-managed key, but can be encrypted with Microsoft-managed key if the workspace is created with hbi_workspace parameter set to TRUE. For more details, see Data encryption.

Important

When using a customer-managed key, the costs for your subscription will be higher because of the additional resources in your subscription. To estimate the cost, use the Azure pricing calculator.

Create Azure Key Vault

To create the key vault, see Create a key vault. When creating Azure Key Vault, you must enable soft delete and purge protection.

Important

The key vault must be in the same Azure subscription that will contain your Azure Machine Learning workspace.

Create a key

Tip

If you have problems creating the key, it may be caused by Azure role-based access controls that have been applied in your subscription. Make sure that the security principal (user, managed identity, service principal, etc.) you are using to create the key has been assigned the Contributor role for the key vault instance. You must also configure an Access policy in key vault that grants the security principal Create, Get, Delete, and Purge authorization.

If you plan to use a user-assigned managed identity for your workspace, the managed identity must also be assigned these roles and access policies.

For more information, see the following articles:

• Provide access to key vault keys, certificates, and secrets
• Assign a key vault access policy
• Use managed identities with Azure Machine Learning

1. From the Azure portal, select the key vault instance. Then select Keys from the left.

2. Select + Generate/import from the top of the page. Use the following values to create a key:

   • Set Options to Generate.
   • Enter a Name for the key. The name should be something that identifies what the planned use is. For example, my-cosmos-key.
   • Set Key type to RSA.
   • We recommend selecting at least 3072 for the RSA key size.
   • Leave Enabled set to yes.

   Optionally you can set an activation date, expiration date, and tags.

3. Select Create to create the key.

Allow Azure Cosmos DB to access the key

1. To configure the key vault, select it in the Azure portal and then select Access polices from the left menu.
2. To create permissions for Azure Cosmos DB, select + Create at the top of the page. Under Key permissions, select Get, Unwrap Key, and Wrap key permissions.
3. Under Principal, search for Azure Cosmos DB and then select it. The principal ID for this entry is a232010e-820c-4083-83bb-3ace5fc29d0b for all regions other than Azure Government. For Azure Government, the principal ID is 57506a73-e302-42a9-b869-6f12d9ec29e9.
4. Select Review + Create, and then select Create.

Create a workspace that uses a customer-managed key

Create an Azure Machine Learning workspace. When creating the workspace, you must select the Azure Key Vault and the key. Depending on how you create the workspace, you specify these resources in different ways:

Warning

The key vault that contains your customer-managed key must be in the same Azure subscription as the workspace.

• Azure portal: Select the key vault and key from a dropdown input box when configuring the workspace.

• SDK, REST API, and Azure Resource Manager templates: Provide the Azure Resource Manager ID of the key vault and the URL for the key. To get these values, use the Azure CLI and the following commands:

  # Replace `mykv` with your key vault name.
  # Replace `mykey` with the name of your key.
  
  # Get the Azure Resource Manager ID of the key vault
  az keyvault show --name mykv --query id
  # Get the URL for the key
  az keyvault key show --vault-name mykv -n mykey --query key.kid
  

  The key vault ID value will be similar to /subscriptions/{GUID}/resourceGroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/mykv. The URL for the key will be similar to https://mykv.vault.azure.net/keys/mykey/{GUID}.

For examples of creating the workspace with a customer-managed key, see the following articles:

Creation method	Article
CLI	Create a workspace with Azure CLI
Azure portal/ Python SDK	Create and manage a workspace
Azure Resource Manager template	Create a workspace with a template
REST API	Create, run, and delete Azure Machine Learning resources with REST

Once the workspace has been created, you'll notice that Azure resource group is created in your subscription. This group is in addition to the resource group for your workspace. This resource group will contain the Microsoft-managed resources that your key is used with. The resource group will be named using the formula of <Azure Machine Learning workspace resource group name><GUID>. It will contain an Azure Cosmos DB instance, Azure Storage Account, and Azure AI Search.

Tip

• The Request Units for the Azure Cosmos DB instance automatically scale as needed.
• If your Azure Machine Learning workspace uses a private endpoint, this resource group will also contain a Microsoft-managed Azure Virtual Network. This VNet is used to secure communications between the managed services and the workspace. You cannot provide your own VNet for use with the Microsoft-managed resources. You also cannot modify the virtual network. For example, you cannot change the IP address range that it uses.

Important

If your subscription does not have enough quota for these services, a failure will occur.

Warning

Don't delete the resource group that contains this Azure Cosmos DB instance, or any of the resources automatically created in this group. If you need to delete the resource group or Microsoft-managed services in it, you must delete the Azure Machine Learning workspace that uses it. The resource group resources are deleted when the associated workspace is deleted.

For more information on customer-managed keys with Azure Cosmos DB, see Configure customer-managed keys for your Azure Cosmos DB account.

Azure Kubernetes Service

You may encrypt a deployed Azure Kubernetes Service resource using customer-managed keys at any time. For more information, see Bring your own keys with Azure Kubernetes Service.

This process allows you to encrypt both the Data and the OS Disk of the deployed virtual machines in the Kubernetes cluster.

Important

This process only works with AKS K8s version 1.17 or higher.

Next steps

• Customer-managed keys with Azure Machine Learning
• Create a workspace with Azure CLI
• Create and manage a workspace
• Create a workspace with a template
• Create, run, and delete Azure Machine Learning resources with REST