Use customer-managed keys with Azure Machine Learning

  • Article

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.

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
Azure Container Instances 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 and Azure Container Instances.

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 keys that you use with Azure Container Instances and Azure Kubernetes Service are provided when you configure those resources.

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 Azure Cosmos DB instance that logs metadata for the workspace.
    Microsoft.Search Azure AI 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 Azure in your subscription can't transfer ownership to you.
  • You can't delete Azure-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.

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:

  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.
  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.cn/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 Container Instance

Important

Deploying to Azure Container Instances is not available in SDK or CLI v2. Only through SDK & CLI v1.

When deploying a trained model to an Azure Container instance (ACI), you can encrypt the deployed resource using a customer-managed key. For information on generating a key, see Encrypt data with a customer-managed key.

To use the key when deploying a model to Azure Container Instance, create a new deployment configuration using AciWebservice.deploy_configuration(). Provide the key information using the following parameters:

  • cmk_vault_base_url: The URL of the key vault that contains the key.
  • cmk_key_name: The name of the key.
  • cmk_key_version: The version of the key.

For more information on creating and using a deployment configuration, see the following articles:

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